Parameters

Edit online

The parameter definitions for CSNBDKG.

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 processing method is the algorithm used to create the generated key. The keyword is left-aligned and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for Diversified Key Generate control information

Keywords for Diversified Key Generate control information
Keyword Description
Processing Method for generating or updating diversified keys (One required)
A28OWFCL Specifies that 16 bytes of clear data are processed as described in AS2805.5.4 to create the generated key. The data parameter is processed by the One Way Function of the Australian Payment Network (APN) using a double-length key-encrypting key to generate a new key-encrypting key.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: D0
  • Algorithm: T
  • TR-31 mode of key use: B

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: D0, M0, M1, M3, M6, P0
  • Algorithm: T
  • TR-31 mode of key use: B (D0 only), D (P0 only), C, G, V
A28OWFEC Specifies that 16 bytes of encrypted data in the data parameter are processed as described in AS2805.5.4 to create the generated key. The encrypted data shall be processed by the Australian Payment Network (APN) One Way Function (OWF) using a double-length key in the generating_key_identifier parameter to generate a new key in the generated_key_identifier parameter.

The data parameter should contain the data TDES-ECB wrapped as follows:

data = wrap(PPASN) || wrap(PPASN)

When using TR-31 tokens, the generating_key_identifier allows the following properties:

  • TR-31 key usage: D0, K0
  • Algorithm: T
  • TR-31 mode of key use: B, E

The data_decrypting_key_identifier allows the following properties:

  • TR-31 key usage: D0
  • Algorithm: T
  • TR-31 mode of key use: B or D

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: D0, K0
  • Algorithm: T
  • TR-31 mode of key use: B, E
Note: The skeleton token in the generated_key_identifier parameter must match the type of the generating_key_identifier.
A28XOREC Specifies that 16 bytes of encrypted data in the data parameter is processed as described in AS2805.5.4 to create the generated key. The decrypted data is processed by an XOR operation using a double-length key in the generating_key_identifier parameter to generate a new key in the generated_key_identifier parameter.

The data parameter should contain the data TDES-ECB wrapped as follows:

data = wrap(PPASN) || wrap(PPASN)

This mode is specific to 2.2 TERMKEYGEN2 in AS2805.5.4

When using TR-31 tokens, the generating_key_identifier must have the following properties:

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

The data_decrypting_key_identifier allows the following properties:

  • TR-31 key usage: D0
  • Algorithm: T
  • TR-31 mode of key use: B or D

The generated_key_identifier may contain a TR-31 skeleton token with the following properties:

  • TR-31 key usage: K0
  • Algorithm: T
  • TR-31 mode of key use: E
CLR8-ENC Specifies that eight bytes of clear data shall be Triple-DES encrypted with the generating key (generating_key_identifier) to create a key.

The key selected by the generating_key_identifier must specify a KEYGENKY key-type also with control vector bit 19 set to B'1'.

The key identified by the data_decrypting_key_identifier must identify a null DES key-token.

The key token identified by the generated_key_identifier variable must contain a control vector that specifies a single-length key of one of these types: DATA, CIPHER, DECIPHER, MAC, or MACVER.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: B3
  • Algorithm: T
  • TR-31 mode of key use: X

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: D0, M1, M3
  • Algorithm: D
  • TR-31 mode of key use: B, C, D, E, G, V
TDES-CBC Specifies that 16 bytes of clear data shall be Triple-DES encrypted with the generating key to create the generated key. If the generated_key_identifier variable specifies a double-length key, then 16 bytes of clear data are Triple-DES encrypted in CBC mode with an initial value of binary zeros.
Note: The EMV Card Personalization specification states that CBC encryption mode should be used in the diversification process.

The key selected by the generating_key_identifier parameter must specify a DKYGENKY key-type that has the appropriate control vector usage bits (bits 19 – 22) set for the desired generated key.

Control vector bits 12 – 14 binary encode the key-derivation sequence level (DKYL7 down to DKYL0). The final key is derived when bits 12 – 14 are B'000'. The verb verifies the incremental relationship between the value in the control vectors of the key tokens identified by the generating_key_identifier parameter and the generating_key_identifier parameter control vector. In the case when the generated_key_identifier is a null DES token, the appropriate counter value is placed into the output key-token.

