Parameters

Edit online

The parameters for CSNBDPC.

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. The value must be in the range 0-7.
rule_array
Direction: Input
Type: String array
Keywords that provide control information to the verb. 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. The rule_array keywords are described in Table 1.
Table 1. Keywords for DK PIN Change control information

Keywords for DK PIN Change control information
Keyword Description
PIN Block output selection keyword (One, optional)
EPB Return an encrypted PIN block and a MAC to verify the encrypted PIN block.
NOEPB Do not return an encrypted PIN block (EPB). This is the default value.
PIN-block format (One, optional). Release 5.4 or later.
ISO-1 Specifies that the encrypted PIN-block identified by both of the cur_ISO_encrypted_PIN_block and new_ISO_encrypted_PIN_block parameters are in the ISO-1 format. This is the default.
ISO-4 Specifies that the encrypted PIN-block identified by both of the cur_ISO_encrypted_PIN_block and new_ISO_encrypted_PIN_block parameters are in the ISO-4 format.
Script selection algorithm and method (One, optional)
AES-CBC Use CBC mode to AES encrypt the PIN block in the script. If SCR2020 is specified, AES-CBC specifies to AES encrypt the PIN block plus additional data in the script.
NOSCRIPT Do not return an encrypted SMPIN message with a MAC. This is the default value.
TDES-CBC Use CBC mode to TDES encrypt the PIN block in the script. If SCR2020 is specified, TDES-CBC specifies to encrypt the PIN block plus additional data in the script with TDES CBC.
TDES-ECB Use ECB mode to TDES encrypt the PIN block in the script. If SCR2020 is specified, TDES-EBC specifies to encrypt the PIN block plus additional data in the script with TDES EBC.


PIN encryption keyword  (One, optional)
Only valid if TDES-CBC or TDES-ECB is selected.
CLEARPIN Do not encrypt the PIN prior to inserting in the script block. This is the default value.
SELF-ENC Copy the PIN-block self-encrypted to the clear PIN block within the clear output message. Use this rule array keyword to specify that the 8-byte PIN block shall be used as a DES key to encrypt the PIN block. The service copies the self-encrypted PIN block to the clear PIN block in the output message.


