Key Generate2 (CSNBKGN2 and CSNEKGN2)

CALL CSNBKGN2(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             clear_key_bit_length,
             key_type_1,
             key_type_2,
             key_name_1_length,
             key_name_1,
             key_name_2_length,
             key_name_2,
             user_associated_data_1_length,
             user_associated_data_1,
             user_associated_data_2_length,
             user_associated_data_2,
             key_encrypting_key_identifier_1_length,
             key_encrypting_key_identifier_1,
             key_encrypting_key_identifier_2_length,
             key_encrypting_key_identifier_2,
             generated_key_identifier_1_length,
             generated_key_identifier_1,
             generated_key_identifier_2_length,
             generated_key_identifier_2 )

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return/reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. ICSF and cryptographic coprocessor return/reason codes lists the reason codes.

exit_data_length

Direction	Type
Input/Output	Integer

The length of the data that is passed to the installation exit. The data is identified in the exit_data parameter.

exit_data

Direction	Type
Input/Output	String

The data that is passed to the installation exit.

rule_array_count

Direction	Type
Input	Integer

The number of keywords you supplied in the rule_array parameter. Valid values are 2, 3 or 4.

rule_array

Direction	Type
Input	String

The rule_array contains keywords that provide control information to the callable service. The keywords must be in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on the right with blanks.

Table 1. Keywords for Key Generate2 Control Information

Keyword	Meaning
Token algorithm (required)
HMAC	Specifies to generate an HMAC key token.
AES	Specifies to generate an AES key token.
Key Form (required) The first two characters refer to key_type_1. The next two characters refer to key_type_2. See the Usage Notes section for further details.
EX	One key that can be sent to another system.
EXEX	A key pair; both keys to be sent elsewhere, possibly for exporting to two different systems. Both keys have the same clear value.
IM	One key that can be locally imported. The key can be imported onto this system to make it operational at another time.
IMEX	A key pair to be imported; one key to be imported locally and one key to be sent elsewhere. Both keys have the same clear value.
IMIM	A key pair to be imported; both keys to be imported locally at another time. Both keys have the same clear value.
OP	One operational key. The key is returned to the caller in operational form to be used locally.
OPEX	A key pair; one key that is operational and one key to be sent elsewhere. Both keys have the same clear value.
OPIM	A key pair; one key that is operational and one key to be imported locally at another time. Both keys have the same clear value.
OPOP	A key pair; either with the same key type with different associated data or complementary key types. Both keys have the same clear value.
Payload Version for generated_key_identifier_1 (one, optional) Note: This keyword overrides payload format version of any corresponding skeleton token.
V0PYLDK1	Build a token with the old variable-length payload format for the generated_key_identifier_1 parameter. This is the default for AES CIPHER, EXPORTER, and IMPORTER key types and is only valid with those key types.
V1PYLDK1	Build a token with the new fixed-length payload format for the generated_key_identifier_1 parameter. This is the default for AES MAC, PINPROT, PINCALC, PINPRW, and DKYGENKY key types. Not valid with the HMAC MAC key type.
Payload Version for generated_key_identifier_2 (one, optional) Note: This keyword overrides payload format version of any corresponding skeleton token.
V0PYLDK2	Build a token with the old variable-length payload format for the generated_key_identifier_2 parameter. This is the default for AES CIPHER, EXPORTER, and IMPORTER key types and is only valid with those key types.
V1PYLDK2	Build a token with the new fixed-length payload format for the generated_key_identifier_2 parameter. This is the default for AES MAC, PINPROT, PINCALC, PINPRW, and DKYGENKY key types. Not valid with the HMAC MAC key type.

clear_key_bit_length

Direction	Type
Input	Integer

The size (in bits) of the key to be generated.

• For the HMAC algorithm, this is a value between 80 and 2048, inclusive.
• For the AES algorithm, this is a value of 128, 192, or 256.

When key_type_1 or key_type_2 is TOKEN, this value overrides the key length contained in generated_key_identifier_1 or generated_key_identifier_2, respectively.

key_type_1

Direction	Type
Input	String

Use the key_type_1 parameter for the first, or only, key that you want generated. The keyword must be left-justified and padded with blanks. Valid type combinations depend on the key form, and are documented in Table 4 and Table 5.

The 8-byte keyword for the key_type_1 parameter can be one of the following:

Table 2. Keywords and associated algorithms for key_type_1 parameter

Keyword	Algorithm
CIPHER	AES
EXPORTER	AES
IMPORTER	AES
MAC	HMAC
MACVER	HMAC
Specify the keyword TOKEN when supplying a key token in the generated_key_identifier_1 parameter.

If key_type_1 is TOKEN, the associated data in the generated_key_identifier_1 parameter is examined to derive the key type.

key_type_2

Direction	Type
Input	String

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

The 8-byte keyword for the key_type_2 parameter can be one of the following:

Table 3. Keywords and associated algorithms for key_type_2 parameter

