Parameters

Edit online

The parameters for CSNBPTR.

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

input_PIN_encrypting_key_identifier
Direction: Input/Output
Type: String
The input PIN-encrypting key (IPINENC) for the input_PIN_block parameter specified as a 64-byte internal key token or a key label. If keyword UKPTOPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH is specified in the rule_array parameter, the input_PIN_encrypting_key_identifier must specify a key token or key label of a KEYGENKY with the UKPT usage bit enabled.

If you do not use the DES DUKPT process or you specify the UKPTIPIN or DUKPT-IP rule-array keyword, the key token must contain the input PIN-block encrypting key to be used to decrypt the input PIN- block. The control vector in the key token must specify the IPINENC key-type and have one or both of the TRANSLAT and REFORMAT bits set to B'1' as appropriate for the requested mode.

If you use the DES DUKPT process for the input PIN-block by specifying the UKPTOPIN, UKPTBOTH, DUKPT-OP, or DUKPT-BH keyword, specify the base derivation key as a KEYGENKY key- type with the UKPT bit set to B'1'.

If you use the AES DUKPT process for the input PIN-block by specifying ADUKPTIP or ADUKPTBH keywords, specify the base derivation key as 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.

output_PIN_encrypting_key_identifier
Direction: Input/Output
Type: String
The output PIN-encrypting key (OPINENC) for the output_PIN_block parameter specified as a 64-byte internal key token or a key label. If keyword UKPTOPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH is specified in the rule_array, the output_PIN_encrypting_key_identifier must specify a key token or key label of a KEYGENKY with the UKPT usage bit enabled.

If you do not use the DES DUKPT process or you specify the UKPTOPIN or DUKPT-OP keyword, the key token must contain the output PIN-block encrypting key to be used to encrypt the output PIN block. The control vector in the key token must specify the OPINENC key type and have one or both of the TRANSLAT and REFORMAT bits set to B'1' as appropriate for the requested mode.

If you use the DES DUKPT process for the output PIN-block by specifying the UKPTIPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH keyword, specify the base derivation key as a KEYGENKY key- type with the UKPT bit set to B'1'.

If you use the AES DUKPT process for the input PIN-block by specifying ADUKPTOP or ADUKPTBH keywords, specify the base derivation key as 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.

input_PIN_profile
Direction: Input
Type: String
The three 8-byte character elements that contain information necessary to either create a formatted PIN block or extract a PIN from a formatted PIN block, and optionally containing additional 24 bytes containing the input CKSN extension used when a DES unique key per transaction keyword is specified in the rule array, or an additional 20 bytes containing the input Derivation Data extension when an AES DUKPT keyword is specified. The strings are equivalent to 24-byte, 44-byte or 48-byte data structures. The first 24 bytes are ignored when TRANSLAT is specified in the rule array.

A particular PIN profile can be either an input PIN profile or an output PIN profile depending on whether the PIN block is being enciphered or deciphered by the verb. See The PIN profile for additional information.

If you choose the TRANSLAT processing rule or the REFORMAT processing rule in the rule_array parameter, the input PIN profile and output PIN profile can have different PIN block formats. If you specify UKPTIPIN with DUKPT-IP or UKPTBOTH with DUKPT-BH in the rule_array parameter, the input_PIN_profile is extended to a 48-byte field and must contain the current key serial number. See The PIN profile for additional information.

The pad digit is needed to extract the PIN from a 3624 or 3621 PIN block in the Encrypted PIN Translate verb with a process rule (rule_array parameter) of REFORMAT. If the process rule is TRANSLAT, the pad digit is ignored.

The PINLENnn keywords are disabled for this verb by default. If these keywords are used, return code 8 with reason code 33 is returned. To enable them, the Enhanced PIN Security access control point (bit X'0313') must be enabled using a TKE.

If the keyword UKPTBOTH or UKPTIPIN is specified, CKSN extension must be included in the input_PIN_profile. Single-DES DUKPT algorithm will be used to derive the DUKPT key used to decrypt the input PIN block. If the keyword DUKPT-BH or DUKPT-IP is specified, input_PIN_profile must include CKSN extension and the triple-DES DUKPT algorithm is used to derive the DUKPT key used to decrypt the input PIN block. If the keyword ADUKPTIP or ADUKPTH is specified, input_PIN_profile must include Derivation Data extension and the AES DUKPT algorithm is used to derive the key used to decrypt the input PIN block.

