Controlling token access and key policy

The PKCS #11 standard was designed for systems that grant access to token information based on a PIN. The standard defines two types of users, the standard user (User) and the security officer (SO), each having its own personal identification number (PIN). The SO can initialize a token (zero the contents) and set the User's PIN. The SO can also access the public objects on the token, but not the private ones. The User has access to the private objects on a token and has the power to change his or her own PIN. The User cannot reinitialize a token. The PIN that a user enters determines which role that user takes. A user can fill both roles by having knowledge of both PINs.

z/OS does not use PINs. Instead, profiles in the SAF CRYPTOZ class control access to tokens. For each token, there are two resources in the CRYPTOZ class for controlling access to tokens:

The resource USER.token-name controls the access of the User role to the token.
The resource SO.token-name controls the access of the SO role to the token.

A user's access level to each of these resources (read, update, or control) determines the user's access level to the token.

There are six possible token access levels. Three are defined by the PKCS #11 standard, and three are unique to z/OS®. The PKCS #11 token access levels are:

User R/O: Allows the user to read the token including its private objects, but the user cannot create new token or session objects or alter existing ones.
User R/W: Allows the user read/write access to the token object including its private objects.
SO R/W: Allows the user to act as the security officer for the token and to read, create, and alter public objects on the token.

The token access levels unique to z/OS are:

Weak SO: A security officer that can modify the CA certificates contained in a token but not initialize the token. (For example, a system administrator who determines the trust policy for all applications on the system.)
Strong SO: A security officer that can add, generate or remove private objects in a token. (For example, a server administrator.)
Weak User: A User that cannot change the trusted CAs contained in a token. (For example, to prevent an end-user from changing the trust policy of his or her token.)

Table 1 shows how a user's access level to a token is derived from the user's access level to a resource in the SAF CRYPTOZ class.

Table 1. Token access levels
CRYPTOZ resource	READ (SAF access level)	UPDATE (SAF access level)	CONTROL (SAF access level)
SO.token-label	Weak SO Can read, create, delete, modify, and use public objects	SO R/W Same ability as Weak SO plus can create and delete tokens	Strong SO Same ability as SO R/W plus can read but not use (see Note2) private objects; create, delete, and modify private objects
USER.token-label	User R/O Can read and use (see Note 2) public and private objects	Weak User Same ability as User R/O plus can create, delete, and modify private and public objects. Cannot add, delete, or modify certificate authority objects	User R/W Same ability as Weak User plus can add, delete, and modify certificate authority objects

Note:

The USER.token-name and SO.token-name profiles will not be checked to determine access to the omnipresent token SYSTOK-SESSION-ONLY. ICSF creates this token to provide PKCS #11 support even if no other token is available to an application. All users will always by considered to have R/W access to this token.
"Use" is defined as any of the following:
- Performing any cryptographic operation involving the key object; for example C_Encrypt
- Searching for key objects using sensitive search attributes
- Retrieving sensitive key object attributes.
The sensitive attribute for a secret key is CKA_VALUE. The sensitive attribute for Diffie Hellman, DSA, and Elliptic Curve private key objects is CKA_VALUE. The sensitive attributes for RSA private key objects are CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, and CKA_COEFFICIENT.
The CRYPTOZ resources can be defined as "RACF®-DELEGATED" if required. For information about delegated resources, see the topic on delegated resources inz/OS Security Server RACF Security Administrator's Guide.
Although the use of generic profiles in the CRYPTOZ class is permitted, you should not use a single generic profile to cover both the SO.token-label and USER.token-label resources. You should not do this, because there are additional resources in the class controlling key policy. (See Guidelines in this topic for FIPSEXEMPT.token-label and CLEARKEY.token-label.) Creating a generic profile that uses generic characters to match both the SO and USER portion of the resource name (for example *.token-label) will also inadvertently match these other resources and can have unintended consequences.
If the CSFSERV class is active, ICSF performs access control checks on the underlying callable services. The user must have READ access to the appropriate CSFSERV class resource. Table 2 lists the resources in the CSFSERV class for token services.

Table 2. Resources in the CSFSERV class for token services
Name of resource	Service	Called by
CSF1TRC	Token or object creation	C_InitToken, C_CreateObject, C_CopyObject
CSF1TRD	Token or object deletion	C_InitToken, C_DestroyObject
CSF1TRL	Token or object find	C_Initialize, C_FindObjects, CSN_FindALLObjects
CSF1SAV	Set object attributes	C_SetAttributeValue
CSF1GAV	Get object attributes	C_GetAttributeValue
CSF1GSK	Generate secret key	C_GenerateKey
CSF1GKP	Generate key pair	C_GenerateKeyPair
CSF1PKS	Private key sign	C_Decrypt, C_DecryptUpdate, C_DecryptFinal, C_Sign, C_SignFinal
CSF1PKV	Public key verify	C_Encrypt, C_EncryptUpdate, C_EncryptFinal, C_Verify, C_VerifyFinal
CSF1SKD	Secret key decrypt	C_Decrypt, C_DecryptUpdate, C_DecryptFinal
CSF1SKE	Secret key encrypt	C_Encrypt, C_EncryptUpdate, C_EncryptFinal
CSFOWH	One-way hash	C_Digest, C_DigestUpdate, C_DigestFinal, C_Sign, C_SignUpDate, C_SignFinal, C_Verify, C_VerifyUpdate, C_VerifyFinal
CSF1WPK	Wrap key	C_Wrapkey
CSF1UWK	Unwrap key	C_Unwrapkey
CSF1HMG	Generate HMAC	C_Sign
CSF1HMV	Verify HMAC	C_Verify
CSF1DVK	Derive key	C_DeriveKey
CSF1DMK	Derive multiple keys	C_DeriveKey
CSFIQA	PKCS #11 initialization	C_Initialize
CSFRNG	Random number generate	C_GenerateRandom