The data_decrypting_key_identifier parameter must identify a null DES key-token.

A key token identified by the generated_key_identifier parameter that is not a null key-token must contain a control vector that specifies a double-length key having a key type that is consistent with the specification in bits 19 – 22 of the generating key.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: B3
  • Algorithm: T
  • TR-31 mode of key use: X

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: K0, K1, K4, D0, B3, M0, M1, M3, M6, F0, F1, F2, F3, F4, P0, V0, V1, V2
  • Algorithm: T
  • TR-31 mode of key use: B, C, D, E, G, V, X
TDES-DEC Specifies that 8 or 16 bytes of clear data shall be Triple-DES decrypted with the generating key to create the generated key. If the generated_key_identifier variable specifies a single-length key, then 8 bytes of clear data are Triple-DES decrypted. If the generated_key_identifier variable specifies a double-length key, then 16 bytes of clear data are Triple-DES decrypted in ECB mode.

The key selected by the generating_key_identifier must specify a DKYGENKY key-type that has the appropriate control vector usage bits (bits 19 – 22) set for the desired generated key.

Control vector bits 12 – 14 binary encode the key-derivation sequence level (DKYL7 down to DKYL0). The final key is derived when bits 12 – 14 are B'000'. The verb verifies the incremental relationship between the value in the generated_key_identifier control vector and the generating_key_identifier control vector. Or in the case when the generated_key_identifier variable is a null DES key-token, the appropriate counter value is placed into the output key-token.

The data_decrypting_key_identifier variable must identify a null DES key-token.

A key token identified by the generated_key_identifier variable that is not a null DES key-token must contain a control vector that specifies a single-length or double-length key having a key type consistent with the specification in bits 19 – 22 of the generating key.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: B3
  • Algorithm: T
  • TR-31 mode of key use: X

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: K0, K1, K4, D0, B3, M0, M1, M3, M6, F0, F1, F2, F3, F4, P0, V0, V1, V2
  • Algorithm: T
  • TR-31 mode of key use: B, C, D, E, G, V, X
TDES-ENC Specifies that 16 bytes of clear data shall be Triple-DES encrypted with the generating key to create the generated key. If the generated_key_identifier variable specifies a double-length key, then 16 bytes of clear data are Triple-DES encrypted in ECB mode with an initial value of binary zeros.
Note: The EMV Card Personalization specification states that ECB encryption mode should be used in the diversification process.

The key selected by the generated_key_identifier must specify a DKYGENKY key-type that has the appropriate control vector usage bits (bits 19 – 22) set for the desired generated key.

Control vector bits 12 – 14 binary encode the key-derivation sequence level (DKYL7 down to DKYL0). The final key is derived when bits 12 – 14 are B'000'. The verb verifies the incremental relationship between the value in the generated_key_identifier control vector and the generating_key_identifier control vector. Or in the case when the generated_key_identifier variable is a null DES key-token, the appropriate counter value is placed into the output key-token.

The data_decrypting_key_identifier parameter must identify a null DES key-token.

A key token identified by the generated_key_identifier variable that is not a null DES key-token must contain a control vector that specifies a single-length or double-length key having a key type consistent with the specification in bits 19 – 22 of the generating key.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: B3
  • Algorithm: T
  • TR-31 mode of key use: X

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: K0, K1, K4, D0, B3, M0, M1, M3, M6, F0, F1, F2, F3, F4, P0, V0, V1, V2
  • Algorithm: T
  • TR-31 mode of key use: B, C, D, E, G, V, X
TDES-XOR Specifies that 10 bytes or 18 bytes of clear (not encrypted) data shall be processed as described in Working with Europay-Mastercard-Visa Smart cards to create the generated key. The data variable contains either 8 bytes or 16 bytes of data to be triple-encrypted to which you append a 2-byte Application Transaction Counter value (previously received from the smart card). Place the counter value in a string construct with the high-order counter bit first in the string.

The key selected by the generating_key_identifier parameter must specify a DKYGENKY key-type at level-0 (bits 12 – 14 B'000') and indicate permission to create one of several key types in bits 19 – 22:

