Parameters

Edit online

The parameter definitions for CSNBKGN2.

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count
Direction: Input
Type: Integer
The number of keywords you supplied in the rule_array parameter. This value must be 2, 3, or 4.
rule_array
Direction: Input
Type: String array
The rule_array contains keywords that provide control information to the verb. The keywords must be in contiguous storage with each of the keywords left-aligned in its own 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for Key Generate2 control information

Keywords for Key Generate2 control information
Keyword Description
Token algorithm (One required)
AES Specifies to generate an AES key token.
HMAC Specifies to generate an HMAC key token.
Key form (One, required) The first two characters refer to key_type_1. The next two characters refer to key_type_2. See Usage notes for details.
EX Return one copy of the key enciphered under an exporter KEK with key usage GEN-EXEX.
EXEX Return two copies of the key, both enciphered under exporter key-encrypting keys with key usage GEN-EXEX.
IM Return one copy of the key enciphered under an importer KEK with key usage GEN-IMEX.
IMEX Return two copies of the key, the first enciphered under an importer KEK with key usage GEN-IMEX, and the second under an exporter KEK with key usage GEN-IMEX.
IMIM Return two copies of the key, both enciphered under importer KEKs with key usage GEN-IMIM.
OP Return one copy of the key enciphered under the AES master key.
OPEX Return two copies of the key, the first enciphered key under the AES master key and the second under an exporter KEK with key usage GEN-OPEX.
OPIM Return two copies of the key, the first enciphered key under the AES master key and the second under an importer KEK with key usage GEN-OPIM.
OPOP Return two copies of the key, both enciphered under the AES master key.
Payload Version for generated_key_identifier_1 (one, optional)
Note: If TOKEN is specified for key_type_1, the payload format version is determined by the information in the key token identified by the generated_key_identifier_1 parameter unless specifically overridden by one of the following keywords.
V0PYLDK1 Return a key token identified by the generated_key_identifier_1 parameter with a payload formatted using the less secure legacy variable-length version 0 format. This is the default if the key_type_1 variable is not valued to TOKEN and the key type is AES CIPHER, AES EXPORTER, AES IMPORTER, or HMAC MAC. Only valid with those key types.
V1PYLDK1 Return a key token using the generated_key_identifier_1 parameter with a payload formatted using the more secure fixed-length version 1 format. This is the default if the key_type_1 variable is not valued to TOKEN and the key type is not AES CIPHER, AES EXPORTER, AES IMPORTER, or HMAC MAC. Not valid with HMAC MAC.
Note: This option produces a key token that is not compatible with releases before Release 4.4.
Payload Version for generated_key_identifier_2 (one, optional when generating a key pair, otherwise not allowed)
Note: If TOKEN is specified for key_type_2 when generating a key pair, the payload format version is determined by the information in the key token identified by the generated_key_identifier_2 parameter unless specifically overridden by one of the following keywords.
V0PYLDK2 Return a key token identified by the generated_key_identifier_2 parameter with a payload formatted using the original variable-length version 0 format. This is the default if the key_type_2 variable is not valued to TOKEN and the key type is AES CIPHER, AES EXPORTER, AES IMPORTER, or HMAC MAC. Only valid with those key types.
V1PYLDK2 Return a key token using the generated_key_identifier_2 parameter with a payload formatted using the more secure fixed-length version 1 format. This is the default if the key_type_2 variable is not valued to TOKEN and the key type is not AES CIPHER, AES EXPORTER, AES IMPORTER, or HMAC MAC. Not valid with HMAC MAC.
Note: This option produces a key token that is not compatible with releases before Release 4.4.
clear_key_bit_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of clear-key bits to randomly generate and return encrypted in the generated key or keys. If a generated key token has a key type of TOKEN, this value overrides any key length contained in the key token. The value can be 128, 192, and 256 for AES keys, and 80 - 2048 for HMAC keys.
key_type_1, key_type_2
Direction: Input
Type: String
The key_type_1 and key_type_2 parameters are pointers to 8-byte string variables, each containing a keyword that is left aligned and padded on the right with space characters. The keyword specifies the key type of the key being generated. If a single copy of the key is being generated, set the key_type_2 variable to eight space characters.

The verb returns each copy of the generated key in a default key token that it builds, or updates a key token that is provided. Keyword TOKEN indicates that the verb is to return an updated key token that contains the key-usage and key-management fields of the key token that is provided by the corresponding key_identifier_1 or key_identifier_2 parameter. A keyword other than TOKEN indicates that a null key-token is provided and that the verb is to build and return a default key-token for the specified key type (AES key types CIPHER, EXPORTER, or IMPORTER only).

Valid type combinations depend on the key form, and are documented in Table 1 and Table 2.

The 8-byte keyword for the key_type_1 or key_type_2 parameters can be one of the following:

Table 2. Keywords and associated algorithms for key_type_1/2 parameter

Keywords and associated algorithms for key_type_1/2 parameter
Keyword Algorithm
CIPHER AES
EXPORTER AES
IMPORTER AES
MAC AES or HMAC
MACVER HMAC
Specify the keyword TOKEN when supplying a key token in the generated_key_identifier_1/2 parameter.

