Key tokens, key labels, and key identifiers

Edit online

Essentially all cryptographic operations employ one or more keys. In CCA, keys are retained within a structure called a key token.

A verb parameter can point to a variable that contains a key token. Generally you do not need to be concerned with the details of a key token. You can deal with it as an entity.

Key tokens are described as either internal, operational, or external, as follows:

Internal: A key token that contains an encrypted key for local use. The cryptographic engine decrypts an internal key to use the key in a local operation. When a key is entered into the system, it is always encrypted if it appears outside the protected environment of the cryptographic engine. The engine has a special key-encrypting key, called a master key. This key is held within the engine to wrap and unwrap locally used keys.
Operational: An internal key token that is complete and ready for use and contains a key that is encrypted under a master key. During entry of a key, the internal key-token can have a flag set indicating the key information is incomplete.
External: A key token that contains a key that is either in the clear or is encrypted by some key-encrypting key other than the master key. Generally, when a key is to be transported from place to place or is to be held for a significant period of time, the key must be encrypted with a transport key. A key wrapped by a (transport) key-encrypting key is designated as being external.
RSA and ECC public-keys are not encrypted values and, when not accompanied by private-key information, are retained in an external key-token.

Internal key tokens can be stored in a file maintained by the directory server. These key tokens are referenced by use of a key label. A key label is an alphanumeric string you place in a variable and reference with a verb parameter.

Parameter descriptions specify how you can provide a key using these terms:

Key token

The parameter must contain a proper key-token structure.

Key label

The parameter must contain a key-label string used to locate a key record in key storage.

Key identifier

The parameter must contain either a key token or a key label. The first byte in the parameter indicates whether it contains a key token or a key label.

X'00': indicates a DES null key-token.
range X'01' - X'1F': indicates that the variable is processed as a key token.
range X'20' - X'FE': indicates that the variable is processed as a key label. There are additional restrictions on the value of a key label.
X'FF': raises an error condition when passed to the API.