B'0001'
DDATA, to generate a DATA key
B'0010'
DMAC, to generate a MAC key
B'0011'
DMV, to generate a MACVER key
B'1000'
DMKEY, to generate a SECMSG SMKEY (used in secure messaging, key encryption, see the Secure Messaging for PINs verb)
B'1001'
DMPIN, to generate a SECMSG SMPIN (used in secure messaging, PIN encryption, see the Secure Messaging for PINs verb).

The data_decrypting_key_identifier parameter must identify a null DES key-token.

A key token or key-token record identified by the generated_key_identifier parameter that is not a null DES key-token. The token must contain a control vector that specifies a key type conforming to that specified in control-vector bits 19 – 22 for the key-generating key. The control vector must specify a double-length key.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: B3
  • Algorithm: T
  • TR-31 mode of key use: X

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: D0, M0, M1, M3, M6, F1, F2, P0
  • Algorithm: T
  • TR-31 mode of key use: B, C, D, E, G, V
TDESEMV2 This option supports generation of a session key by the EMV 2000 algorithm (This EMV2000 algorithm uses a branch factor of 2). The generating key must be a level 0 DKYGENKY and cannot have replicated halves. The session key generated must be double length and the allowed key types are DATA, DATAC, DATAM, DATAMV, MAC, MACVER, SMPIN, and SMKEY. Key type must be allowed by the generating key control vector.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: B3
  • Algorithm: T
  • TR-31 mode of key use: X

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: D0, M0, M1, M3, M6, F1, F2, P0
  • Algorithm: T
  • TR-31 mode of key use: B, C, D, E, G, V
TDESEMV4 This option supports generation of a session key by the EMV 2000 algorithm (This EMV2000 algorithm uses a branch factor of 4). The generating key must be a level 0 DKYGENKY and cannot have replicated halves. The session key generated must be double length and the allowed key types are DATA, DATAC, DATAM, DATAMV, MAC, MACVER, SMPIN, and SMKEY. Key type must be allowed by the generating key control vector.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: B3
  • Algorithm: T
  • TR-31 mode of key use: X

The generated_key_identifier may contain a TR-31 skeleton token with the following properties allowed:

  • TR-31 key usage: D0, M0, M1, M3, M6, F1, F2, P0
  • Algorithm: T
  • TR-31 mode of key use: B, C, D, E, G, V
Processing Method for updating a diversified key (optional)
SESS-XOR Specifies the VISA method for session key generation, namely that 8 bytes or 16 bytes of data shall be exclusive-ORed with the clear value of the session key contained in the key token identified by the generating_key_identifier parameter. If the generating_key_identifier parameter identifies a single-length key, then 8 bytes of data are exclusive-ORed. If the generating_key_identifier parameter identifies a double-length key, then 16 bytes of data are exclusive-ORed.

The key token specified by the generating_key_identifier parameter must be of key type DATA, DATAC, DATAM, DATAMV, MAC, MACVER.

The data_decrypting_key_identifier parameter must identify a null DES key-token.

On input, the token identified by the generated_key_identifier parameter must identify a null DES key-token. The control vector contained in the output key token identified by the generated_key_identifier is the same as the control vector contained in the key token identified by the generating_key_identifier.

When using TR-31 tokens, the generating_key_identifier must have the following properties:

  • TR-31 key usage: D0, M0, M1, M3, M6
  • Algorithm: D or T
  • TR-31 mode of key use: B, C, D, E, G, V

