ACF2 support of secret key for PKCS #11 token

Products

• ACF2 - z/OS

Issue/Introduction

As seen in a page in ACF2 TechDoc , IDTs (Identity Tokens) can be signed or unsigned. In order for the IDT to be signed, the PKCS (Public Key Cryptography Standards) #11 token must have a secret key in ICSF (Integrated Cryptographic Service Facility). An installation can create the secret key by calling CSFPTRC, 

Does ACF2 support secret keys?

Environment

Release : 16.0

Component : ACF2 for z/OS

Cause

 

 

 

Resolution

It is up to the application that is using the P11token to use the the IBM Token Record Create callable service ( CSFPTRC6) functions to insert a secret key. The ESM ( external security manager such as ACF2,Top Secret, RACF) gets called for the authorization check when the CSFPTRC or CSFPTRC6 functions are used.

For example, when Configuring the z/OS system for Zowe section 'Configure signed SAF Identity tokens (IDT)' to use SAF Identity tokens on z/OS, Zowe provides  sample program ZWESECKG in the SZWESAMP dataset to generate a secret key for the PKCS#11 token and then the ESM needs to be configured to define a SAF resource profile under the IDTDATA SAF resource class:

General steps are:

1. Create PKCS#11 token
2. Generate a secret key for the PKCS#11 token ( see the sample program ZWESECKG in the SZWESAMP dataset)
3. Define a SAF resource profile under the IDTDATA SAF resource class

Details with examples can be found in documentation of external security manager products:

• RACF - see "Signed and Unsigned Identity Tokens" and "IDT Configuration" subsections on this page in the z/OS Security Server RACROUTE Macro Reference book.
•     
• Top Secret - see Maintain Identity Token (IDT) Records subsection in Administrating chapter
•  
• ACF2 - IDTDATA Profile Records subsection in Administrating chapter.

It is recommended to check the documentation for the application that is being set up for JWT token authentication. Each application will specify details for insertion of the secret key.

- - - - - - - - - - - - -

When a PKCS #11 Token is created, the CSFPTRC or CSFPTRC6 functions will make a security call for the 'secret key' and the ESM will be called for the resource authorization check. Secret key generation may be done in hardware or software.

IBM's Table 2: Resources in the CSFSERV class for token services shows the CSFSERV resources for CSF1GSK(Generate secret key) and CSF1SKE(Secret key encrypt). For ACF2 the CSFSERV resource class defaults to TYPE(SAF) although it is recommended to INSERT a GSO CLASMAP to map the CSFSERV resource to a unique TYPE code such as CSF.

According to IBM PKCS #11 Token Record Create (CSFPTRC and CSFPTRC6) the authorization uses the CRYPTOZ resource class to control access to tokens. For ACF2 the CRYPTOZ class defaults to TYPE(CRY).

The CRYPTOZ class resources which control access to tokens:

• a token-name which controls the access of the User role to the token.
• a token-name  which controls the access of the SO role to the token.

The PKCS #11 token access authorization required is as follows:

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

For details on IBM PKCS #11 Token Record Create authorizations see IBM Table 1. Authorization requirements for the token record create callable service.