Parameters

Edit online

The parameters for CSNBPTRE.

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 6 – 10.
rule_array
Direction: Input
Type: String array
A pointer to a string variable containing an array of keywords. The keywords are 8 bytes in length, and are left-aligned and padded on the right with space characters. The returned rule array keywords express the contents of the token.
Table 1. Keywords for Encrypted PIN Translate Enhanced control information

Keywords for Encrypted PIN Translate Enhanced control information
Keyword Description
Processing method (required)
VMDS Specifies that the VDSP method (Visa Data Secure Platform method, formally known as the Visa Merchant Data Secure (VMDS) method) is to be used for processing.
Mode (required)
REFORMAT Specifies that either the PIN-block format and the PIN-block encryption, or both, are to be changed. If the PIN-extraction method is not chosen by default, another element in the rule array must specify one of the keywords that indicates a PIN-extraction method.
Input PAN data key management method (one, required). These keywords are used to define the PAN-encrypting key used to decrypt the PAN_data parameter.
IN-DUKPT Specifies that the key to be used to decrypt the PAN data is to be derived using the key specified in the input_PIN_encrypting_key_identifier. See the description of the input_PIN_encrypting_key_identifier for the requirements of the key. The DUKPT-BH, DUKPT-IP, ADUKPTBH, or ADUKPTIP keyword is required.
OUTDUKPT Specifies that the key to be used to decrypt the PAN data is to be derived using the key specified in the output_PIN_encrypting_key_identifier. See the description of the output_PIN_encrypting_key_identifier for the requirements of the key. The DUKPT-BH, DUKPT-OP, ADUKPTBH, or ADUKPTOP keyword is required.
STATIC Specifies the use of static double length (2-key) Triple-DES symmetric keys for the PAN.
Input data algorithm (one, required)
TDES Specifies that Triple-DES encryption was used for the PAN.
Input data mode (one, required)
CBC Specifies that CBC mode encryption was used for the PAN. This is the mode for the Standard Encryption option.
VFPE Specifies that Visa format preserving encryption was used for the PAN.
PAN input character set (one, required)
PAN4BITX Specifies that the PAN data character set is 4-bit hex. Two digits per byte. Not valid with the CBC rule.
PAN8BITA Specifies that the PAN data character set is normal ASCII, represented in binary format. Not valid with CBC rule.
PAN-EBLK Specifies that the PAN data is in a CBC encrypted block. Valid only with CBC rule.
PAN check digit compliance (one required if mode VFPE and PAN input character set keyword are present, otherwise not allowed)
CMPCKDGT Last digit of the PAN contains a compliant check digit per ISO/IEC 7812-1.
NONCKDGIT Last digit of the PAN does not contain a compliant check digit per ISO/IEC 7812-1.
DES DUKPT (one, optional). These keywords are for PIN-encrypting keys. See Table 2 for valid DUKPT keyword combinations.
DUKPT-BH Specifies that the input and output PIN-encrypting keys are to be derived using the key-generating key specified in the respective parameters. See the descriptions of the input_PIN_encrypting_key_identifier and output_PIN_encrypting_key_identifier parameters for the requirements of the keys. This keyword cannot be specified with any of the keywords in the AES DUKPT group.
DUKPT-IP Specifies the use of DUKPT input-key derivation and PIN-block decryption, Triple-DES method. Specifies that the input PIN-encrypting key is to be derived using the key-generating key specified in the input_PIN_encrypting_key_identifier parameter. See the description of the input_PIN_encrypting_key_identifier parameter for the requirements of the key. This keyword cannot be specified with ADUKPTBH or ADUKPTIP.
DUKPT-OP Specifies that the output PIN-encrypting key is to be derived using the key-generating key specified in the output_PIN_encrypting_key_identifier parameter. See the description of the output_PIN_encrypting_key_identifier parameter for the requirements of the key. This keyword cannot be specified with ADUKPTBH or ADUKPTOP.
AES DUKPT (one, optional). See Table 2 for valid DUKPT keyword combinations.
ADUKPTBH Specifies that the input and output PIN-encrypting keys are to be derived with the AES DUKPT algorithm using the key-generating key specified in the respective parameters. See the descriptions of the input_PIN_encrypting_key_identifier and output_PIN_encrypting_key_identifier parameters for the requirements of the keys. This keyword cannot be specified with any of the keywords in the DES DUKPT group.
ADUKPTIP Specifies the use of DUKPT input-key derivation and PIN-block decryption. AES DUKPT method. Specifies that the input PIN-encrypting key is to be derived using the key-generating key specified in the input_PIN_encrypting_key_identifier parameter. See the description of this parameter for the requirements of the key. This keyword cannot be specified with DUKPT-BH or DUKPT-IP.
ADUKPTOP Specifies that the output PIN-encrypting key is to be derived with the AES DUKPT algorithm using the key-generating key specified in the output_PIN_encrypting_key_identifier parameter. See the description of this parameter for the requirements of the key. This keyword cannot be specified with DUKPT-BH or DUKPT-OP.
PIN-extraction method (one, optional).
If the PIN block format is provided, one of the PIN extraction method keywords shown in Table 2 can be specified for the given PIN block format.
Note: Specify the PIN block format keyword in the PIN_profile variable (see PIN block format).

