Parameters

Edit online

The parameters for CSNBPCU.

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 parameter. This value must be 1 or 2.
rule_array
Direction: Input
Type: String array
Keywords that provide control information to the verb. The keywords are left-aligned in an 8-byte field and padded on the right with blanks. The keywords must be in contiguous storage. The rule_array keywords are described in Table 1.
Table 1. Keywords for PIN Change/Unblock control information

Keywords for PIN Change/Unblock control information
Keyword Description
Algorithm (One, optional)
AES-EMV1 The ICC master key is derived according to the CSNBDKG2 verb with option MK-OPTC. The EMV common session key is derived according to the CSNBDKG2 verb with option SESS-ENC. The encryption_master_key parameter must refer to an AES key. Only valid with the EMV-PCU1PIN processing method.
TDES-XOR TDES encipher clear data to generate the intermediate (card-unique) key, followed by XOR of the final two bytes of each key with the ATC counter. This is the default.
TDESEMV2 Same processing as in the Diversified Key Generate verb.
TDESEMV4 Same processing as in the Diversified Key Generate verb.
PIN processing method (One, required)
AMEXPCU1 Form the new PIN from the new reference PIN, the smart-card-unique, intermediate key, and the current reference PIN.
AMEXPCU2 Form the new PIN from the new reference PIN and the smart-card-unique, intermediate key.
VISAPCU1 Form the new PIN from the new reference PIN and the intermediate (card-unique) key only.
VISAPCU2 Form the new PIN from the new reference PIN, the intermediate (card-unique) key and the current reference PIN.
EMV-PCU1 The new PIN is passed in the new_reference_PIN_* set of parameters. The contents of the five current_reference_PIN_* variables are ignored.

The PIN block is formatted according to EMV v4.3 Book 2 Format 1 and detailed in EMV Common Payment Application (2011) as updated by SB165. TDES-CBC or AES encryption over the PIN block is done according to the issuer master key passed in and EMV v4.3 Book 2.

Note: The authentication_master_key parameter is ignored. The EMV PIN-change command creation process calculates a MAC over the full message using a derived session key and recommends MAC chaining across EMV commands which is outside the scope of this service.

Valid with the AES-EMV1, TDES-XOR, TDESEMV2, and TDESEMV4 algorithm keywords.
authentication_master_key_length
Direction: Input
Type: Integer
The length of the authentication_master_key parameter. For PIN processing method EMV-PCU1, the authentication_master_key_length must be 0 for future compatibility. Otherwise, the value must be 64 for a CCA key token, or up to 9992 for a TR-31 token.
authentication_master_key
Direction: Input/Output
Type: String
The label name or internal token of a DKYGENKY key type that is to be used to generate the card-unique diversified key. For a CCA token, the control vector of this key must be a DKYL0 key that permits the generation of a double-length MAC key (DMAC).

For a TR-31 token, it must have the following attributes (and must not contain a "DA" optional block):

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

This token must not have replicated key halves.

For PIN processing method EMV-PCU1, the authentication_master_key must be a NULL token (64 bytes of X'00').

encryption_master_key_length
Direction: Input
Type: Integer
The length of the encryption_master_key parameter.

For TDES-XOR, TDESEMV2, and TDESEMV4, the value must be 64 for a CCA token. For AES-EMV1, the value must be between the actual length of the token and 9992.

encryption_master_key
Direction: Input/Output
Type: String
The label name or internal token of a DKYGENKY key type that is to be used to generate the card-unique diversified key. The key may be a CCA or TR-31 DES key (TDES-XOR, TDESEMV2, or TDESEMV4) or a CCA or TR-31 AES key (AES-EMV1).

For a CCA DES key, the control vector of this key must be a DKYL0 key that permits the generation of a double-length PIN encryption key (DMPIN). This DKYGENKY must not have replicated key halves.

For a TR-31 DES key, the token must have the following attributes:

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

In addition, it may contain a DA optional block. If a DA optional block is included, it must contain one of the following derivations: P0TEN, P0TES, or P0TEE. If it does not contain any of these derivations, an error is thrown. If there is no DA optional block present in the B3 token, the Diversified Key Generate - DKYGENKY - DALL access control point (X'0290') must be set.

For a CCA AES key, the variable-length symmetric key token must have a token algorithm of AES and a key type of DKYGENKY, sequence level of DKYL0 or DKYL1, and key type to diversify of D-PPROT or D-ALL. For an AES D-PPROT key, the key usage fields must indicate that the derived key can be used for encryption (ENCRYPT), the encryption mode must be Cipher Block Chaining (CBC), common usage control must be NOFLDFMT, PIN block format usage must be ISO-4, and PIN services control must include PINXLATE or REFORMAT.

