Parameters

The parameter definitions for CSNBKGN.

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

key_form


Direction:	Input
Type:	String

A 4-byte keyword that defines the type of key you want generated. This parameter also specifies if each key should be returned for either operational, importable, or exportable use. The keyword must be in a 4-byte field, left-aligned, and padded with blanks.

The possible key forms are:

Operational (OP): The key is used for cryptographic operations on the local system. Operational keys are protected by master key variants and can be stored in the CCA key storage file or held by applications in internal key tokens.
Importable (IM): The key is stored with a file or sent to another system. Importable keys are protected by importer key-encrypting keys.
Exportable (EX): The key is transported or exported to another system and imported there for use. Exportable keys are protected by exporter key-encrypting keys and cannot be used by CCA verb.

Importable and exportable keys are contained in external key tokens. For more information on key tokens, refer to Key token.

The first two characters refer to key_type_1. The next two characters refer to key_type_2.

The following keywords are allowed: OP, IM, EX, OPIM, OPEX, IMEX, EXEX, OPOP, and IMIM. See Table 1 for their meanings.

Table 1. Keywords for the Key Generate verb key_form parameter
Keywords for the Key Generate verb key_form parameter
Keyword	Description
EX	Return one copy of the key enciphered under an exporter KEK with key usage EXEX.
EXEX	Return two copies of the key, both enciphered under exporter key-encrypting keys with key usage EXEX.
IM	Return one copy of the key enciphered under an importer KEK with key usage IMEX.
IMEX	Return two copies of the key, the first enciphered under an importer KEK with key usage IMEX, and the second under an exporter KEK with key usage IMEX.
IMIM	Return two copies of the key, both enciphered under importer KEKs with key usage IMIM.
OP	Return one copy of the key enciphered under the DES master key.
OPEX	Return two copies of the key, the first enciphered key under the DES master key and the second under an exporter KEK with key usage OPEX.
OPIM	Return two copies of the key, the first enciphered key under the DES master key and the second under an importer KEK with key usage OPIM.
OPOP	Return two copies of the key, both enciphered under the DES master key.

The key forms are defined as follows:

Operational (OP): The key value is enciphered under a master key. The result is placed into an internal key token. The key is then operational at the local system.
Importable (IM): The key value is enciphered under an importer key-encrypting key. The result is placed into an external key token. The key can then be imported later to the local node. This key form cannot be used by any CCA verb.
Exportable (EX): The key value is enciphered under an exporter key-encrypting key. The result is placed into an external key token. The key can then be transported or exported to another system and imported there for use. This key form cannot be used by any CCA verb.

The keys are placed into tokens that the generated_key_identifier_1 and generated_key_identifier_2 parameters identify.

Valid key type combinations depend on the key form. See Table 2 for valid key combinations.

key_length


Direction:	Input
Type:	String

An 8-byte value that defines the length of the key as being 8, 16, 24 or 32 bytes. The keyword must be left-aligned and padded on the right with blanks. You must supply one of the key length values in the key_length parameter.

Note: As of CCA 5.4 and CCA 6.2, this verb supports three-key TDES keys. As a key management service this includes three-key TDES key encrypting keys (KEKs).

Table 2 lists the key lengths used for various key types.

Table 2. Key length values for the Key Generate verb
Key length values for the Key Generate verb
Value	Description	Algorithm
SINGLE or KEYLN8	Single length (8-byte or 64-bit) key	DES
SINGLE-R	Generates a double-length (two-key) Triple-DES key (16 bytes) with replicated key halves, making an effective single-length key (CV bit 40 = B'0'; see the Note at the end of the table). DES only.	DES
DOUBLE or KEYLN16	Double length (16-byte or 128-bit) key	AES or DES
DOUBLE-O	Double length (16-byte or 128-bit) key	DES
TRIPLE	Generates a triple-length (three-key) Triple-DES key (24 bytes) that does not have key parts guaranteed unique (CV bit 40 = B'0'; see the Note at the end of the table).	DES only
TRIPLE-O	Generates a triple-length (three-key) Triple-DES key (24 bytes) that has key parts guaranteed unique (CV bit 40 = B'1';´see the Note at the end of the table).	DES only.
ZEROCV24	Generates a triple-length (three-key) Triple-DES key (24 bytes) for a default DATA key that does not have key parts guaranteed unique. Requires at least one generated key that is in external form. Not valid with key form keyword OP or OPOP. Notes: Each external key is returned in a Version X'01' fixed-length DES key-token, that is, in a key-token that has a control vector valued to binary zeros. If OPIM or OPEX is specified, the internal key is returned in a non-Version X'01' fixed-length DES key-token. The internal key-token has a default control vector for a triple-length DATA key.	DES only.
KEYLN24	Triple length (24-byte or 192-bit) key	AES or DES
KEYLN32	32-byte (256-bit) key	AES
Note: Excluding Version X'01' fixed-length DES key tokens, the key-form bits of a triple-DES control vector can be set so that the key parts are guaranteed unique (that is, not replicated). This control vector setting prevents a double-length or triple-length key that has an effective strength of single length, or a triple-length key that has an effective strength of double length, from masquerading as a stronger Triple-DES key. CCA supports the keyword DOUBLE-O to force the verb to generate a double-length Triple-DES key that has both key parts guaranteed unique. CCA also supports the keyword TRIPLE-O to force the verb to generate a triple-length Triple-DES key that has all three key parts guaranteed unique. Another method to force the verb to generate a Triple-DES key with key parts guaranteed unique is to provide a key token with a control vector that has the required key form bits set. See Key form bits, 'fff' and 'FFF'.