The following PIN-block formats are supported:

  • 3624
  • ISO-0
  • ISO-1
  • ISO-2
  • ISO-3

The following S390 formats are also supported: VISA-2, VISA-3, VISA-4, OEM-1, ECI-2, ECI-3.

See PIN extraction methods for additional information. If the default extraction method for a PIN block format is desired, specify the rule_array_count value as 1.
input_PIN_encrypting_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the input_PIN_encrypting_key_identifier variable. Set this value to the length of the CCA AES or DES key token, TR-31 AES or DES key token, or label. If the input_PIN_encrypting_key_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the token and 9992.
input_PIN_encrypting_key_identifier
Direction: Input
Type: String

The identifier of the key to decrypt the input PIN block or the base derivation key to be used to derive the key to decrypt the input PIN block. The base derivation key can optionally be used to derive the key to decrypt the PAN data. The key identifier is an operational fixed-length CCA DES key-token, variable-length CCA AES key-token, TR-31 AES or DES key token, or the key label of such a record in key-storage.

If you do not use the DUKPT process or you specify the ADUKPTOP rule array keyword, the key token must contain the PIN-encrypting key to be used to decipher the input PIN block. If you use a CCA key, then the token must be DES, the key type must be IPINENC, and the key usage REFORMAT bit must be enabled.

If you use a TR-31 key, then the token must be a DES IPINENC key. Therefore, it must have the following attributes:

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

If you use the DES-DUKPT process for the input PIN block by specifying the DUKPT-IP or DUKPT-BH rule array keyword, the key token must contain the base derivation key to derive the PIN-encrypting key. If you have also specified the IN-DUKPT keyword, the key will be used to derive the key to decrypt the PAN data.

If you use a CCA key, then the token must be a DES KEYGENKY key with the UKPT key usage bit enabled.

If you use a TR-31 key, then the token must be a DES KEYGENKY. Therefore, it must have the following attributes:

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

If you use the AES-DUKPT process for the input PIN block by specifying the ADUKPTIP or ADUKPTBH rule array keywords, the key token must contain the base derivation key to derive the PIN-encrypting key. If you have also specified the IN-DUKPT keyword, the key will be used to derive the key to decrypt the PAN data.

If you use a CCA key, then the base derivation key must be an AES variable-length symmetric key-token, version X’ 05 AES DKYGENKY with Key-usage field 1, low-order byte, most significant bit set to 1 indicating this key is allowed to be used as BDK.

If you use a TR-31 key, then the token must be an AES DKYGENKY. Therefore, it must have the following attributes:

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

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

output_PIN_encrypting_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the output_PIN_encrypting_key_identifier variable. If the output_PIN_encrypting_key_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the AES or DES key token and 9992.
output_PIN_encrypting_key_identifier
Direction: Input
Type: String

A pointer to a string variable containing an operational fixed-length CCA DES key-token, variable-length CCA AES key-token, TR-31 AES or DES key token, or the key label of such a record in key-storage.