When you specify the AES DUKPT method, the Derivation Data extension of the input_PIN_profile parameter is a pointer to a hex data structure containing the 20-byte Derivation Data structure described in AES-DUKPT derivation data. 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).

input_PAN_data
Direction: Input
Type: String
The personal account number (PAN) if the process rule (rule_array parameter) is REFORMAT and the input PIN format is ISO-0, ISO-3, or VISA-4 only. Otherwise, this parameter is ignored. Specify 12 digits of account data in character format.

For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit.

For VISA-4, use the leftmost 12 digits of the PAN, excluding the check digit.

input_PIN_block
Direction: Input
Type: String
The 8-byte enciphered PIN block that contains the PIN to be translated.
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
The process rule for the verb is described in Table 1.
Table 1. Keywords for Encrypted PIN Translate control information

Keywords for Encrypted PIN Translate control information
Keyword Description
Processing rule (One, required)
REFORMAT Changes the PIN format, the contents of the PIN block, and the PIN-encrypting key.
TRANSLAT Changes the PIN-encrypting key only. It does not change the PIN format and the contents of the PIN block.
PIN block format and PIN extraction method (Optional) See PIN extraction methods for additional information and a list of PIN block formats and PIN extraction method keywords.
Note: If a PIN extraction method is not specified, the first one listed in Table 2 for the PIN block format will be the default.
DES DUKPT keywords - Single length key derivation (One, optional)
UKPTBOTH Both the input_PIN_encrypting_key_identifier and the output_PIN_encrypting_key_identifier are derived as a single length key. Both the input_PIN_encrypting_key_identifier and the output_PIN_encrypting_key_identifier must be KEYGENKY keys with the UKPT usage bit enabled. Both the input_PIN_profile and the output_PIN_profile must be 48 bytes and contain the respective key serial number. This keyword cannot be specified with any of the keywords in AES DUKPT group.
UKPTIPIN The input_PIN_encrypting_key_identifier is derived as a single length key. The input_PIN_encrypting_key_identifier must be a KEYGENKY key with the UKPT usage bit enabled. The input_PIN_profile must be 48 bytes and contain the key serial number. This keyword cannot be specified with the ADUKPTIP keyword.
UKPTOPIN The output_PIN_encrypting_key_identifier is derived as a single length key. The output_PIN_encrypting_key_identifier must be a KEYGENKYY key with the UKPT usage bit enabled. The output_PIN_profile must be 48 bytes and contain the key serial number. This keyword cannot be specified with the ADUKPTOP keyword.
DES DUKPT keywords - double length key derivation (One, optional)
DUKPT-BH Both the input_PIN_encrypting_key_identifier and the output_PIN_encrypting_key_identifier are derived as a double length key. Both the input_PIN_encrypting_key_identifier and the output_PIN_encrypting_key_identifier must be KEYGENKY keys with the UKPT usage bit enabled. Both the input_PIN_profile and the output_PIN_profile must be 48 bytes and contain the respective key serial number. This keyword cannot be specified with any of the keywords in AES DUKPT group.
DUKPT-IP The input_PIN_encrypting_key_identifier is derived as a double length key. The input_PIN_encrypting_key_identifier must be a KEYGENKY key with the UKPT usage bit enabled. The input_PIN_profile must be 48 bytes and contain the key serial number. This keyword cannot be specified with the ADUKPTIP keyword.
DUKPT-O The output_PIN_encrypting_key_identifier is derived as a double length key. The output_PIN_encrypting_key_identifier must be a KEYGENKY key with the UKPT usage bit enabled. The output_PIN_profile must be 48 bytes and contain the key serial number. This keyword cannot be specified with the ADUKPTOP keyword.
AES DUKPT (one, optional). Valid for AES keys only. See Table 2 for valid DUKPT keyword combinations.
ADUKPTBH Specifies the use of AES DUKPT key-derivation and PIN-block ciphering for both input and output processing. This keyword cannot be specified with any of the keywords in the DES DUKPT groups.
ADUKPTIP Specifies the use of AES DUKPT key-derivation and PIN-block ciphering for input processing. This keyword cannot be specified with UKPTIPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH.
ADUKPTOP Specifies the use of AES DUKPT key-derivation and PIN-block ciphering for output processing. This keyword cannot be specified with UKPTOPIN, UKPTBOTH, DUKPT-OP, or DUKPT-BH.
PIN-extraction method (one, optional).
HEXDIGIT Specifies to use the first occurrence of a digit in the range from X'A' to X'F' as the pad value to determine the PIN length. Only valid with PIN-block format 3624.
PADDIGIT Specifies to use the pad value in the PIN profile to identify the end of the PIN. Only valid with PIN-block format 3624. This is the default for 3624.
PADEXIST Specifies to use the character in the sixth position of the PIN block as the value of the pad value. Only valid with PIN-block format 3624.
PINBLOCK Specifies to use one of the following items to identify the PIN, depending on the contents of the PIN block:
  • The PIN length, if the PIN block contains a PIN-length field.
  • The PIN-delimiter character, if the PIN block contains a PIN-delimiter character.