Keyword	Algorithm
CIPHER	AES
EXPORTER	AES
IMPORTER	AES
MAC	HMAC
MACVER	HMAC
Specify the keyword TOKEN when supplying a key token in the generated_key_identifier_2 parameter.

If key_type_2 is TOKEN, the associated data in the generated_key_identifier_2 parameter is examined to derive the key type.

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

key_name_1_length

Direction	Type
Input	Integer

The length of the key_name parameter for generated_key_identifier_1. Valid values are 0 and 64 bytes.

key_name_1

Direction	Type
Input	String

A 64-byte key store label to be stored in the associated data structure of generated_key_identifier_1.

key_name_2_length

Direction	Type
Input	Integer

The length of the key_name parameter for generated_key_identifier_2. Valid values are 0 and 64 bytes.

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

key_name_2

Direction	Type
Input	String

A 64-byte key store label to be stored in the associated data structure of generated_key_identifier_2.

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

user_associated_data_1_length

Direction	Type
Input	Integer

The length of the user-associated data parameter for generated_key_identifier_1. The valid values are 0 to 255 bytes.

user_associated_data_1

Direction	Type
Input	String

User-associated data to be stored in the associated data structure for generated_key_identifier_1.

user_associated_data_2_length

Direction	Type
Input	Integer

The length of the user-associated data parameter for generated_key_identifier_2. The valid values are 0 to 255 bytes.

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

user_associated_data_2

Direction	Type
Input	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	Type
Input	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 64 bytes when key_encrypting_key_identifier_1 is a label. Otherwise, the value must be between the actual length of the token and 9992 bytes.

key_encrypting_key_identifier_1

Direction	Type
Input/Output	String

The identifier of the key-encrypting key to wrap the generated key 1 when the key form indicates an external key is generated. The key identifier is a variable-length operational key token or key block or the label of an operational token or block in key storage.

When key_encrypting_key_identifier_1_length is zero, this parameter is ignored.

For CCA key, the identifier is a variable-length AES key token of key type EXPORTER or IMPORTER with key management attributes enable to allow the key to wrap the type of key being generated.

For X9.143 key blocks, the identifier is a key block of an AES key-encrypting key: key usage K0, algorithm A, and mode of use D or E.

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

key_encrypting_key_identifier_2_length

Direction	Type
Input	Integer

The length of the buffer for key_encrypting_key_identifier_2 in bytes.

When the Key Form rule is OPOP, this length must be zero.

When the Key Form rule is EXEX, IMEX, IMIM, OPIM, or OPEX, the value must be 64 when key_encrypting_key_identifier_2 is a label. Otherwise, the value must be between the actual length of the token and 9992.

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

key_encrypting_key_identifier_2

Direction	Type
Input/Output	String

The identifier of the key-encrypting key to wrap the generated key 2 when the key form indicates an external key is generated. The key identifier is a variable-length operational key token or key block or the label of an operational token or block in key storage.

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

For CCA key, the identifier is a variable-length AES key token of key type EXPORTER or IMPORTER with key management attributes enable to allow the key to wrap the type of key being generated.

For X9.143 key blocks, the identifier is a key block of an AES key-encrypting key: key usage K0, algorithm A, and mode of use D or E.

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

generated_key_identifier_1_length

Direction	Type
Input/Output	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 will hold the actual length of the generated_key_identifier_1.

generated_key_identifier_1

Direction	Type
Input/Output	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 justified in the buffer. See key_type_1 for a list of 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	Type
Input/Output	Integer

On input, the length of the buffer for the generated_key_identifier_2 in 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	Type
Input/Output	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 justified in the buffer. See key_type_2 for a list of 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.

The following tables list the valid key type and key form combinations and required access control points.

The key usage attributes that are shown are those that are required. Key usage attributes that are not shown are optional. When key usage attributes are not the default values for a key type, a skeleton key token with the desired attributes must be supplied and a key type must be TOKEN.

The key types marked with an asterisk (*) must be requested through the specification of a proper key usage field in a key token and the use of the TOKEN keyword.

The key types marked with an asterisk (*) must be requested through the specification of a proper key usage field in a key token and the use of the TOKEN keyword.

Table 5. Key Generate2 valid key types and key forms for two AES or HMAC keys