For a TR-31 AES key, the token must have the following attributes:

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

In addition, it may contain a DA optional block. If a DA optional block is included, it must contain one of the following derivations: P0AEN, P0AES, or P0AEE. If it does not contain any of these derivations, an error is thrown. If there is no DA optional block present in the B3 token, the Diversified Key Generate - DKYGENKY - DALL access control point (X'0290') must be set.

key_generation_data_length
Direction: Input
Type: Integer
The length of the key_generation_data parameter. For TDES-XOR, TDESEMV2, or TDESEMV4, this value must be 10, 18, 26, or 34 bytes. For AES-EMV1, this value must be 32.
key_generation_data
Direction: Input
Type: String
The data provided to generate the card-unique session key.
TDES key generation:
For TDES-XOR, this consists of 8 or 16 bytes of data to be processed by TDES to generate the card-unique diversified key followed by a 16 bit ATC counter to offset the card-unique diversified key to form the session key. ForTDESEMV2 and TDESEMV4, this can be 10, 18, 26 or 34 bytes. See Diversified Key Generate (CSNBDKG) for more information.
AES key generation:
For AES-EMV1, this parameter consists of 2 sections of 16 bytes each, holding first the derivation data for the CSNBDKG2 service MK-OPTC and second the derivation data for the CSNBDKG2 service SESS-ENC. The MK-OPTC derivation data is specified in EMV v4.3 Book 2 section A1.4.3 'Option C' (PAN and PAN sequence number, padded). The SESS-ENC derivation data should be as specified in EMV v4.3 Book 2 section A1.3.1 'Common Session Key Derivation Option' (Application Cryptogram, padded).
Derivation data :: [ 16-byte MK-OPTC data || 16-byte SESS-ENC data ]
new_reference_PIN_key_length
Direction: Input
Type: Integer
The length of the new_reference_PIN_key parameter. The key may be a CCA or TR-31 DES key (all new_reference_PIN_profile PIN block formats except ISO-4) or a CCA or TR-31 AES key (new_reference_PIN_profile PIN block format ISO-4).

For CCA DES keys, the value must be 64.

For CCA AES keys, the value must be between the actual length of the token and 725.

For TR-31 AES and DES keys, the value must be between the actual length of the token and 9992.

new_reference_PIN_key
Direction: Input/Output
Type: String
The label name or internal token of a PIN encrypting key that is to be used to decrypt the new_reference_PIN_block.

If the label name is supplied, the name must be unique in the CKDS. The key may be a CCA or TR-31 DES key (all new_reference_PIN_profile PIN block formats except ISO-4) or a CCA or TR-31 AES key (new_reference_PIN_profile PIN block format ISO-4).

For CCA DES keys, the control vector in the fixed-length token must specify an IPINENC or OPINENC key.

For a TR-31 DES key, the token must have the following attributes:

  • TR-31 key usage: P0
  • Algorithm: T
  • TR-31 mode of key use: D or E

For both CCA and TR-31 DES tokens, double and triple length keys are supported.

For AES keys, the variable-length symmetric key-token must have a token algorithm of AES and a key type of PINPROT. In addition, the key usage fields must indicate that the key can be used for encryption (ENCRYPT) or decryption (DECRYPT), the encryption mode must be Cipher Block Chaining (CBC), common usage control must be NOFLDFMT. The PIN block format usage must be ISO-4, and PIN services control must include PINXLATE or REFORMAT.

For a TR-31 AES key, the token must have the following attributes:

  • TR-31 key usage: P0
  • Algorithm: A
  • TR-31 mode of key use: D or E
new_reference_PIN_block
Direction: Input
Type: String
This field contains the enciphered PIN block of the new PIN. When the new_reference_PIN_profile specifies ISO-4, the new_reference_PIN_block is 16 bytes long. For all other formats, the new_reference_PIN_block is 8 bytes long.
new_reference_PIN_profile
Direction: Input
Type: String
This is a 24-byte field that contains three 8-byte elements with a PIN block format keyword, a format control keyword (NONE), and a pad digit as required by certain formats.
new_reference_PAN_data
Direction: Input
Type: String

A primary account number (PAN) in character format. The service uses this parameter if the PIN profile specifies the ISO-0, ISO-3, ISO-4, or VISA-4 keyword for the input_PIN_profile PIN block format. Otherwise, ensure that this parameter is a 12-byte value in application storage. The information in this parameter is ignored, but the parameter must be specified.

When using the ISO-0, ISO-3, or VISA-4 keyword, the value is 12 bytes long. Use the 12 rightmost digits of the PAN data, excluding the check digit.