AES keys allow only KEYLN16, KEYLN24, and KEYLN32. To generate a 128-bit AES key, specify key_length as KEYLN16. For 192-bit AES keys specify key_length as KEYLN24. A 256-bit AES key requires a key_length of KEYLN32. All AES keys are DATA keys.

Keys with a length of 32 bytes have four 8-byte key parts. This key length is valid only for AES keys. To generate a 32-byte AES key with four different values to be the basis of each key part, specify key_length as KEYLN32.

To generate a single-length key, specify key_length as SINGLE or KEYLN8.

Double-length (16-byte) keys have an 8-byte left half and an 8-byte right half. Both halves can have identical clear values or not. If you want the same value to be used in both key halves (called replicated key values), specify a key_length of SINGLE, SINGLE-R, or KEYLN8. If you want different values to be the basis of each key half, specify a key_length of DOUBLE or KEYLN16.

Triple-length (24-byte) keys have three 8-byte key parts. This key length is valid for DATA keys only. To generate a triple-length DATA key with three different values to be the basis of each key part, specify a key_length of KEYLN24.

Use SINGLE or SINGLE-R if you want to create a DES transport key that you would use to exchange DATA keys with a PCF system. Because PCF does not use double-length transport keys, specify SINGLE so that the effects of multiple encipherment are nullified.

When generating an AKEK, the key_length parameter is ignored. The AKEK key length (8-byte or 16-byte) is determined by the skeleton token created by the Key Token Build verb and provided in the generated_key_identifier_1 parameter.

The key length specified must be consistent with the key length indicated by the token you supply. For DES keys, this length is a field in the control vector. For AES keys, the length is an explicit field in the token. Table 3 shows the valid key lengths for each key type. An X indicates that a key length is permitted for a key type. A Y indicates that the key generated will be a double-length key with replicated key values. It is preferred that SINGLE-R be used for this result.

Table 3. Key Generate - key lengths for each key type
Key Generate - key lengths for each key type
Key Type	SINGLE (KEYLN8)	SINGLE-R	DOUBLE (KEYLN16)	DOUBLE-O	Triple (KEYLN24)	(KEYLN32)
AESDATA			X		X	X
MAC MACVER	X X	X X	X X	X X
DATA	X	X	X	X	X
DATAM DATAMV			X X	X X
EXPORTER IMPORTER	Y Y	X X	X X	X X
IKEYXLAT OKEYXLAT	Y Y	X X	X X	X X
CIPHER DECIPHER ENCIPHER	X X X		X X X	X X X
IPINENC OPINENC PINGEN PINVER	Y Y Y Y	X X X X	X X X X	X X X X
CVARDEC* CVARENC* CVARPINE* CVARXCVL* CVARXCVR*	X X X X X		X X X X X	X X X X X
DKYGENKY* KEYGENKY*		X X	X X	X X
CIPHERXI CIPHERXL CIPHERXO				X X X

Note: Key types marked with an asterisk (*) are requested through the use of the TOKEN keyword and specifying a proper control vector in a key token.

key_type_1


Direction:	Input
Type:	String

An 8-byte keyword from the following group:


AESDATA      DATA          ENCIPHER      MACVER
AESTOKEN     DATAC         EXPORTER      OKEYXLAT
CIPHER       DATAM         IKEYXLAT      OPINENC
CIPHERXI     DATAMV        IMPORTER      PINGEN
CIPHERXL     DATAXLAT      IPINENC       PINVER
CIPHERXO     DECIPHER      MAC

or the keyword TOKEN.

For information on the meaning of the key types, see Table 1.

Use the key_type_1 parameter for the first, or only key, that you want generated. The keyword must be left-aligned and padded with blanks. Valid type combinations depend on the key form.

If key_type_1 is TOKEN, CCA examines the control vector (CV) field in the generated_key_identifier_1 parameter to derive the key type. When key_type_1 is TOKEN, CCA does not check for the length of the key for DATA keys. Instead, it uses the key_length parameter to determine the length of the key.

Use the AESTOKEN keyword for AES keys, or the TOKEN keyword for DES keys to indicate that the verb should determine the key type from the key token that you supply. For AES, all keys are type AESDATA. For DES, the key type is determined from the control vector in the key tokens. Alternatively, you can specify the key type using keywords shown in Table 1 and Table 2.