Only valid with PIN-block format ISO-0, ISO-1, ISO-2, or ISO-3. This is the default for ISO-0, ISO-1, ISO-2, or ISO-3.
PINLENxx Specifies Specifies to use the length xx specified in the keyword as the length in digits of the PIN, where xx is 04, 05, 06, ..., 16. For example, specify PINLEN04 for a PIN length of 4. Only valid with PIN block format 3624.

PIN-block format ISO-2 generation is not allowed when the Disallow ISO-2 PIN block translate command (offset X'0087') is enabled in the active role (Release 7.5 and 8.2 or later).

output_PIN_profile
Direction: Input
Type: String
The three 8-byte character elements that contain information necessary to either create a formatted PIN block or extract a PIN from a formatted PIN block. A particular PIN profile can be either an input PIN profile or an output PIN profile, depending on whether the PIN block is being enciphered or deciphered by the verb.
  • If you choose the TRANSLAT processing rule in the rule_array parameter, the input_PIN_profile and the output_PIN_profile must specify the same PIN block format.
  • If you choose the REFORMAT processing rule in the rule_array parameter, the input PIN profile and output PIN profile can have different PIN block formats.
  • If you specify UKPTOPIN or UKPTBOTH in the rule_array parameter, the output_PIN_profile is extended to a 48-byte field and must contain the current key serial number. See The PIN profile for additional information.
  • Also, if you specify UKPTOPIN or UKPTBOTH, CKSN extension must be included in the output_PIN_profile. A Single-DES DUKPT algorithm is used to derive the DUKPT key used to encrypt the output PIN block.
  • If you specify the keyword DUKPT-BH or DUKPT-OP, the output_PIN_profile must include CKSN extension and a Triple-DES DUKPT algorithm is used to derive the DUKPT key used to encrypt the output PIN block.
  • Also, if you specify DUKPT-OP or DUKPT-BH, the output_PIN_profile is extended to a 48-byte field and must contain the current key serial number. See The PIN profile for additional information.
  • If you specify the keyword ADUKPTOP or ADUKPTBH, output_PIN_profile must include Derived Data extension and an AES-DUKPT algorithm is used to derive the encryption key to encrypt the output PIN lock.

When you specify the AES DUKPT method, the output_PIN_profile parameter is a pointer to a hex data structure containing the 20-byte Derivation Data data structure described in AES-DUKPT derivation data. 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).

output_PAN_data
Direction: Input
Type: String
The personal account number (PAN) if the process rule (rule_array parameter) is REFORMAT and the output PIN format is ISO-0, ISO-3, or VISA-4 only. Otherwise, this parameter is ignored. Specify 12 digits of account data in character format.

For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit.

For VISA-4, use the leftmost 12 digits of the PAN, excluding the check digit.

sequence_number
Direction: Output
Type: Integer
The sequence number if the process rule (rule_array parameter) is REFORMAT and the output PIN block format is 3621 or 4704-EPP only. Specify the integer value 99999. Otherwise, this parameter is ignored.
output_PIN_block
Direction: Input
Type: String
The 8-byte output PIN block that is re-enciphered.