Configuring a PKCS#11 token

PKCS#11 is a programming interface to create and manipulate cryptographic tokens. PKCS#11 tokens are containers that hold digital certificates and keys. TOTP components that run on z/OS® use a PKCS#11 token to generate and manage secret keys, and to perform hash message authentication code (HMAC) operations.

Before you begin

Before you configure a PKCS#11 token, refer to the configuration roadmap in IBM MFA configuration roadmap.

Important: CEXnC cryptographic coprocessor hardware is not required. The IBM MFA ICSF PKCS#11 support can run in software.

ICSF must be installed, configured, and the ICSF started task started, as described in z/OS Cryptographic Services ICSF System Programmer's Guide. This procedure requires a VSAM data set called the token data set (TKDS), which you might have not already configured. You can add a TKDS data set to an existing PKCS#11 configuration.

Important: In a SYSPLEX, the RACF® database and TKDS must be shared across member LPARs. IBM MFA requires the TKDS and the RACF database to be shared across member LPARs in the same manner. If they are not shared identically, errors such as being unable to decrypt shared secret values can occur.

You can add the TKDS data set one LPAR at a time in a SYSPLEX.

About this task

PKCS#11 tokens and objects are stored in the TKDS. The TKDS serves as the repository for persistent cryptographic keys and certificates used by PKCS#11 applications.

This procedure summarizes the steps to create a PKCS#11 token for your convenience. See z/OS Cryptographic Services ICSF Administrator's Guide for complete information.

See the introductory chapter of z/OS Cryptographic Services ICSF System Programmer's Guide for token access information and guidelines.

Access to PKCS#11 tokens in ICSF is controlled by the CRYPTOZ class, with different access levels as well as a differentiation between standard users and security officers. 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 Security Officer (SO) role to the token.

You must create your own PKCS#11 token using RACDCERT ADDTOKEN or the ICSF panels. The token name you specify in this procedure must match the token name you subsequently use with AZFEXEC.

Important: Troubleshooting IBM MFA CRYPTOZ access problems can be difficult if a governing profile does not exist. Under some circumstances, such as when the user ID of the web services started task does not have access to one or more of the profiles in the CRYPTOZ class because the profile does not exist, ICSF can deny a request without issuing an informative ICHnumber error message, leaving only the reason code for guidance.

It is recommended that you create a governing CRYPTOZ class profile with a value of ** with a UACC of NONE. In the absence of a profile that permits access, this restrictive profile causes a message to be output so that you can determine the missing RACF profile.

RDEFINE CRYPTOZ SO.** UACC(NONE)
RDEFINE CRYPTOZ USER.** UACC(NONE)

Procedure

Create the TKDS. A sample job illustrating the definition of the TKDS data set is shipped in SYS1.SAMPLIB, in member CSFTKD2. Copy, edit, and run the sample job to initialize the TKDS data set.
Edit the ICSF installation options data set in the PARMLIB member for the CSF started task. Set the TKDSN or SYSPLEXTKDS directives, as appropriate:
- TKDSN identifies the VSAM data set that contains the token data set.
- SYSPLEXTKDS specifies whether the token data set should have sysplex-wide data consistency. The SYSPLEXTKDS option is in effect only if the TKDSN option has also been specified.
  In a sysplex, the required format of this directive is:
```
SYSPLEXTKDS(YES,FAIL(YES))
```
  where YES specifies that the system is notified of updates made to the TKDS by other members of the sysplex that have also specified SYSPLEXTKDS(YES,FAIL(fail-option)), and FAIL (YES) specifies that ICSF initialization terminates abnormally if there is a failure creating the TKDS latch set.
Create the PKCS#11 token using RACDCERT ADDTOKEN.
```
RACDCERT ADDTOKEN(token_name)
```

Activate the CRYPTOZ class with generics and RACLISTs:

SETROPTS CLASSACT(CRYPTOZ) GENERIC(CRYPTOZ) GENCMD(CRYPTOZ) RACLIST(CRYPTOZ)

Create generic profiles in the CRYPTOZ class.

RDEFINE CRYPTOZ SO.** UACC(NONE) OWNER(userid or group-name)
RDEFINE CRYPTOZ USER.** UACC(NONE) OWNER(userid or group-name)

Create a profile for the web service server's access to the token you created with RACDCERT ADDTOKEN.
```
RDEFINE CRYPTOZ SO.token_name UACC(NONE)
```
Create a profile for the standard user's access to the token you created with RACDCERT ADDTOKEN:
```
RDEFINE CRYPTOZ USER.token_name UACC(NONE)
```
Give the user ID of the web services started task CONTROL access to the profile that protects the token, where AZFWEB is the user ID of the web services started task.
```
PERMIT SO.token_name CLASS(CRYPTOZ) ID(AZFWEB) ACC(CONTROL)
```
Give the user ID of the administrator who executes the panels CONTROL access to the profile that protects the token.
```
PERMIT SO.token_name CLASS(CRYPTOZ) ID(user-ID) ACC(CONTROL)
```
Give the user ID of the IBM MFA services started task UPDATE access to the profile that protects the token, where AZFSTC is the user ID of the IBM MFA services started task.
```
PERMIT USER.token_name CLASS(CRYPTOZ) ID(AZFSTC) ACC(UPDATE)
```
Give the user ID of the web services started task UPDATE access to the profile that protects the token, where AZFWEB is the user ID of the web services started task.
```
PERMIT USER.token_name CLASS(CRYPTOZ) ID(AZFWEB) ACC(UPDATE)
```
Give the user ID of the administrator who executes the panels UPDATE access to the profile that protects the token.
```
PERMIT USER.token_name CLASS(CRYPTOZ) ID(user-ID) ACC(UPDATE)
```

Create the CLEARKEY.token-name resource profile.

RDEFINE CRYPTOZ CLEARKEY.token_name UACC(NONE)

Give the user ID of the administrator who executes the panels READ access to the profile.
```
PERMIT CLEARKEY.token_name CLASS(CRYPTOZ) ID(user-ID) ACC(READ)
```
Give the user ID of the IBM MFA services started task READ access to the profile that protects the token, where AZFSTC is the user ID of the IBM MFA services started task.
```
PERMIT CLEARKEY.token_name CLASS(CRYPTOZ) ID(AZFSTC) ACC(READ)
```
Refresh the profile for the CRYPTOZ class, so that the changes take effect:
```
SETROPTS RACLIST(CRYPTOZ) REFRESH
```