MAC Ciphering Method
(One required for AES-CBC, one optional for TDES-CBC or TDES-ECB,
otherwise not allowed.)
CMAC Specifies to use the cipher-based MAC algorithm block cipher mode of operation for authentication, recommended in NIST SP 800-38B. Required for AES-CBC. Only valid with AES-CBC.
EMVMACD Specifies the EMV-related message-padding and calculation method.
TDES-MAC Specifies the ANS X9.9 Option 1 (binary data) procedure and a CBC Triple-DES encryption of the data.
X9.19OPT Specifies the ANS X9.19 Optional Procedure. A double-length key is required. This is the default value.
MAC Length and presentation (one optional, with keyword AES-CBC, TDES-CBC or TDES-ECB, otherwise not allowed.)
MACLEN8 Specifies an 8-byte MAC. This is the default for TDES-CBC and TDES-ECB.
MACLEN16 Specifies a 16-byte MAC. Only valid with CMAC. This is the default for AES-CBC.
Script process (one optional for AES-CBC, TDES-CBC or TDES-ECB, otherwise not allowed).
SCR2013 Specifies to use script processing rules introduced with the service in 2013. This is the default.
SCR2020 Specifies to use script processing rules introduced with the service in 2020. The new process encrypts only the new PIN block and some additional data in the card_script_data parameter, rather than encrypting the entire field, and returns only the encrypted portion of the card_script_data parameter as the output.
PAN_data_length
Direction: Input
Type: Integer
Specifies the length in bytes of the PAN_data parameter. The value must be in the range 10 - 19.
PAN_data
Direction: Input
Type: String
The PAN data to which the PIN is associated. The full account number, including check digit, should be included.
card_p_data_length
Direction: Input
Type: Integer
Specifies the length in bytes of the card_p_data parameter. The value must be in the range 2 - 256.
card_p_data
Direction: Input
Type: String
The time-invariant card data (CDp), determined by the card issuer, which is used to differentiate between multiple cards for one account.
card_t_data_length
Direction: Input
Type: Integer
Specifies the length in bytes of the card_t_data parameter. The value must be in the range 2 - 256.
card_t_data
Direction: Input
Type: String
The time-sensitive card data, determined by the card issuer, which, together with the account number and the card_p_data, specifies an individual card.
cur_ISO_PIN_block_length
Direction: Input
Type: Integer
Specifies the length in bytes of the cur_ISO_PIN_block parameter. The value must be 8 for ISO-1 or 16 for ISO-4.
cur_ISO_PIN_block
Direction: Input
Type: String
The encrypted PIN block in ISO-1 or ISO-4 PIN-block format for the current customer-chosen PIN.
new_ISO_PIN_block_length
Direction: Input
Type: Integer
Specifies the length in bytes of the new_ISO_PIN_block parameter. The value must be 8 for ISO-1 or 16 for ISO-4.
new_ISO_PIN_block
Direction: Input
Type: String
The new encrypted PIN block in ISO-1 or ISO-4 format for the new customer-chosen PIN.
card_script_data_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the card_script_data variable. If the script selection of the rule array specifies to not return an encrypted SMPIN message with a PIN block MAC (that is, AES-CBC, TDES-CBC, or TDES-ECB is not specified), the value must be 0. Otherwise, set the value less than or equal to 4096 for AES_CBC. Set this value to a multiple of 8 and less than or equal to 4096 for TDES-CBC or TDES-ECB.
card_script_data
Direction: Input
Type: String
The cleartext data from which to produce a MAC. The script_offset value can be considered the PIN block offset. If the SCR2013 keyword or no script process rule is specified, the entire field is encrypted and returned in the script parameter. If the SCR2020 keyword is specified, script_length bytes are encrypted starting at the offset indicated by the script_offset parameter. The PIN block plus additional data are encrypted and inserted at the offset specified by the script_offset parameter where the MAC operation is performed. The smaller encrypted result is returned in the script parameter.
script_offset
Direction: Input
Type: Integer
The offset in bytes from the beginning of the cleartext data in the card_script_data variable to the location for the clear PIN block. The first byte of the cleartext data is offset 0. If the SCR2013 keyword or no script process rule is specified, this offset plus the script_offset_field_length must be less than or equal to the card_script_data_length. If the SCR2020 keyword is specified, the value of the script_offset plus the script_length must be less than or equal to the card_script_data_length.
script_offset_field_length
Direction: Input
Type: Integer
The number of bytes of data in the PIN block format referenced by the output PIN profile. This length must be 8. The PIN block must fit entirely within the card_script_data parameter. If NOSCRIPT is specified in the rule array, this parameter is ignored.
script_initialization_vector_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the script_initialization_vector parameter. For script selection algorithm and method keyword AES-CBC the value must be 16, and for TDES-CBC the value must be 8. Otherwise, set the value to 0.
script_initialization_vector
Direction: Input
Type: String
a pointer to a string variable containing the initialization vector to use when encrypting the script in CBC mode. If the script_initialization_vector_length variable is 0 or if keyword TDES-ECB is specified, this parameter is ignored but must be declared. Otherwise, this parameter must point to a string of hexadecimal zeros.
output_PIN_profile
Direction: Input
Type: String
A 24-byte string containing the PIN profile, including the PIN block format for the script. See The PIN profile for additional information. You can use PIN-block formats ISO-0, ISO-1, ISO-2, ISO-3, and beginning with Release 5.4, ISO-4 with this service. If NOSCRIPT is specified in the rule array, this parameter is ignored.
PIN_reference_value_length
Direction: Input
Type: Integer
Specifies the length in bytes of the PIN_reference_value parameter. This value must be 16.
PIN_reference_value
Direction: Input
Type: String
The 16-byte PIN reference value of the current PIN for comparison to the calculated value.
PRW_random_number_length
Direction: Input
Type: Integer
Specifies the length in bytes of the PRW_random_number parameter. The value must be 4.
PRW_random_number
Direction: Input
Type: String
The 4-byte random number associated with the PIN reference value of the current PIN.
PRW_key_identifier_length
Direction: Input
Type: Integer
Specifies the length in bytes of the PRW_key_identifier parameter. If the PRW_key_identifier contains a label, the length must be 64. Otherwise, the value must be at least the actual token length, up to 725.
PRW_key_identifier
Direction: Input
Type: String
The identifier of the key to verify the PRW of the current PIN block. The key identifier is an operational token or the key label of an operational token in key storage. The key algorithm of this key must be AES, the key type must be PINPRW, and the key usage fields must indicate VERIFY, CMAC, and DKPINOP.

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