This is the identifier of the key to encrypt the output PIN block or the base derivation key to be used to derive the key to encrypt the output PIN block. The base derivation key can optionally be used to derive the key to encrypt the PAN data. The key identifier is an operational token or the key label of an operational token in key storage.

If you do not use the DUKPT process or you specify the DUKPT-IP or ADUKPTIP rule array keyword, the key token must contain the PIN-encrypting key to be used to encipher the output PIN block. If you use a CCA key, then it must be DES, the key type must be OPINENC, and the key usage REFORMAT bit must be enabled.

If you use a TR-31 key, then it must be a DES OPINENC key. Therefore, it must have the following attributes:

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

If you use the DES DUKPT process for the output PIN block by specifying the DUKPT-OP or DUKPT-BH rule array keyword, the key token must contain the base derivation key to derive the PIN-encrypting key. If you have also specified the OUTDUKPT keyword, the key will be used to derive the key to encrypt the PAN data. If you use a CCA key, then it must be a DES KEYGENKY key with the UKPT key usage bit enabled.

If you use a TR-31 key, then it must be a DES KEYGENKY key. Therefore, it must have the following attributes:

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

If you use the AES DUKPT process for the output PIN block by specifying the ADUKPTOP or ADUKPTBH rule array keyword, the key token must contain the base derivation key to derive the PIN-encrypting key. If you have also specified the OUTDUKPT keyword, the key will be used to derive the key to encrypt the PAN data. If you use a CCA key, then it must be an AES DKYGENKY key with the A-DUKPT bit set to 1 in the low-order byte of key usage field 1.

If you use a TR-31 key, then it must be an AES DKYGENKY key. Therefore, it must have the following attributes:

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

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

PAN_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the PAN_key_identifier variable. Set the value to 0 if the PAN key management method keyword specifies DUKPT. If the PAN key management method specifies STATIC, then the value must be between the actual length of the TR-31 or CCA DES key token and 9992.
PAN_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing an internal fixed-length CCA or TR-31 DES key-token or the key label of such a record in DES key-storage. The key is used to decipher the input PAN data.

This token contains a double-length data decryption key if the input PAN data key management method is STATIC. If using a CCA key token, then it must contain a double-length data encryption key (Zone Encryption Key in the VDSP specification), and the token must have a key type of CIPHER or DECIPHER.

If you use a TR-31 key, then it must contain a DES CIPHER or DECIPHER key. Therefore, it must have the following attributes:

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

If IN-DUKPT is specified as the input PAN data key management method, the base derivation key in the input_PIN_encrypting_key_identifier parameter is used to create the decryption key for the PAN.

If OUTDUKPT is specified as the input PAN data key management method, the base derivation key in the output_PIN_encrypting_key_identifier parameter is used to create the decryption key for the PAN.

This parameter is not used if IN-DUKPT or OUTDUKPT is specified.

The key identifier is an operational token or the key label of an operational token in key storage. The key algorithm must be DES, the key type must be CIPHER or DECIPHER and the key must be a double-length key.

Note: DATA keys with ENC or DEC bits on are not supported. Also, zero CV data keys are not supported.
input_PIN_profile_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the input_PIN_profile variable. Set the length according to the values shown in Table 2.
Table 2. Supported Encrypted PIN Translate2 PIN profile lengths
Pin profile Length
PIN-block format only. 24
PIN-block format and CKSN extension used for DES-DUKPT. 48
PIN-block format and single block of derivation data extension used for AES-DUKPT. 44
input_PIN_profile
Direction: Input
Type: String

The 24, 44, or 48 byte input PIN profile. The profile consists of three 8-byte character strings with information defining the input PIN-block format.

When the keywords DUKPT-BH, DUKPT-IP or IN-DUKPT are specified, additional bytes must be present containing CKSN. When the keywords ADUKPTBH, ADUKPTIP or IN-DUKPT are specified, additional bytes must be present containing Derivation Data structure.

