Key token

ICSF supports two formats of symmetric key tokens: fixed-length and variable-length. The fixed-length format token is a 64-byte field composed of a key value and control information in the control vector. The variable-length format token is composed of a key value and control information in the associated data section of the token. The control information is assigned to the key when ICSF creates the key. The key token can be either an internal key token, an external key token, or a null key token. Through the use of key tokens, ICSF can:

Support continuous operation across a master key change
Control use of keys in cryptographic services

If the first byte of the key identifier is X'01', the key identifier is interpreted as an internal key token. An internal key token is a token that can be used only on the ICSF system that created it (or another ICSF system with the same host master key). It contains a key that is encrypted under the master key.

An application obtains an internal key token by using one of the callable services such as those listed here. The callable services are described in detail in Managing Symmetric Cryptographic Keys.

CKDS Key Record Read and CKDS Key Record Read2
Clear Key Import and Multiple Clear Key Import
Data Key Import
Key Generate and Key Generate2
Key Import
Key Part Import and Key Part Import2
Key Token Build and Key Token Build2
Secure Key Import, Multiple Secure Key Import, and Secure Key Import2
Symmetric Key Import2
TR-31 Import

The master keys may be dynamically changed between the time that you invoke a service, such as the key import callable service to obtain a key token, and the time that you pass the key token to the encipher callable service. When a change to the master key occurs, ICSF reenciphers the caller's key from under the old master key to under the new master key. A Return Code of 0 with a reason code of 10000 notifies you that ICSF reenciphered the key. For information on reenciphering the CKDS or the PKDS, see z/OS Cryptographic Services ICSF Administrator's Guide.

Attention: If an internal key token held in user storage is not used while the master key is changed twice, the internal key token is no longer usable. (See Other considerations for additional information.)

For debugging information, see Key Token Formats for the format of an internal key token.

If the first byte of the key identifier is X'02', the key identifier is interpreted as an external key token. By using the external key token, you can exchange keys between systems. It contains a key that is encrypted under a key-encrypting key.

An external key token contains an encrypted key and control information to allow compatible cryptographic systems to:

Have a standard method of exchanging keys
Control the use of keys through the control vector
Merge the key with other information needed to use the key

An application obtains the external key token by using one of the callable services such as these listed. They are described in detail in Managing Symmetric Cryptographic Keys.

Key Generate and Key Generate2
Key Export
Data Key Export
Symmetric Key Export and Symmetric Key Export with Data

For debugging information, see Key Token Formats for the format of an external key token.

If the first byte of the key identifier is X'00', the key identifier is interpreted as a null key token. Use the null key token to import a DES key from a system that cannot produce external key tokens into a fixed-length format token. That is, if you have an 8- to 16-byte key that has been encrypted under an importer key, but is not imbedded within a token, place the encrypted key in a null key token and then invoke the key import callable service to get the key in operational form.

For debugging information, see Key Token Formats for the format of a null key token.

ICSF supports the TR-31 key block for communication with systems that do not use CCA key tokens. The TR-31 Export callable service is used to export CCA operational tokens to TR-31 key blocks. The TR-31 Import callable service is used to import TR-31 key blocks to CCA operational tokens.