cur_IPIN_encryption_key_identifier_length
Direction: Input
Type: Integer
Specifies the length in bytes of the cur_IPIN_encryption_key_identifier parameter. Set the value to 64 for an ISO-1 PIN-block, or a maximum of 3500 for an ISO-4 PIN-block. A key label must be at least 64 bytes, and only the first 64 bytes of a key label are used.
cur_IPIN_encryption_key_identifier
Direction: Input/Output
Type: String

A pointer to a string variable containing an operational fixed-length DES key-token or the key label of such a record in DES key-storage or an operational variable-length AES key-token or the key label of such a record in AES key-storage. The key token contains the current inbound PIN encryption key used to recover the PIN from the encrypted PIN block identified by the cur_ISO_PIN_block parameter.

If ISO-1 is requested, the Triple-DES key must have a key type of IPINENC. In addition, the control vector must enable the verification of an encrypted PIN (EPINVER, CV bit 19 = B'1').

Beginning with Release 5.4, if ISO-4 is requested, the key token must have a token algorithm of AES and a key type of PINPROT. In addition, the key usage fields must have the encryption operation set so that the key can be used for decryption but not encryption (DECRYPT). The encryption mode must be Cipher Block Chaining (CBC), the common control usage must be set to no field format specification (NOFLDFMT), the PIN-block format usage must be set to allow ISO-4, and the inbound function usage must allow verifying an encrypted PIN (EPINVER).

new_IPIN_encryption_key_identifier_length
Direction: Input
Type: Integer
Specifies the length in bytes of the new_IPIN_encryption_key_identifier parameter. Set the value to 64 for an ISO-1 PIN-block, or a maximum of 3500 for an ISO-4 PIN-block. A key label must be at least 64 bytes, and only the first 64 bytes of a key label are used.
new_IPIN_encryption_key_identifier
Direction: Input/Output
Type: String

A pointer to a string variable containing an operational fixed-length Triple-DES key-token or the key label of such a record in DES key-storage or, beginning with Release 5.4, a variable-length AES key-token or the key label of such a record in AES key-storage. The key token contains the new inbound PIN encryption key used to recover the PIN from the encrypted PIN-block identified by the new_ISO_PIN_block parameter and verify the recovered value.

If the encrypted PIN-block is in ISO-1 format, the Triple-DES key-token must have a key type of IPINENC. In addition, the control vector must enable translation of an encrypted PIN (TRANSLAT, CV bit 21 = B'1').

Note: To use the same key token for the current and the new IPIN encryption key, the control vector must have CV bit 19 = B'1' and CV bit 21 = B'1'. An IPINENC key has these bits on by default in the control vector.

Beginning with Release 5.4, if the encrypted PIN-block is in ISO-4 format, the key token must have a token algorithm of AES and a key type of PINPROT. In addition, the key usage fields must have the encryption operation set so that the key can be used for decryption but not encryption (DECRYPT), the encryption mode must be Cipher Block Chaining (CBC), the common control usage set to no field format specification (NOFLDFMT), and the inbound function usage must allow translation (PINXLATE). To use the same key token for the current and the new IPIN encryption key, the inbound function usage must allow encrypted PIN verification (EPINVER) and the common control usage must be set to no field format specification (NOFLDFMT).

