Key Generate2 (CSNBKGN2)

Edit online

Use the Key Generate2 verb to randomly generate a keyed hash message authentication code (HMAC) key or an AES key. Depending on the key form specified, the verb returns either one or two enciphered copies of the key, each in a variable-length symmetric key-token. Key tokens can be returned to either application storage or AES key storage.

To generate keys that are returned in a fixed-length symmetric key-token, see Key Generate (CSNBKGN).

The CSNBKGN2 verb selectively returns one or two copies of an AES or an HMAC key enciphered under the AES master key or an AES key-encrypting key. Keys enciphered under the master key are immediately usable at the local node.

The verb can create default key tokens, update the key in existing key tokens, or complete skeleton key tokens. You can use the Key Token Build2 verb to build a skeleton key token (see Key Token Build2 (CSNBKTB2).

Note: Variable-length symmetric key tokens have an associated data section that contains clear data. This section is hashed and the hash value is cryptographically bound to its enciphered payload. See Variable-length symmetric key tokens.

To use this verb, specify the following:

  • Two required rule array keywords:
    • a required token algorithm keyword that selects the type of algorithm that the key can be used for (either AES or HMAC)
    • a required key form keyword that selects the number of keys to return, either one or two, and the token type for each key, either internal or external.
  • The number of bits of clear-key data to randomly generate and return encrypted in the generated key or keys
    • AES keys can be 128, 192, or 256 bits
    • HMAC keys can be 80 - 2048 bits

    Any generated key will have the specified key length.

  • The key types of each AES or HMAC key to be returned. A key type of TOKEN indicates that the generated key token provided as input is to be updated.
    Note:
    1. When generating only one copy of the key, use eight space characters for the second key-type variable.
    2. To update an existing key token with a copy of the randomly generated key, specify keyword TOKEN as the key type and identify the key token to be updated using the generated_key_identifier_n parameter.
    3. If the key type is not TOKEN, the generated_key_identifier_n parameter must have a length of zero or point to a null key-token. This results in a key token with default key-usage and key-management fields.
  • The optional key name (label), 64 bytes, of one or both keys that is to be placed in the associated data of the key token; if provided, this data overrides any label in the input generated key token.
  • The optional user-defined associated data, up to 255 bytes, of one or both keys that is to be placed in the associated data of the key token; if provided, this data overrides any user-defined associated data in the input generated key token.
    Note: A user_associated_data_n variable that contains data overrides any user-defined associated data contained in a key token to be updated.
  • A key-encrypting key (KEK) identifier of key type EXPORTER or IMPORTER, contained in an internal variable-length symmetric key-token, for wrapping each external key to be returned.
  • The key identifier for each key to be generated.
Note: This verb supports PCI-HSM 2016 compliant-tagged key tokens.