z/OS Cryptographic Services ICSF Administrator's Guide
Previous topic | Next topic | Contents | Index | Contact z/OS | Library | PDF


Enabling access authority checking for key tokens

z/OS Cryptographic Services ICSF Administrator's Guide
SA22-7521-17

Profiles in the CSFKEYS class determine access authority to cryptographic keys. However, CSFKEYS profiles protect keys by their key label (discrete or generic CSFKEYS profiles are named to match one or more key labels), and ICSF callable services accept either a key label or key token. By default, if an application passes a callable service a key token instead of a key label, no authorization checking is done on the use of the key. By enabling Key Token Authorization Checking controls, you can have ICSF identify a key token's associated key label so that a SAF authorization check can be performed. This lets you implement a consistent security policy for keys regardless of how they are identified (by key label or key token) to callable services.

Separate Key Token Authorization Checking controls are provided for activating the checking for either a CKDS or a PKDS in either warning or fail mode. In warning mode, authorization checking is performed, but an application will not be prevented from using a token even when the user lacks the necessary authority. Instead, ICSF will merely log an SMF type 82 subtype 25 record in the SMF data set. Warning mode allows you to identify users who will need access permission to a key prior to moving to a stricter implementation of the Key Token Authorization Checking policy.

This stricter implementation of the policy is called fail mode. In fail mode, an application will be denied access to a token when the user does not have authority to access it. The operation will be unsuccessful, and a return code 8, reason code BF7 (3063) will be returned to the calling application. As with warning mode, ICSF will log an SMF type 82 subtype 25 record in the SMF data set. In addition, RACF will log an SMF type 80 record (with event code qualifier of ACCESS). The resource name in the SMF type 80 record will be the first label associated with the key token that failed the check.

Because the same token could be associated with multiple key records in the key store, when an application passes an encrypted key token to an ICSF callable service, ICSF locates all the labels associated with the passed token. If the user has permission to any of the key labels, then the application is granted authority to use the token. Because access authority to any label associated with a token will give a user access to the token, you may want to ensure that the key store does not contain multiple key records for the same key token. ICSF provides a utility program, CSFDUTIL, that generates a report of all duplicate keys for either a CKDS or PKDS. To prevent duplicate keys from being added to a key store, you can enable the Default Key Label Checking control for either the CKDS or PKDS as described in Enabling duplicate key label checking.

If ICSF can not find an associated key label for the passed token in the key store, no authorization checking will be performed on the use of the key unless the Default Key Label Checking control is enabled for the key store. If the Default Key Label Checking control is enabled (as described in Determining access to tokens not stored in the CKDS or PKDS), a default profile will determine user access when ICSF cannot identify an associated label for the passed token.

The following table shows the controls for enabling Key Token Authorization Checking for the CKDS and PKDS in either warning or fail mode. To enable one of the Key Token Authorization Checking controls, create the appropriate profile in the XFACILIT class.

Table 6. Key Store Policy controls: The Key Token Authorization Checking controls
The existence of this resource profile in the XFACILIT class: Does this:
CSF.CKDS.TOKEN.CHECK.LABEL.WARN Activates Key Store Policy for CKDS. Enables Key Token Authorization Checking for the CKDS in warning mode. In this mode, a failing authorization check will result in a warning, but the operation will be allowed to continue.
CSF.CKDS.TOKEN.CHECK.LABEL.FAIL Activates Key Store Policy for CKDS. Enables Key Token Authorization Checking for the CKDS in fail mode. In this mode, ICSF does not allow the operation to continue when the authorization check fails. The service returns with an error.
CSF.PKDS.TOKEN.CHECK.LABEL.WARN Activates Key Store Policy for PKDS. Enables Key Token Authorization Checking for the PKDS in warning mode. In this mode, a failing authorization check will result in a warning, but the operation will be allowed to continue.
CSF.PKDS.TOKEN.CHECK.LABEL.FAIL Activates Key Store Policy for PKDS. Enables Key Token Authorization Checking for the PKDS in fail mode. In this mode, ICSF does not allow the operation to continue when the authorization check fails. The service returns with an error.

For example, say you want to enable Key Token Authorization Checking for both a CKDS and a PKDS. You're not certain all the users currently accessing key tokens in these key stores will have the necessary access authority, and do not want to disrupt current work patterns at your installation. For this reason, you decide to allow a warning period during which you can identify users who will need permission to access certain key tokens. The following commands will enable Key Token Authorization Checking for the CKDS and the PKDS in warning mode.