key_type_1 (key usage)	key_type_2 (key usage)	Key Form OPOP OPIM IMIM	Key Form OPEX	Key Form EXEX	Key Form IMEX
CIPHER (DECRYPT, ENCRYPT)	CIPHER (DECRYPT, C-XLATE)	X	X	X	X
CIPHER (DECRYPT, ENCRYPT)	CIPHER (DECRYPT, ENCRYPT, C-XLATE)	X	X	X	X
CIPHER (DECRYPT, ENCRYPT)	CIPHER (ENCRYPT, C-XLATE)	X	X	X	X
CIPHER (DECRYPT)	CIPHER (ENCRYPT, C-XLATE)	X	X	X	X
CIPHER (DECRYPT, C-XLATE)	CIPHER (DECRYPT, ENCRYPT)	X	X	X	X
CIPHER (DECRYPT, ENCRYPT, C-XLATE)	CIPHER (DECRYPT, ENCRYPT)	X	E	X	E
CIPHER (ENCRYPT, C-XLATE)	CIPHER (DECRYPT, ENCRYPT)	X	E	X	E
CIPHER (ENCRYPT, C-XLATE)	CIPHER (DECRYPT)	X	E	X	E
CIPHER (DECRYPT, C-XLATE)	CIPHER (ENCRYPT)	X	E	X	E
CIPHER (DECRYPT, ENCRYPT, C-XLATE)	CIPHER (DECRYPT, ENCRYPT, C-XLATE)		E	X	E
CIPHER (DECRYPT, C-XLATE)	CIPHER (ENCRYPT, C-XLATE)		E	X	E
CIPHER (ENCRYPT, C-XLATE)	CIPHER (DECRYPT, C-XLATE)		E	X	E
*DKYGENKY	*DKYGENKY	X	X	X	X
*DKYGENKY (D-MAC:MMSAUTH1)	*DKYGENKY (D-MAC:MMSAUTH2)		X
EXPORTER	IMPORTER		X	X	X
IMPORTER	EXPORTER		X	X	X
*KDKGENKY (KDKTYPEA)	*KDKGENKY (KDKTYPEB)		X	X	X
*KDKGENKY (KDKTYPEB)	*KDKGENKY (KDKTYPEA)		X	X	X
MAC (GENERATE)	MAC (GENERATE)	X	X	X	X
MAC (GENERATE)	MAC (VERIFY)	X	X	X	X
MAC (GENERATE)	MAC (GENONLY)	X	X	X	X
MAC (GENONLY)	MAC (GENERATE)	X	X	X	X
MAC (GENONLY)	MAC (VERIFY)	X	X	X	X
MAC (VERIFY)	MAC (GENERATE)	X	X	X	X
MAC (VERIFY)	MAC (GENONLY)	X	X	X	X
PINPROT(ENCRYPT, NOFLDFMT)	PINPROT(DECRYPT, NOFLDFMT)	E	X	X	X
PINPROT(DECRYPT, NOFLDFMT)	PINPROT(ENCRYPT, NOFLDFMT)	E	X	X	X
PINPROT(ENCRYPT, NOFLDFMT)	PINPROT(ENCRYPT, NOFLDFMT)	X
PINPROT (DECRYPT, NOFLDFMT, ISO-4, EPINVER)	PINPROT (ENCRYPT, NOFLDFMT, ISO-4, REFORMAT)	OPOP only1
PINPROT (ENCRYPT, NOFLDFMT, ISO-4, REFORMAT)	PINPROT (DECRYPT, NOFLDFMT, ISO-4, EPINVER)	OPOP only1

¹ Requires access control point Key Generate2 - Allow GEN of OPOP EPVR/OPIN Key Pair.

For AES keys, the AES KEK must be at least as strong as the key being generated to be considered sufficient strength.

For HMAC keys, the AES KEK must be sufficient strength as described in the following table.

If ICSF is configured to audit the lifecycle of tokens [AUDITKEYLIFECKDS(TOKEN(YES),...) is specified], an additional request is made to the Crypto Express coprocessor to generate the key fingerprint to be used for auditing the generated key.

The following table shows the access control points in the domain role that control the function of this service.

Table 9. Required access control points for Key Generate2

Access Control Point	Function control
Key Generate2 - Allow GEN of OPOP EPVR/OPIN Key Pair	Generation of OPOP EPVR/OPIN key pair.
Key Generate2 - OP	Key Form OP, EX, IM.
Key Generate2 - Key set	The key-form and key-type combinations shown with an X in Table 5 and Table 7.
Key Generate2 - Key set extended	The key-form and key-type combinations shown with an E in Table 5.
Key Generate2 - DK PIN key set	The key-form and key-type combinations shown with an D in Table 7.
Key Generate2 - DK PIN admin1 set PINPROT	The key-form and key-type combinations shown with an D1P in Table 7.
Key Generate2 - DK PIN admin1 set MAC	The key-form and key-type combinations shown with an D1M in Table 7.
Key Generate2 - DK PIN print key	The key-form and key-type combinations shown with an DP in Table 7.
Key Generate2 - DK PIN admin2 set MAC	The key-form and key-type combinations shown with an D2 in Table 7.
Key Generate2 - Allow AES DKYGENKY keys with MMSAUTH	Key Generation of AES DKYGENKY D-MAC keys with MMSAUTH1 or MMSAUTH2 key usage fields.
Key Generate2 - Disallow AES keys with PTR2AUTH	Key Generation of AES keys with PTR2AUTH key usage field.
Prohibit weak wrapping - Transport keys	Prohibit wrapping a key with a weaker key.
Warn when weak wrap - Transport keys	Issue a non-zero reason code when using a weak wrapping key.

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. The CCA releases used in the table are described in CCA release levels.