The CKSN extension is a 24-byte structure which specifies DES DUKPT input parameters and Derivation Data is 20-byte hex structure which specifies AES DUKPT input parameters. DES DUKPT algorithm will be used to derive the DUKPT key in the input_PIN_encrypting_key_identifier when CKSN extension is included and AES DUKPT algorithm will be used when Derived Data extension is included in the input_PIN_profile parameter.

When specifying the AES DUKPT method, this parameter includes a pointer to a hex data structure containing the 20-byte Derivation Data structure. Bytes 4 and 5, Algorithm Indicator, must be set to 0x0000 (2-key TDEA) or 0x0001 (3-key TDEA). Bytes 2 and 3, key Usage Indicator, must be set to 0x1000 (PIN Encryption). See Table 1 for the layout of the AES-DUKPT derivation data extension.
PAN_data_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the PAN_data parameter if the mode is CBC. If the mode is VFPE, this variable contains the number of PAN digits. The value is in the range 15 - 19 for VFPE. It is 16 if the standard encryption option is selected.
PAN_data
Direction: Input
Type: String
A pointer to a string variable containing the PAN data. For VFPE mode, if the PAN contains an odd number of 4-bit hex digits, the data must be left justified in the PAN variable and the right-most 4 bits are ignored. The verb uses this data to recover the PIN from the PIN block if you specify the REFORMAT keyword and the input PIN profile specifies the ISO-0, VISA-4 or ISO-3 keyword for the PIN-block format. If the output PIN profile specifies the ISO-0, VISA-4, or ISO-3 keyword for the PIN-block format, the 12 rightmost digits of the (decrypted) PAN, excluding the check digit, are used to format the output PIN block.
input_PIN_block_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the encrypted input PIN block. The value must be 8.
input_PIN_block
Direction: Input
Type: String
A pointer to a string variable containing the encrypted PIN-block.
output_PIN_profile_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the output_PIN_profile variable. See Table 2 for the supported PIN profile lengths.
output_PIN_profile
Direction: Input
Type: String

The 24, 44, or 48 byte output PIN profile. The profile contains three 8-byte character strings with information defining the PIN-block format and optionally followed by either an additional 24 bytes containing the input CKSN extension or an additional 20 bytes containing the input Derivation Data structure. See The PIN profile for additional information.

If the rule array keyword UKPTBOTH or UKPTOPIN is specified, CKSN extension must be included in the output_PIN_profile. Single-DES DUKPT algorithm will be used to derive the DUKPT key used to encrypt the output PIN block.

If the rule array keyword DUKPT-BH or DUKPT-OP is specified, CKSN extension must be included in the output_PIN_profile. The Triple-DES DUKPT algorithm will be used to derive the DUKPT key used to encrypt the output PIN block.

If the rule array keyword ADUKPTBH or ADUKPTOP is specified, the AES-DUKPT algorithm will be used to derive the DUKPT key used to encrypt the output PIN block when the Derivation Data extension is included in the output_PIN_profile. See The PIN profile for the layout of the AES-DUKPT Derivation Data structure. The algorithm indicator must be set to X'0000' (2-key TDES), X'0001' (3-key TDES), X'0002' (AES-128), X'0003' (AES-192), or X'0004' (AES-256). The key usage indicator must be set to X'1000' (PIN Encryption).

sequence_number
Direction: Input
Type: Integer
A pointer to an integer variable containing the sequence number. Ensure that the referenced integer variable is valued to 99999 if the output PIN block format is 3621 or 4704-EPP. Otherwise, this parameter is ignored.
output_PIN_block_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the re-enciphered PIN block. The value must be at least 8.
output_PIN_block
Direction: Output
Type: String
A pointer to a string variable containing the re-enciphered and, optionally, reformatted PIN-block returned by the verb. The buffer can be larger on input. However, on output this field is updated to indicate the actual number of bytes returned by the card.
reserved1_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the reserved1 variable. This value must be zero.
reserved1
Direction: Input/Output
Type: String
A pointer to a string variable. This parameter is reserved for future use.
reserved2_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the reserved2 variable. This value must be zero.
reserved2
Direction: Output
Type: String
A pointer to a string variable. This parameter is reserved for future use.