Configure 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.

Before you begin

ICSF must be installed, configured, and the ICSF started task started, as described in z/OS Cryptographic Services ICSF System Programmer's Guide.

Table 1 summarizes the required resource profile access for IBM® HTTP Server - Powered by Apache.

Table 1. Resource Profiles
Resource Profile	Class	Web Server User ID
BPX.DAEMON	FACILITY	UPDATE
BPX.SERVER	FACILITY	UPDATE
CLEARKEY.`TOKEN_NAME`	CRYPTOZ	READ
CSF1HMG	CSFSERV	READ
CSF1GSK	CSFSERV	READ
CSF1SKD	CSFSERV	READ
CSF1SKE	CSFSERV	READ
CSF1TRC	CSFSERV	READ
CSF1TRL	CSFSERV	READ
CSFIQA	CSFSERV	READ
CSFOWH	CSFSERV	READ
CSFRNG	CSFSERV	READ
CSFRNGL	CSFSERV	READ
IRR.DIGTCERT. LISTRING	FACILITY	READ UPDATE is needed if TLS is configured for the web server
SO.`TOKEN_NAME`	CRYPTOZ	CONTROL
USER.`TOKEN_NAME`	CRYPTOZ	UPDATE

Note: If the web server is configured with SSL/TLS, the web server user ID requires access to additional profiles, such as CSFDSG, CSF1DVK, CSF1GKP, CSF1GAV, CSF1TRD, and CSFPKI. See IBM HTTP Server Powered by Apache (https://publibz.boulder.ibm.com/epubs/pdf/dpr1cg00.pdf) for information on configuring SSL/TLS for the web server.

For example:

PERMIT CSFRNG CLASS(CSFSERV) ID(user-ID) ACC(READ)
SETROPTS RACLIST(CSFSERV) REFRESH

Note: If you create CSF.CSFSERV.AUTH.CSFOWH.DISABLE or CSF.CSFSERV.AUTH.CSFRNG.DISABLE profiles in the XFACILIT class, the respective SAF checks are disabled, even if the CSFSERV class profiles exist.

See Configuring CSFSERV Resource Profiles for additional resource profile settings when the ICSF CHECKAUTH(YES) parameter is set.

About this task

PKCS #11 tokens and objects are stored in a VSAM data set called the token data set (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 Writing PKCS #11 Applications 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 create the PKCS#11 token to be used by the IBM HTTP Server - Powered by Apache web server using RACDCERT ADDTOKEN. The token name you specify in this procedure must match the token name you subsequently specify in your httpd.conf file and other configuration files included in the configuration.

Note: The PKCS#11 tokens configured for use by IBM HTTP Server - Powered by Apache should not be used for any other purpose including, being referenced in any of the factor settings configured by running the AZFEXEC exec.

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 server 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 CSFTKDS. 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:
Important: You can add a TKDS data set to an existing PKCS#11 configuration. The TKDS data set must be shared in a SYSPLEX. You can add the TKDS data set one LPAR at a time in a SYSPLEX.
- 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.

Activate the CRYPTOZ class with generics and RACLISTs:

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

Create generic profiles in the CRYPTOZ class.

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

Create a profile for the IBM HTTP web server's access to the token.
```
RDEFINE CRYPTOZ SO.TOKEN_NAME UACC(NONE)
```
Create a profile for the standard user's access to the token:
```
RDEFINE CRYPTOZ USER.TOKEN_NAME UACC(NONE)
```
Give the web server CONTROL access to the profile that protects the token, where web-server-user-ID is the user ID of the IBM HTTP web server started task.
```
PERMIT SO.TOKEN_NAME CLASS(CRYPTOZ) ID(web-server-user-ID) ACC(CONTROL)
```
Give the same user UPDATE access to the profile that protects the token, where web-server-user-ID is the user ID of the IBM HTTP web server started task.
```
PERMIT USER.TOKEN_NAME CLASS(CRYPTOZ) ID(web-server-user-ID) ACC(UPDATE)
```
Refresh the profile for the CRYPTOZ class, so that the changes take effect:
```
SETROPTS RACLIST(CRYPTOZ) REFRESH
```
Give the same user READ access to the IRR.DIGTCERT.LISTRING profile in the FACILITY class, where user-ID is the user ID of the IBM HTTP web server started task.
```
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(user-ID) ACCESS(READ)
```
Refresh the FACILITY class:
```
SETROPTS RACLIST(FACILITY) REFRESH
```