Guidelines:

If your organization controls access to ICSF callable services using the CSFSERV class, define the resources listed in Table 2 and grant access accordingly.
Tip: Define generic profiles. For example, a profile named CSF* covers all the ICSF services. A profile named CSF1* covers the PKCS #11 subset of the ICSF services, with the exception of those covered by the CSFOWH, CSFIQF, and CSFRNG resources.
The CRYPTOZ class supports generic profiles. Take advantage of this by creating a token naming convention for your organization and enforce it with generic profiles. For example, require users and applications to prefix their token names with their user IDs, as with data set names. (See Sample scenario for setting up z/OS PKCS #11 tokens.)
For server applications, grant security officers (server administrators) Strong SO access and their end-users (server daemon user IDs) Weak User or User R/W access.
For applications for which you do not wish to separate the security officer and end-user roles, grant the appropriate user IDs access to both the SO and USER profiles.

In addition to these two resources for controlling access to tokens, each token also has two additional resources in the CRYPTOZ class: FIPSEXEMPT.token-name and CLEARKEY.token-name.

The FIPSEXEMPT.token-name resource is used for identifying applications that are subject to FIPS 140 restrictions when ICSF is running in FIPS compatibility mode. Refer to Operating in compliance with FIPS 140-2 for more information.
The CLEARKEY.token-name resource will be queried to determine the policy for creating a clear in contrast to a secure key when CKA_IBM_SECURE=TRUE has not been specified for key generation. The following table indicates the significance of the different access levels. When there is no matching profile defined, the row indicating RACF access of UPDATE or No Decision is considered, the policy is to base the decision on the key’s sensitivity and whether an Enterprise PKCS #11 coprocessor is available or not.¹

Table 3. CLEARKEY.token-label resource access and key security policy
Key Security Objective	RACF ACCESS	Action taken when PKCS #11 coprocessor not available or algorithm not supported	Action taken when PKCS #11 coprocessor available and algorithm supported
Generate no secure keys. Stay compatible with earlier releases	CONTROL	`Sensitive – Clear Key Non-sensitive – Clear Key`	`Sensitive – Clear Key Non-sensitive – Clear Key`
Use key sensitivity and environment to determine security	UPDATE or No Decision	`Sensitive – Clear Key Non-sensitive – Clear Key`	`Sensitive – Secure Key Non-sensitive – Clear Key`
Ensure keys explicitly marked sensitive are always secure keys	READ	`Sensitive – Denied Non-sensitive – Clear Key`	`Sensitive – Secure Key Non-sensitive – Clear Key`
Prevent generation or creation of any clear keys	NONE	`Sensitive – Denied Non-sensitive – Denied`	`Sensitive – Secure Key Non-sensitive – Secure Key`

Service specific notes:

For generate key and generate key-pair, CLEARKEY.token-label checking is always performed as described above.
For create object, no CLEARKEY.token-label checking is performed. By default, all keys created via create object are clear keys. To get an encrypted key, the caller must specify CKA_IBM_SECURE=TRUE. Such keys are not true secure keys since the sensitive key material has appeared in-the-clear outside the bounds of the secure coprocessor.
For copy object, no CLEARKEY.token-label checking is performed. By default, the source key’s security is carried forward to the target key. Clear keys may be upgraded to encrypted keys by specifying CKA_IBM_SECURE=TRUE.
For unwrap key, the security of the base key always determines the security of the unwrapped key. However, in the case of clear key unwrap, CLEARKEY.token-label checking is performed to see if clear keys are permitted.
For derive key, the base key can be clear or secure. The resulting derived key will be clear. CLEARKEY.token-label checking is performed to see if clear keys are permitted.

General notes:

You should avoid setting a discrete or generic profile that would restrict clear key creation in the omnipresent token. This token is used by other z/OS components to create session keys only. It is typical for session keys to be clear keys. The clear key resource checked for the omnipresent token is CLEARKEY.SYSTOK-SESSION-ONLY.
If no CLEARKEY profile is created to protect a given token, the No Decision row governs the action taken for that token for key creation and generation requests. The action taken depends on whether a PKCS #11 coprocessor is active or not. If no PKCS #11 coprocessor is active, all key creation and generate requests result in clear keys. If a PKCS #11 coprocessor is made active, sensitive keys (CKA_SENSITIVE=TRUE) may be generated as secure keys, depending on the algorithm. This could have an unexpected effect on existing programs.