script_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the script_key_identifier variable. If the script_key_identifier parameter identifies a key label, the length must be 64. Otherwise, for script selection algorithm and method keyword NOSCRIPT or its default, set the length to 0 or the length of a null key token, for AES-CBC set a maximum length of 725, and for TDES-CBC or TDES-ECB set the length to 64.
script_key_identifier
Direction: Input/Output
Type: String
A pointer to a string variable containing an operational fixed-length DES key-token or the key label of such a record in DES key-storage. Beginning with Release 4.4, it can be a pointer to a string variable containing an operational variable-length AES key-token or the key label of such a record in AES key-storage. The type of key depends on the script selection algorithm and method of the rule array:
  • If AES-CBC is specified to return an AES-enciphered SMPIN message with a PIN block MAC, the key must be contained in a variable-length symmetric key-token. The key must have a token algorithm of AES and a key type of SECMSG. In addition, the key usage fields must enable the encryption of PINs in an EMV secure message (SMPIN), and must allow the key to be used by the CSNBDPC verb (ANY-USE or DPC-ONLY).
  • If TDES-ECB or TDES-CBC) is specified to return a DES-enciphered SMPIN message with a PIN block MAC, the key must be contained in a fixed-length DES key token and have a key type of SECMSG. In addition, the control vector must enable the encryption of PINs (SMPIN bit 19 = B'1') .
  • If NOSCRIPT or its default is specified to not return an enciphered SMPIN message with a PIN block MAC, the script_key_identifier_length variable should be set to 0. If the length is greater than 0, this parameter must identify a valid DES or a valid AES key-token that is otherwise ignored.
script_MAC_key_identifier_length
Direction: Input
Type: Integer
The script_MAC_key_identifier_length parameter is a pointer to an integer variable containing the number of bytes of data in the script_MAC_key_identifier variable. If the script_MAC_key_identifier parameter identifies a key label, the length must be 64. Otherwise, for script selection algorithm and method keyword NOSCRIPT or its default, set the value to 0 or the length of a null key token, for AES-CBC set a maximum length of 725, and for TDES-CBC or TDES-ECB set the length to 64.
script_MAC_key_identifier
Direction: Input/Output
Type: String
A pointer to a string variable containing an operational fixed-length DES key-token or the key label of such a record in DES key-storage. Beginning with Release 4.4, it can be a pointer to a string variable containing an operational variable-length AES key-token or the key label of such a record in AES key-storage. The type of key depends on the script selection algorithm and method of the rule array:
  • If AES-CBC is specified to return an AES-enciphered SMPIN message with a PIN block MAC, the key must be contained in a variable-length symmetric key-token. The key must have a token algorithm of AES and a key type of MAC. In addition, the key usage fields must have the MAC operation set so that the key can be used for generate (GENERATE or GENONLY), and the MAC mode must be CMAC.
  • If TDES-ECB or TDES-CBC is specified to return a DES-enciphered SMPIN message with a PIN block MAC, the key must be double length and have a key type of MAC (generate is allowed). In addition, the control vector must have a subtype of ANY-MAC (bits 0-3 = B'0000').
  • If NOSCRIPT or its default is specified to not return an enciphered SMPIN message with a PIN block MAC, the script_key_identifier_length variable should be set to 0. If the length is greater than 0, this parameter must identify a valid DES or, beginning with Release 4.4, a valid AES key-token that is otherwise ignored.
new_PRW_key_identifier_length
Direction: Input
Type: Integer
Specifies the length in bytes of the new_PRW_key_identifier parameter. If the new_PRW_key_identifier contains a label, the length must be 64. Otherwise, the value must be at least the actual token length, up to 725.
new_PRW_key_identifier
Direction: Input/Output
Type: String
The identifier of the key to verify the new PRW. The key identifier is an operational token or the key label of an operational token in key storage. The key algorithm of this key must be AES, the key type must be PINPRW, and the key usage fields must indicate GENONLY, CMAC, and DKPINOP.

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