If key_type_1 or key_type_2 is TOKEN, the associated data in the generated_key_identifier_1 or generated_key_identifier_2 parameter is used to derive the key type.

key_name_1_length
Direction: Input
Type: Integer
The length of the key_name parameter for generated_key_identifier_1. Valid values are 0 and 64.
key_name_1
Direction: Input
Type: String
A pointer to a string variable containing the optional key label that is placed in the associated data of the key token identified by the generated_key_identifier_1 variable. If present, it must be a valid key label. This data is cryptographically bound to the first copy of the key.
key_name_2_length
Direction: Input
Type: Integer
The length of the key_name parameter for generated_key_identifier_2. Valid values are 0 and 64. When only one key is being generated, set this value to 0.
key_name_2
Direction: Input
Type: String
A pointer to a string variable containing the optional key label that is placed in the associated data of the key token identified by the generated_key_identifier_2 variable. If present, it must be a valid key label. This data is cryptographically bound to the first copy of the key.

When only one key is being generated, this parameter is ignored.

user_associated_data_1_length
Direction: Input
Type: Integer
The length of the user-associated data parameter for generated_key_identifier_1. The valid values are 0 - 255 bytes.
user_associated_data_1
Direction: Input
Type: String
User-associated data to be stored in the associated data structure for generated_key_identifier_1.
user_associated_data_2_length
Direction: Input
Type: Integer
The length of the user-associated data parameter for generated_key_identifier_2. The valid values are 0 - 255 bytes. When only one key is being generated, this parameter is ignored.
user_associated_data_2
Direction: Input
Type: String
User associated data to be stored in the associated data structure for generated_key_identifier_2.

When only one key is being generated, this parameter is ignored.

key_encrypting_key_identifier_1_length
Direction: Input
Type: Integer
The length of the buffer for key_encrypting_key_identifier_1 in bytes. When the key form rule is OP, OPOP, OPIM, or OPEX, this length must be zero. When the key form rule is EX, EXEX, IM, IMEX, or IMIM, the value must be between the actual length of the token and 9992 bytes when key_encrypting_key_identifier_1 is a token.

The value must be 64 bytes when key_encrypting_key_identifier_1 is a label.

key_encrypting_key_identifier_1
Direction: Input
Type: String
When key_encrypting_key_identifier_1_length is zero, this parameter is ignored. Otherwise, key_encrypting_key_identifier_1 contains an internal CCA or TR-31 key token containing the AES importer or exporter key-encrypting key, or a key label.

When using a TR-31 token, it must have the following attributes for a key_form value of EX or EXEX:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: E

When using a TR-31 token, it must have the following attributes for a key_form value of IM, IMEX, or IMIM:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: D

If the token supplied was encrypted under the old master key, the token will be returned encrypted under the current master key.

key_encrypting_key_identifier_2_length
Direction: Input
Type: Integer
The length of the buffer for key_encrypting_key_identifier_2 in bytes. When the key form rule is OP, IM, EX, or OPOP, this length must be zero. When the key form rule is EXEX, IMEX, IMIM, OPIM, or OPEX, the value must be between the actual length of the token and 9992 when key_encrypting_key_identifier_2 is a token. The value must be 64 when key_encrypting_key_identifier_2 is a label.

When only one key is being generated, this parameter is ignored.

key_encrypting_key_identifier_2
Direction: Input/Output
Type: String
When key_encrypting_key_identifier_2_length is zero, this parameter is ignored. Otherwise, key_encrypting_key_identifier_2 contains an internal CCA or TR-31 key token containing the AES importer or exporter key-encrypting key, or a key label.

When using a TR-31 token, it must have the following attributes for a key_form value of EXEX, IMEX, or OPEX:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: E

When using a TR-31 token, it must have the following attributes for a key_form value of IMIM or OPIM:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: D

If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.

When only one key is being generated, this parameter is ignored.

generated_key_identifier_1_length
Direction: Input/Output
Type: Integer
On input, the length of the buffer for the generated_key_identifier_1 parameter in bytes. The maximum value is 900 bytes.

On output, the parameter holds the actual length of the generated_key_identifier_1.

generated_key_identifier_1
Direction: Input/Output
Type: String
The buffer for the first generated key token.

On input, if you specify a key_type_1 of TOKEN, then the buffer contains a valid key token of the key type you want to generate. The key token must be left-aligned in the buffer. Otherwise, this parameter must be binary zeros. See key_type_1, key_type_2 for valid key types.

On output, the buffer contains the generated key token.

To generate a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.

generated_key_identifier_2_length
Direction: Input/Output
Type: Integer
On input, the length of the buffer for the generated_key_identifier_2 in bytes. The minimum value is 120 bytes and the maximum value is 725 bytes. The maximum value is 900 bytes.

On output, the parameter will hold the actual length of the generated_key_identifier_2.

When only one key is being generated, this parameter is ignored.

generated_key_identifier_2
Direction: Input/Output
Type: String
The buffer for the second generated key token.

On input, if you specify a key_type_2 of TOKEN, then the buffer contains a valid key token of the key type you want to generate. The key token must be left-aligned in the buffer. Otherwise, this parameter must be binary zeros. See key_type_1, key_type_2 for valid key types.

On output, the buffer contains the generated key token.

When only one key is being generated, this parameter is ignored

To generate a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.