Key token

Edit online

CCA supports two types of symmetric key tokens, fixed-length and variable-length.

An AES or DES fixed-length token is a 64-byte field composed of a key value and control information in the control vector. An HMAC key token is a variable-length token composed of a key value and control information. The control information is assigned to the key when the coprocessor 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, CCA can do the following:
  • 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 CCA system that created it or another CCA 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 verbs such as those listed below. The verbs are described in detail in Managing AES, DES, and HMAC cryptographic keys.
  • AES Key Record Read
  • Clear Key Import
  • Data Key Import
  • DES Key Record Read
  • Key Generate
  • Key Generate2
  • Key Import
  • Key Part Import
  • Key Part Import2
  • Key Token Build
  • Key Token Build2
  • Multiple Clear Key Import
  • Symmetric Key Import2

The master key could be dynamically changed between the time that you invoke a verb, such as the Key Import verb, to obtain a key token, and the time that you pass the key token to the Encipher verb. When a change to the master key occurs, the coprocessor will still successfully use the key, because it stores a copy of the old master key as well as the new one.

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. A return code of 0 with a reason code of 10001 notifies you that the master key used to decrypt the key used in your operation was an old master key, as a reminder that you should use one of the Key Token Change verbs to re-encipher your key under the current or new master key (as desired, see verbs for description).

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 verbs such as those listed below. They are described in detail in Managing AES, DES, and HMAC cryptographic keys.
  • Key Generate
  • Key Export
  • Data Key Export
  • Symmetric Key Export

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 key from a system that cannot produce external key tokens. That is, if you have an 8 or 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 verb to get the key in operational form.

For debugging information, see Key token formats for the format of internal, external, or null key tokens.