Parameters

The parameter definitions for CSNBDKG2.

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

A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 1, 2, or 3.

rule_array


Direction:	Input
Type:	String array

A pointer to a string variable containing an array of keywords that provide control information to the verb. The rule_array keywords for CSNBDKG2 are described in Table 1.

Table 1. Keywords for Diversified Key Generate2 control information
Keyword for Diversified Key Generate2 control information
Keyword	Description
*Diversification Process* (One required)
KDFFM-DK	Specifies to use the DK version of Key Derivation Function (KDF) in Feedback Mode (NIST SP 800-108), as specified in DK Kryptographie Teil 1: Empfohlene kryptographische Algorithmen, to generate a bank specific Issuer Master Key. The generated Issuer Master Key (keying material) can be used to derive an ICC master key. This method uses AES CMAC to encipher up to 2048 bytes of derivation data with the k-bit diversified key generating key (banking association specific master key) to produce a k-bit generated Bank specific Issuer Master Key, where k = 128, 192, or 256.
MK-OPTC	Specifies to use the EMV Master Key Derivation Option C, as specified in EMV Integrated Circuit Card Specifications for Payments Systems, to generate an ICC master key. The generated ICC master key (keying material) can be used for Application Cryptogram generation or verification, issuer authentication, and secure messaging. This method uses AES in ECB mode to encipher the 16 bytes of derivation data with the k-bit diversified key generating key (Issuer Master Key) to produce a k-bit generated ICC master key, where k = 128, 192, or 256.
SESS-ENC	A session key is created by enciphering a 16-byte diversification value with the k-bit AES key-generating key to produce a k-bit AES session key using the AES algorithm in ECB mode, where k is 128, 192 or 256 bits.
*Bit length of generated key* (One, optional). Release 4.4 or later. Valid only with the KDFFM-DK keyword. Default is to use the bit length of the generating key as the bit length of the generated key.
KLEN128	Specifies the bit length of the generated key to be 128.
KLEN192	Specifies the bit length of the generated key to be 192, allowed if and only if the bit length of the generating key is greater than or equal to 192. See Required commands.
KLEN256	Specifies the bit length of the generated key to be 256, allowed if and only if the bit length of the generating key is 256. See Required commands.
*IV usage* (One, optional). Valid only with process keyword KDFFM-DK.
DEFLT-IV	Specifies to use the DK default initial vector value `0x52 52 52 52 52 52 52 52 25 25 25 25 25 25 25 25` as the IV in the derivation function. This is the default value.
USE-IV	Specifies to use the value specified in the input_initial_vector parameter as the IV in the derivation function.

generating_key_identifier_length


Direction:	Input
Type:	Integer

Length of the generating_key_identifier parameter in bytes. If the generating_key_identifier contains a label, the value must be 64. Otherwise, the value must be at least the actual token length, up to 9992.

generating_key_identifier


Direction:	Input/Output
Type:	String

The identifier of the key-generating key. The key identifier is an operational token or the key label of an operational token in key storage.

For CCA keys:

The key algorithm of this key must be AES and the key type must be DKYGENKY. The key usage field indicates the key type of the generated key. The key length determines the length of the generated key.
If SESS-ENC is specified, the clear length of the generated key is equal to the clear length of the generating key. Also, the sequence level can be set to DKYL0, DKYL1, or DKYL2 in the key usage field 2.
If deriving AES MAC keys for the M of N MAC Scheme, the key (known as k-base-1) must be an AES DKYGENKY D-MAC key with the MMSAUTH1 KUF bit enabled.

For TR-31 tokens, this translates to the following properties (the DA optional block is also allowed):

Key Usage: B3
Algorithm: A
Mode of Use: X

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

If the rule_array parameter specifies a diversification process of KDFFM-DK, the key-derivation sequence level of the generating key must be DKYL2. Otherwise, if KDFFM-DK is not specified, any sequence level is allowed for the generating key.

derivation_data_length


Direction:	Input
Type:	Integer

Length of the derivation_data parameter in bytes. Derivation data length value can be any value in the range 1 - 2048 for keyword KDFFM-DK. Otherwise the value must be 16.

derivation_data


Direction:	Input
Type:	String

The derivation data to be used in the key generation process. This data is often referred to as the diversification data. For SESS-ENC, the derivation data is 16 bytes long. Note that if SESS-ENC is specified and the length of the key generating key is 192 bits or 256 bits, the data is manipulated in conformance with the EMV Common Session Key Derivation Option.

When deriving AES MAC keys for the M of N MAC Scheme, the derivation_data parameter must contain the M of N MAC Scheme parameters as described in Table 2 in the initial key derivation.

input_initial_vector_length


Direction:	Input
Type:	Integer

