Storing PassTicket keys encrypted in ICSF

ICSF can be used to store PassTicket keys in the CKDS, encrypted under the master key. Using ICSF ensures the maximum possible security for the PassTicket keys.

For legacy PassTickets, there are two options for defining the key to ICSF:

• Use the SSIGNON operand and the KEYLABEL keyword to identify the CKDS key label to use for the particular PTKTDATA profile being added or altered. The key must refer to a DES key with a type of DATA and a length of 8 bytes. KEYLABEL is the recommended option as it allows for secure key entry and the use of your own naming convention for keys. You are responsible for adding the appropriate key to the CKDS, with the specified label, before it is used in a PassTicket operation.
• Use the SSIGNON operand and KEYENCRYPTED keyword to enter the key value to use for the particular PTKTDATA profile being added or altered. RACF® will generate a key label value in the form IRR.SSIGNON.sysname.mmddyyyy.hhmmss.nnnnnn and add the key to the CKDS. The key label name is not user configurable.

For enhanced PassTickets, the key must be defined in ICSF:

• Use the SSIGNON operand and the EPTKEYLABEL keyword to identify the CKDS key label to use for the particular PTKTDATA profile being added or altered.
• The key label must refer to an ICSF HMAC key with a key algorithm of HMAC, a key type of MAC and the key usage fields must indicate GENERATE. The supported HMAC key size range is from 32 to 256 bytes. The recommended minimum key size is 64 bytes.
• You are responsible for adding the appropriate key to the CKDS with the specified label, before it is used in a PassTicket operation.
• The RACF enhanced PassTicket support uses ICSF HMAC keys which require that the ICSF CKDS is defined in either the variable length record format or common record format (KDSR). For more information on ICSF CKDS formats, please refer to Introduction to z/OS ICSF in z/OS Cryptographic Services ICSF System Programmer's Guide.

The RLIST command displays the key label used for an encrypted key.

When the SSIGNON segment is displayed, the output will indicate which fields apply to legacy PassTickets and which apply to enhanced PassTickets.

When the RACF database is shared, the use of ICSF is simplest when the CKDS and RACF database are shared across a common set of systems. RACF always uses the local system's CKDS when generating or evaluating a PassTicket. If the PassTicket is generated on one system, and then evaluated on a different system, the evaluation will fail if RACF is unable to retrieve the key from the local CKDS. If the ICSF CKDS is not shared across systems which share the RACF database, ICSF services must be used to export the key label from the system on which the PassTicket key was defined. The key must then be imported to the ICSF CKDS of all other systems which share the RACF database. The ICSF CSNDSYX and CSNDSYI services can be used to export and import PassTicket keys from the ICSF CKDS. The ICSF CSNBKEX and CSNBKIM services can also be used to export and import PassTicket keys from the ICSF CKDS. There is a similar consideration if you are using the remote sharing facility to propagate commands that update PTKTDATA class profiles. If the target of the propagation is a multisystem node, the CKDS in use on the remote node's MAIN system will be the only CKDS updated with the new PassTicket key.

Note that older versions of RACF might have stored a legacy PassTicket key token in the profile instead of a key label. The creation of a legacy PassTicket key token is also possible if the user entering the RACF command lacks authorization to the CSFKEYS profile protecting the key label name, or to the CSFKRC or CSFKRW service. Like a normal KEYENCRYPTED key, a key token is also encrypted under the CKDS master key, but it is stored in RACF instead of the CKDS, and thus there is no key label. RACF updates the key token when a master key change is detected. RACF only updates a key token when it is used in a PassTicket operation. If the master key is changed twice between use of a specific key token, the key token is rendered unusable. When the RACF database is shared, and the CKDS is not shared across the generating and evaluating systems, the CKDS master keys must be the same.

The RLIST command will indicate the presence of a legacy PassTicket key token. You can use the ENCRYPTKEY keyword of the RALTER command to move this token into the CKDS using a RACF-generated key label name. See Converting legacy PassTicket masked keys to encrypted keys.

Important: RACF does not delete keys from the CKDS. Before deleting or changing an encrypted key, take note of the current key label value so that it can be deleted from the CKDS, using ICSF interfaces.