When using the ISO-4 keyword, the value is 21 bytes long. The PAN data is 10 – 19 bytes long. The length of the PAN data and the PAN data are contained in the structure below padded to 21 bytes with characters that is ignored.

Table 2. PAN data structure

PAN data structure for the PIN Change Unblock verb
Offset Length Description
0 2 Length of the PAN data field, p.
2 p 10 to 19 bytes of PAN data.
2+p 0-9 Padding.
current_reference_PIN_key_length
Direction: Input
Type: Integer
The length of the current_reference_PIN_key parameter. The key may be a CCA or TR-31 DES key (all current_reference_PIN_profile PIN block formats except ISO-4) or a CCA or TR-31 AES key (current_reference_PIN_profile PIN block format ISO-4).

For CCA DES keys, the value must be 64.

For CCA AES keys, the value must be between the actual length of the token and 725.

For TR-31 AES and DES keys, the value must be between the actual length of the token and 9992.

current_reference_PIN_key
Direction: Input/Output
Type: String
The label name or internal token of a PIN encrypting key that is to be used to decrypt the current_reference_PIN_block. If the label name is supplied, the name must be unique on the CKDS. The key may be a DES key (all current_reference_PIN_profile PIN block formats except ISO-4) or an AES key (current_reference_PIN_profile PIN block format ISO-4).

For CCA DES keys, the control vector in the fixed-length token must specify an IPINENC or OPINENC key.

For a TR-31 DES key, the token must have the following attributes:

  • TR-31 key usage: P0
  • Algorithm: T
  • TR-31 mode of key use: D or E

For both CCA and TR-31 DES tokens, double and triple length keys are supported.

For CCA AES keys, the variable-length symmetric key token must have a token algorithm of AES and a key type of PINPROT. In addition, the key usage fields must indicate that the key can be used for encryption (ENCRYPT) or decryption (DECRYPT), the encryption mode must be Cipher Block Chaining (CBC), common usage control must be NOFLDFMT, PIN block format usage must be ISO-4, and PIN services control must include PINXLATE or REFORMAT.

For a TR-31 AES key, the token must have the following attributes:

  • TR-31 key usage: P0
  • Algorithm: A
  • TR-31 mode of key use: D or E
current_reference_PIN_block
Direction: Input
Type: String
This field contains the enciphered PIN block of the new PIN. When the current_reference_PIN_profile specifies ISO-4, the current_reference_PIN_block is 16 bytes long. For all other formats, the current_reference_PIN_block is 8 bytes long.
current_reference_PIN_profile
Direction: Input
Type: String
This is a 24-byte field that contains three 8-byte elements with a PIN block format keyword, a format control keyword (NONE), and a pad digit as required by certain formats. If the rule_array contains VISAPCU1, this value is ignored.
current_reference_PAN_data
Direction: Input
Type: String

A primary account number (PAN) in character format. The service uses this parameter if the PIN profile specifies the ISO-0, ISO-3, ISO-4, or VISA-4 keyword for the input_PIN_profile PIN block format. Otherwise, ensure that this parameter is a 12-byte value in application storage. The information in this parameter is ignored, but the parameter must be specified.

When using the ISO-0, ISO-3, or VISA-4 keyword, the value is 12 bytes long. Use the 12 rightmost digits of the PAN data, excluding the check digit.

When using the ISO-4 keyword, the value is 21 bytes long. The PAN data is 10 – 19 bytes long. The length of the PAN data and the PAN data are contained in the structure shown in Table 3 padded to 21 bytes with characters that are ignored.
Table 3. PAN data structure

PAN data structure for the PIN Change Unblock verb
Offset Length Description
0 2 Length of the PAN data field, p.
2 p 10 to 19 bytes of PAN data.
2+p 0-9 Padding.
output_PIN_data_length
Direction: Input
Type: Integer
Currently this field is reserved. This value must be 0.
output_PIN_data
Direction: Input
Type: String
This parameter is ignored.
output_PIN_profile
Direction: Input
Type: String
This is a 24-byte field that contains three 8-byte elements with a PIN block format keyword (VISAPCU1, VISCPU2, AMEXPCU1, AMEXPCU2, or EMV-PCU1), a format control keyword (NONE, left aligned and padded on the right with space characters), and eight bytes of spaces.
output_PIN_message_length
Direction: Input/Output
Type: Integer
The length of the output_PIN_message field. The value must be at least 16 for EMV-PCU1, VISAPCU1, and VISAPCU2 and at least 8 for AMEXPCU1 and AMEXPCU2.
output_PIN_message
Direction: Output
Type: String
The reformatted PIN block with the new reference PIN enciphered under the SMPIN session key.