OPIN_encryption_key_identifier_length
Direction: Input
Type: Integer
Specifies the length in bytes of the OPIN_encryption_key_identifier parameter. If the rule array indicates that no encrypted PIN block is to be returned, this value must be 0. If the OPIN_encryption_key_identifier contains a label, the length must be 64. Otherwise, the value must be at least the actual token length, up to 725.
OPIN_encryption_key_identifier
Direction: Input/Output
Type: String
The identifier of the key to encrypt the new PIN block. The key identifier is an operational token or the key label of an operational token in key storage. If the OPIN_encryption_key_identifier_length is 0, this parameter is ignored. The key algorithm of this key must be AES, the key type must be PINPROT, and the key usage fields must indicate ENCRYPT, CBC, and DKPINOP.

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

OEPB_MAC_key_identifier_length
Direction: Input
Type: Integer
Specifies the length in bytes of the OEPB_MAC_key_identifier parameter. If the rule array indicates that no encrypted PIN block is to be returned, this value must be 0. If the OEPB_MAC_key_identifier contains a label, the length must be 64. Otherwise, the value must be at least the actual token length, up to 725.
OEPB_MAC_key_identifier
Direction: Input/Output
Type: String
The identifier of the key to generate the MAC of new PIN block. The key identifier is an operational token or the key label of an operational token in key storage. If the OEPB_MAC_key_identifier_length is 0, this parameter is ignored. The key algorithm of this key must be AES, the key type must be MAC, and the key usage fields must indicate CMAC, GENONLY, and DKPINOP.

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

script_length
Direction: Input/Output
Type: Integer
The number of bytes of data in the script variable. The value must be 0 if the script selection algorithm and method of the rule array specifies NOSCRIPT. For scripting, if the SCR2020 keyword is specified, the value must be set to the PIN block length plus the length of the additional customer defined data. Otherwise, the value of the script_offset plus the script_length must be less than or equal to the card_script_data_length.
script
Direction: Output
Type: String
The script returned. If the rule array specifies to return a script, script_length bytes of this variable are overwritten. If SCR2020 is specified, the script parameter is a pointer to a string variable containing the encrypted part of the script. Otherwise, it contains the entire script.
script_MAC_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the script_MAC variable. Set to 0 if script selection algorithm and method of the rule array specifies NOSCRIPT or its default. Otherwise, on input set the value to at least 8 for MAC length and presentation keyword MACLEN8, or at least 16 for MACLEN16. Set this value between 4 and 16 (inclusive), if MACLEN16 keyword is not specified, but the AES-CBC keyword is specified. On output, the value is updated with the length of data returned in the script_MAC variable.
script_MAC
Direction: Output
Type: String
A pointer to a string variable containing the MAC calculated on the script returned in the script variable. The value is left-aligned in the variable and is truncated on the right as needed to the length specified by the MAC length and presentation keyword.
new_PIN_reference_value_length
Direction: Input/Output
Type: Integer
Specifies the length in bytes of the new_PIN_reference_value parameter. The value must be at least 16. On output, it is set to 16.
new_PIN_reference_value
Direction: Output
Type: String
The 16-byte new PIN reference value of the new PIN block.
new_PRW_random_number_length
Direction: Input/Output
Type: Integer
Specifies the length in bytes of the new_PRW_random_number parameter. The value must be at least 4. On output, it is set to 4.
new_PRW_random_number
Direction: Output
Type: String
The 4-byte random number associated with the new PIN reference value.
output_encrypted_PIN_block_length
Direction: Input/Output
Type: Integer
Specifies the length in bytes of the output_encrypted_PIN_block parameter. If the rule array indicates that no encrypted PIN block should be returned, this value must be 0. Otherwise, it should be at least 32. On output it is set to 32.
output_encrypted_PIN_block
Direction: Output
Type: String
The 32-byte encrypted new PIN block. If the output_encrypted_PIN_block_length is 0, this parameter is ignored.
PIN_block_MAC_length
Direction: Input/Output
Type: Integer
Specifies the length in bytes of the PIN_block_MAC parameter. If the rule_array indicates that no PIN block MAC should be returned, this value must be 0. Otherwise, it must be at least 8.
PIN_block_MAC
Direction: Output
Type: String
The 8-byte MAC of the new encrypted PIN block. If the PIN_block_MAC_length is 0, this parameter is ignored.