The generated_key_identifier must contain a null token.
Key-wrapping method (One, optional)
USECONFG This is the default. Specifies to wrap the key using the configuration setting for the default wrapping method. The default wrapping method configuration setting may be changed using the TKE. This keyword is ignored for AES keys.
WRAP-ECB Specifies to wrap the key using the legacy wrapping method.
WRAP-ENH Specifies to wrap the key using the enhanced wrapping method.
WRAPENH3 Specifies to wrap the key using the enhanced wrapping method with TDES-CMAC and the SHA-256 hashing algorithm. This keyword sets CV bit 56 = B’1’ (ENH-ONLY), which is required for the WRAPENH3 wrapping method.
Translation control (Optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when the default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to binary zeros.
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method once it has been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the control vector to B'1'.
generating_key_identifier
Direction: Input/Output
Type: String
The label or internal token of a key generating key. The type of key-generating key depends on the processing method.

The requirements for the keys used by APN are:

  • For A28XOREC, this key may be a double-length DES EXPORTER key in either a CCA token or a TR-31 token.
  • For A28OWFEC, this key may be a double-length DES EXPORTER or DES CIPHER key in either a CCA token or a TR-31 token.
  • For A28OWFCL, this key may be a double-length DES CIPHER key in either a CCA token or a TR-31 token.
See the rule_array parameter (Table 1) for more details on TR-31 keys that can be used in this parameter.

For other processing method rules, the key is a DES key-generating key as described in the rule array.

If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.
data_length
Direction: Input
Type: Integer
The length of the data parameter (number of bytes). The required length depends on the diversification process specified in the rule array and the length of the key identified by the generated_key_identifier parameter:

Table with three columns
Rule-array keyword Key length of generated key Required data length
CLR8-ENC SINGLE 8
A28OWFCL DOUBLE 16
A28OWFEC DOUBLE 16
A28XOREC DOUBLE 16
TDES-CBC DOUBLE or null key-token 16
TDES-ENC DOUBLE or null key-token 16
SINGLE 8
TDES-DEC DOUBLE or null key-token 16
SINGLE 8
TDESEMV2, TDESEMV4 DOUBLE 10, 18, 26, or 34
TDES-XOR DOUBLE 10 or 18
SESS-XOR DOUBLE 16
SINGLE 8
data
Direction: Input
Type: String
Data input to the diversified key or session key generation process. Data depends on the processing method and the generated_key_identifier.
data_decrypting_key_identifier
Direction: Input/Output
Type: String
The key to decrypt the value supplied in the data parameter. When the processing method rule array keyword is A28OWFEC or A28XOREC, this parameter must contain the label, the 64-byte CCA key token of a DES CIPHER or DECIPHER key, or a TR-31 key token as described in Table 1. The key must be a double-length key. Otherwise, this parameter must contain a 64-byte null token.

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

generated_key_identifier
Direction: Input/Output
Type: String
The internal token of an operational key, a CCA skeleton token containing the control vector of the key to be generated, a TR-31 skeleton token, or a null token. A null token can be supplied if the generated_key_identifier is a DKYGENKY with a CV derived from the generating_key_identifier. A skeleton token or internal token is required when the generated_key_identifier is not a DKYGENKY key type or the processing method is not SESS-XOR. For SESS-XOR, this must be a null token. When generating TR-31 tokens, a completed TR-31 key token is not allowed in the generated_key_identifier parameter, only a skeleton TR-31 key token is allowed.

On output, this parameter contains the generated key.

Starting with CCA 8.1, the generated_key_identifier takes on the compliant-tagged property of the generating_key_identifier, ignoring the state of the generated_key_identifier skeleton token on input. In previous releases, to generate a compliant-tagged key token, a compliant-tagged skeleton token would need to be supplied.

The key is generated using the data and the diversification process specified. The diversified key that is generated is returned encrypted in the specified internal CCA key token, TR-31 key token, or in the generated key token if a null key-token is specified. If an internal key-token is identified on input, its control vector must be suitable for the specified process rule.

  • For A28XOREC, this key must be a CCA key token or skeleton of type DES EXPORTER. Or for TR-31 it must be a TR-31 skeleton token as described in Table 1 (never a full TR-31 token).
  • For A28OWFEC, this key must be a CCA key token or skeleton that matches the type of the generating_key_identifier. Or for TR-31 it must be a TR-31 skeleton token that matches the type of the generating_key_identifier as described in Table 1 (never a full TR-31 token).
  • For A28OWFCL, this key must be a CCA key token or skeleton of type DES CIPHER, DES MAC with sub-type ANY-MAC, or DES IPINENC. Or for TR-31 it must be a TR-31 skeleton token as described in Table 1 (never a full TR-31 token).