Length in bytes of the input_initial_vector parameter. For CCA releases 6.7, 7.4 and later, and when the KDFFM-DK process rule and the USE-IV keywords are specified, the value must be in the range of 0 - 16. Otherwise, the value must be 0.

input_initial_vector


Direction:	Input
Type:	String

A pointer to a string variable containing a 0 - 16 byte input initial vector value provided to be used instead of the default initial vector for the KDMFFM-DK diversification process. Valid only with the KDFFM-DK keyword.

If the input_initial_vector length is 0, the value

0x52 52 52 52 52 52 52 52 25 25 25 25 25 25 25 25

is used if no IV usage rule array keyword is specified, or if the DFLT-IV rule array keyword is specified.

If the input_initial_vector_length is 0, and the USE-IV rule-array keyword is specified, the input_initial_vector is hexadecimal zero.

When the input_initial_vector_length is zero, this field is ignored.

reserved2_length


Direction:	Input
Type:	Integer

Length of the reserved2 parameter in bytes. The value must be 0.

reserved2


Direction:	Input
Type:	String

This parameter is ignored.

generated_key_identifier1_length


Direction:	Input/Output
Type:	Integer

On input, this parameter specifies the length in bytes of the buffer for the generated_key_identifier1 parameter. The maximum value is 9992 bytes.

On output, the parameter holds the actual length in bytes of the generated_key_identifier1 parameter.

generated_key_identifier1


Direction:	Input/Output
Type:	String

A pointer to a string variable containing an internal variable-length symmetric key token, or the key label of such a record in AES key-storage, or an internal TR-31 key token (or the key label of such a record in combined key storage).

On input, identify a null key token or a skeleton key token that specifies the desired attributes of the key on output. The key token identified by generating_key_identifier determines whether on input the generated_key_identifier1 can identify a null key token or a skeleton key token. See Table 2.

Starting with CCA 8.1, the generated_key_identifier token determines its compliance-tag status based only on the generating_key_identifier token. In previous releases, when the key-generating key from generating_key_identifier is compliant-tagged, a compliant-tagged key token is created.

When a skeleton token is passed as input and the generating_key_identifier is compliant-tagged, the skeleton token must have the compliant-tagged flag on.

Table 2. Generating and generated key tokens
Table with three columns describing input and output of generating and generated key tokens
Input generating key token	Input generated key token	Output generated key token
DKYGENKY, DKYL0, type of key to diversify D-ALL	Null AES key token not allowed; AES skeleton key token required.	Key type same as skeleton; diversified key final.
DKYGENKY, DKYL0, type of key to diversify not D-ALL	Either null AES key token or AES skeleton key token required.	Key type determined by input generated key token type of key to diversify; if null key token on input, output key token will have attributes based on the related generated key usage fields of the input generating key token, otherwise the output key token has attributes of the input skeleton key token.
DKYGENKY, DKYL1, any type of key to diversify	Null AES key token required; AES skeleton key token not allowed.	Same as input generating key token except DKYL0 and with new level of diversified key.
DKYGENKY, DKYL2, any type of key to diversify	Null AES key token required; AES skeleton key token not allowed.	Same as input generating key token except DKYL1 and with new level of diversified key.
TR-31 Key Derivation Key (Key usage B3)	Either a null AES key token or a TR-31 skeleton token	The output generated key token has its attributes (Key Usage, Algorithm, Mode of Use) determined by the input TR-31 skeleton key token placed in the generated_key_identifier1 parameter. If generated_key_identifier1 is a NULL token on input, the output generated key has its attributes determined by the allowed configuration specified in the DA optional block in the generating key. For this case the generating key must contain the DA optional block, and the DA optional block must contain exactly one allowed configuration.
Note: If the supplied generated key-token contains a key, the key value and length are ignored and overwritten. The key type must match what the generating key indicates can be created in the key generating key usage field at offset 45. The key usage fields in the generated key must meet the requirements (`KUF must be equal (KUF-MBE)` or `KUF must be permissible (KUF-MBP)`) of the corresponding key usage fields in the generating key unless D-ALL is specified in the generating key. A flag bit in the DKYGENKY key-usage field 2 determines whether the key-usage field level of control is KUF-MBE or KUF-MBP. When the MMSAUTH1 attribute is present in the input generating_key_identifier parameter, the input generated_key_identifier1 parameter must contain a skeleton token with attributes that exactly match the key to be derived based on the counter value in the derivation_data parameter. This applies in all cases of DKYL level. If authorized by access control, D-ALL permits the derivation of several different keys. See Required commands.

generated_key_identifier2_length


Direction:	Input
Type:	Integer

Length of the generated_key_identifier2 parameter in bytes. The value must be 0.

generated_key_identifier2


Direction:	Input/Output
Type:	String

This parameter is ignored.