Key types can have mandatory key forms. For example, CVARENC keys must be generated in pairs with CVARDEC keys. The reason is that a CVARENC key can only be used for encryption, and without a CVARDEC key you cannot decrypt the data. See Table 1 and Table 2 for valid key type and key form combinations.

key_type_2


Direction:	Input
Type:	String

An 8-byte keyword from the following group:


AESDATA      DATA          ENCIPHER      MACVER
AESTOKEN     DATAC         EXPORTER      OKEYXLAT
CIPHER       DATAM         IKEYXLAT      OPINENC
CIPHERXI     DATAMV        IMPORTER      PINGEN
CIPHERXL     DATAXLAT      IPINENC       PINVER
CIPHERXO     DECIPHER      MAC

or the keyword TOKEN.

For information on the meaning of the key types, see Table 1.

Use the key_type_2 parameter for a key pair, which is shown in Table 2. The keyword must be left-aligned and padded with blanks. Valid type combinations depend on the key form.

If key_type_2 is TOKEN, CCA examines the control vector (CV) field in the generated_key_identifier_2 parameter to derive the key type. When key_type_2 is TOKEN, CCA does not check for the length of the key for DATA keys. Instead, it uses the key_length parameter to determine the length of the key.

If you want only one key to be generated, specify the key_type_2 and kek_key_identifier_2 parameters as binary zeros.

See Table 1 and Table 2 for valid key type and key form combinations.

kek_key_identifier_1


Direction:	Input/Output
Type:	String

An importer or exporter key-encrypting key contained in an internal fixed length symmetric CCA key token, an internal TR31 key token, or a key label of such a token. If you supply a key label that is less than 64-bytes, it must be left-aligned and padded with blanks. kek_key_identifier_1 is required for a key_form value of IM, EX, IMEX, EXEX, or IMIM.

If the key_form value is OP, OPEX, OPIM, or OPOP, the kek_key_identifier_1 is null.

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: T
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: T
TR-31 mode of key use: D

If the NOCV bit is on in the internal key token containing the key-encrypting key, the key-encrypting key itself (not the key-encrypting key variant) is used to encipher the generated key.

Control vectors are explained in Control vector and the NOCV bit is shown in Table 1.

This parameter is not used when generating AES keys, and should point to null key-tokens.

kek_key_identifier_2


Direction:	Input/Output
Type:	String

An importer or exporter key-encrypting key contained in an internal fixed length symmetric CCA key token, an internal TR31 key token, or a key label of such a token. If you supply a key label that is less than 64-bytes, it must be left-aligned and padded with blanks. kek_key_identifier_2 is required for a key_form values of OPIM, OPEX, IMEX, IMIM, or EXEX. This field is ignored for key_form values OP, IM and EX.

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

TR-31 key usage: K0
Algorithm: T
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 OPIM or IMIM:

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

If the NOCV bit is on in the internal key token containing the key-encrypting key, the key-encrypting key itself (not the key-encrypting key variant) is used to encipher the generated key.

Control vectors are explained in Control vector and the NOCV bit is shown in Table 1.

This parameter is not used when generating AES keys, and should point to null key-tokens.

generated_key_identifier_1


Direction:	Input/Output
Type:	String

This parameter specifies either a generated:

Internal key token for an operational key form, or
External key token containing a key enciphered under the kek_key_identifier_1 parameter.

When key_type_1 parameter is AESDATA, the generated_key_identifier_1 parameter is ignored. In this case, it is recommended that the parameter be initialized to 64-bytes of X'00'.

If you specify a key_type_1 of TOKEN, then this field contains a valid token of the key type you want to generate. Otherwise, on input, this parameter must be binary zeros. See key_type_1 for a list of valid key types.

If you specify a key_type_1 of IMPORTER or EXPORTER and a key_form of OPEX, and if the generated_key_identifier_1 parameter contains a valid internal token of the same type, the NOCV bit, if on, is propagated to the generated key token.

The key_type_1 parameter overrides the type in the token.
The key_length parameter overrides the length value in the generated key token.

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

In general, unless you are using the AESTOKEN or TOKEN keyword, you must identify a null key token in the generated key identifier parameters on input.

generated_key_identifier_2


Direction:	Input/Output
Type:	String

This parameter specifies a generated external key token containing a key enciphered under the kek_key_identifier_2 parameter.

If you specify a key_type_2 of TOKEN, then this field contains a valid token of the key type you want to generate. Otherwise, on input, this parameter must be binary zeros. See key_type_1 for a list of valid key types.

The token can be an internal or external token.

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

Using the AESTOKEN or TOKEN keyword in the key type parameters requires that the key tokens already exist when the verb is called, so the information in those tokens can be used to determine the key type. In general, unless you are using the AESTOKEN or TOKEN keyword, you must identify a null key token in the generated key identifier parameters on input.