RDEFINE XFACILIT CSF.CKDS.TOKEN.CHECK.LABEL.WARN 
RDEFINE XFACILIT CSF.PKDS.TOKEN.CHECK.LABEL.WARN
SETROPTS RACLIST(XFACILIT) REFRESH

During the warning period, you can, by examining the SMF type 82 subtype 25 records logged in the SMF data set, identify the users who need permission to access keys. You can then create or modify the necessary profiles in the CSFKEYS class. When you are ready to move to a stricter implementation of this policy, you enable the controls for fail mode and disable the ones for warning mode.

RDEFINE XFACILIT CSF.CKDS.TOKEN.CHECK.LABEL.FAIL
RDEFINE XFACILIT CSF.PKDS.TOKEN.CHECK.LABEL.FAIL
RDELETE XFACILIT CSF.CKDS.TOKEN.CHECK.LABEL.WARN
RDELETE XFACILIT CSF.PKDS.TOKEN.CHECK.LABEL.WARN
SETROPTS RACLIST(XFACILIT) REFRESH

If you accidentally enable the Key Token Authorization Checking controls for both warning and fail mode, the control for fail mode will take precedence.

Determining access to tokens not stored in the CKDS or PKDS

When the Key Token Authorization Checking control for a key store has been enabled, and a token is passed to a callable service, ICSF will find the key label(s) associated with the passed token so that a SAF authority check can be performed. If, however, the token passed to the callable service is not in the key store, there will be no associated key label to find. By default, no authorization checking is performed on the use of the key, and the operation is allowed. If you enable the Default Key Label Checking control for the CKDS or PKDS, however, ICSF will use a default profile to determine user access to tokens that are not in the key store.

Separate controls are provided for enabling Default Key Label Checking for a CKDS or a PKDS, The Default Key Label Checking control will be enabled only if the Key Token Authorization Checking control for the appropriate key store is also enabled. Refer to Enabling access authority checking for key tokens for more information. To enable one the Default Key Label Checking controls, create the appropriate profile in the XFACILIT class.

Table 7. Key Store Policy controls: The Default Key Label Checking controls
The existence of this resource profile in the XFACILIT class: Does this:
CSF.CKDS.TOKEN.CHECK.DEFAULT.LABEL Specifies that ICSF should use the default profile CSF-CKDS-DEFAULT in the CSFKEYS class to determine user access to tokens that are not stored in the CKDS. This control is enabled only if the CSF.CKDS.TOKEN.CHECK.LABEL.WARN or CSF.CKDS.TOKEN.CHECK.LABEL.FAIL control is also enabled.
CSF.PKDS.TOKEN.CHECK.DEFAULT.LABEL Specifies that ICSF should use the default profile CSF-PKDS-DEFAULT in the CSFKEYS class to determine user access to tokens that are not stored in the PKDS. This control is enabled only if the CSF.PKDS.TOKEN.CHECK.LABEL.WARN or CSF.PKDS.TOKEN.CHECK.LABEL.FAIL control is also enabled.

For example, to enable the Default Key Label Checking control for a CKDS, you would:

  1. Create the default profile CSF-CKDS-DEFAULT in the CSFKEYS class.
    RDEFINE CSFKEYS CSF-CKDS-DEFAULT UACC(NONE)
  2. By defining the universal access authority (UACC) as NONE in the preceding step, the use of key tokens that do not reside in the key store has been prohibited. If necessary, however, you can give appropriate users (preferably groups) access in the CSF-CKDS-DEFAULT profile and refresh the CSFKEYS class in storage:
    PERMIT CSF-CKDS-DEFAULT CLASS(CSFKEYS) ID(group-id) ACCESS(READ)
    SETROPTS RACLIST(CSFKEYS) REFRESH
  3. Create a profile for the CSF.CKDS.TOKEN.CHECK.DEFAULT.LABEL resource in the XFACILIT class, and refresh the XFACILIT class in storage.
    RDEFINE XFACILIT CSF.CKDS.TOKEN.CHECK.DEFAULT.LABEL
    SETROPTS RACLIST(XFACILIT) REFRESH

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014