Parameters

Edit online

The parameters for CSNBPTR2.

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
A pointer to an integer variable containing the number of 8-byte elements in the rule_array variable. This value must be in the range 1 - 5.
rule_array
A pointer to a string variable containing an array of keywords. Each element in the array must contain a valid keyword that is left-aligned and padded on the right as needed with space characters. The rule_array keywords are:
Table 1. Keywords for Encrypted PIN Translate2 control information
Keyword Meaning
Mode (one required)
REFORMAT Specifies that either or both the PIN-block format and the PIN-block encryption 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.
TRANSLAT Specifies that only PIN-block encryption is changed. The first 24 bytes of PIN profiles are not ignored.
PAN-change option (one, optional). Only valid with ISO-4 PIN block processing and REFORMAT mode.
PAN-CHG Specifies that a PAN change is requested.
Plaintext PAN field format for CMAC message Only valid if all the following are true: (1) PAN-CHG is specified, (2) the Encrypted PIN Translate2 - Permit ISO-4 Reformat w/ PAN Chg command (offset X'038B') is enabled in the active role, and (3) the input and output PIN-block formats are both ISO-4.
PANAUTAS Specifies the plaintext PAN field format for the message used to calculate the CMAC provided in the authentication_data variable is ASCII data, one ASCII character per PAN digit (that is, Old PAN = input_PAN_data and New PAN = output_PAN_data). This is the default.
PANAUTI4 Specifies the plaintext PAN field format for the message used to calculate the CMAC provided in the authentication_data variable is according to ISO 9564-1, as shown in Table 2.
DES DUKPT (one, optional). Valid for DES keys only. See Table 2 for valid DUKPT keyword combinations.
DUKPT-BH Specifies the use of DUKPT key-derivation and PIN-block ciphering for both input and output processing, Triple-DES method. 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. This keyword cannot be specified with ADUKPTBH or ADUKPTIP.
DUKPT-OP Specifies the use of DUKPT output-key derivation and PIN-block encryption, Triple-DES method. This keyword cannot be specified with ADUKPTBH or ADUKPTOP.
UKPTBOTH Specifies the use of DUKPT key-derivation and PIN-block ciphering for both input and output processing, Single-DES method. This keyword cannot be specified with any of the keywords in the AES DUKPT group.
UKPTIPIN Specifies the use of DUKPT input-key derivation and PIN-block decryption, Single-DES method. This keyword cannot be specified with ADUKPTBH or ADUKPTIP.
UKPTOPIN Specifies the use of DUKPT output-key derivation and PIN-block encryption, Single-DES method. This keyword cannot be specified with ADUKPTBH or ADUKPTOP.
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 group.
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). PIN-block format is specified by the first 8-byte element of the input_PIN_profile variable. See The PIN profile.
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 when PIN-block format is 3624.
PADDIGIT Specifies to use the pad value in the PIN profile to identify the end of the PIN. Only valid when PIN-block format is 3624. This is the default for an IBM 3624 PIN-block format.
PADEXIST Specifies to use the character in the sixth position of the PIN block as the value of the pad. Only valid when PIN-block format is 3624.
PINBLOCK Specifies to use one of the following to identify the PIN:
  • 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 when PIN-block format is ISO (ISO-0, ISO-1, ISO-2, ISO-3, or ISO-4). This is the default for an ISO PIN-block format.
PINLENxx Specifies the length of the PIN to use, where xx is 04, 05, 06, …, 16. For example, for a PIN length of 4 digits, specify keyword PINLEN04. Only valid when PIN-block format is 3624.
input_PIN_encrypting_key_identifier_length
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. The maximum value is 9992. A key label must be at least 64 bytes, and only the first 64 bytes of a key label are used.
input_PIN_encrypting_key_identifier
A pointer to a string variable that identifies either an operational fixed-length DES key token, a variable-length AES key-token, a TR-31 AES or DES key token, or the label of such a record in key storage.

This is either the identifier of the key to decrypt the input PIN-block or the identifier of the key-generating key to be used to derive the key to decrypt the input PIN-block. The key identifier must identify an AES key if the input PIN profile specifies a PIN-block format of ISO-4, otherwise it must identify a DES key.

  • For DES keys:

    If you do not use the DUKPT process or you specify the UKPTOPIN or DUKPT-OP rule_array keyword, and you use a CCA key, then the it must be a DES PIN block encrypting key of type IPINENC and has one or both of the TRANSLAT and REFORMAT key usage bits enabled as appropriate for the requested mode.

    If you use a TR-31 key, then it 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 DUKPT process for the input PIN block by specifying the UKPTIPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH rule_array keyword, and you use a CCA key, then it must be a CCA DES base derivation key of KEYGENKY key type with key usage UKPT 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
  • For AES keys ( PIN-block format of ISO-4):

    If you do not use the DUKPT process or you specify the ADUKPTOP rule array keyword, and you use a CCA key, then it must be an AES PIN block encrypting key of type PINPROT with one or both of the PINXLATE and REFORMAT key usage field bits enabled as appropriate for the requested mode. The key usage fields must have the decryption operation set so that the key can be used for decryption (DECRYPT), but not encryption, and the encryption mode of Cipher Block Chaining (CBC) must be specified. And if you use a TR-31 key, then it must be a PINPROT AES key. Therefore, it must have the following attributes:

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

    If you use the AES DUKPT process for the input PIN block by specifying the ADUKPTIP or ADUKPTBH rule_array keyword and the input_PIN_profile parameter contains AES-DUKPT derivation data, then specify the base derivation key as a CCA or TR-31 AES key. If you use a CCA AES key, then it must be a 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 AES key, then it 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
output_PIN_encrypting_key_identifier_length
A pointer to an integer variable containing the number of bytes of data in the output_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. The maximum value is 9992 A key label must be at least 64 bytes, and only the first 64 bytes of a key label are used.
output_PIN_encrypting_key_identifier
A pointer to a string variable that identifies either an operational fixed-length DES key-token, a variable-length AES key token, a TR-31 AES or DES key token, or the label of such a record in key storage.

This is either the identifier of the key to encrypt the output PIN-block or the identifier of the key-generating key to be used to derive the key to use to encrypt the output PIN-block. The key identifier must identify an AES key if the output PIN profile specifies a PIN-block format of ISO-4, otherwise it must identify a DES key.

For DES keys
If you do not use the DUKPT process or you specify the UKPTIPIN or DUKPT-IP rule array keyword, and you use a CCA key, then the key is a DES PIN block encrypting key of type OPINENC and has one or both of the TRANSLAT and REFORMAT key usage bits enabled as appropriate for the requested mode.

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

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

If you use the DUKPT process for the output PIN-block by specifying the UKPTOPIN, UKPTBOTH, DUKPT-OP, or DUKPT-BH rule array keyword, and you use a CCA key, then the key must be a DES base derivation key of KEYGENKY key type with key usage UKPT enabled.

If you use a TR-31 key, then it 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
For AES keys (ISO-4 PIN block)
If you do not use the DUKPT process or you specify the ADUKPTIP rule array keyword, and you use a CCA key, then this key must be an AES PIN block encrypting key of type PINPROT with one or both of the PINXLATE and REFORMAT key usage field bits enabled as appropriate for the requested mode. The key usage fields must have the encryption operation set so that the key can be used for encryption (ENCRYPT), but not decryption, and the encryption mode of Cipher Block Chaining (CBC) must be specified.

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

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

If you use the AES DUKPT process for the output PIN block by specifying the ADUKPTOP or ADUKPTBH rule array keywords and the output_PIN_profile contains AES-DUKPT derivation data, then specify the base derivation key as a CCA or TR-31 AES variable-length symmetric key-token. If you use a CCA key, it must be a 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 AES 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
authentication_key_identifier_length
A pointer to an integer variable containing the number of bytes of data in the authentication_key_identifier variable. When (1) PAN-CHG is specified in the rule array, (2) the Encrypted PIN Translate2 - Permit ISO-4 Reformat w/ PAN Chg command (offset X'038B') is enabled in the active role, and (3) the input and output PIN-block formats are both ISO-4, the length must be greater than 0 and the maximum length is 9992. Otherwise, set this value to either 0, the length of an AES null key-token, or the length of a key label for an AES null key-token.
authentication_key_identifier
A pointer to a string variable that identifies a null or operational variable-length CCA or TR-31 AES key-token, or the label of such a record in key storage.

When (1) PAN-CHG is specified in the rule array, (2) the PTR2 ISO-4 Reformat Requires Authenticated PAN Change to Change the PAN command (offset X'038B') is enabled in the active role, and (3) the input and output PIN-block formats are both ISO-4, the verb performs an authenticated PAN change. Otherwise, a PAN change is not authenticated and either the authentication_key_identifier_length variable must be 0 or the authentication_key_identifier parameter must identify an AES null key-token.

If the verb is to perform an authenticated PAN change, this key is used to verify the CMAC found in the authentication_data variable, and successful verification is required to authorize a PAN change request.

If using a CCA key token, the algorithm of this key must be AES and the key type must be MAC. In addition, the key usage fields must indicate a MAC operation of VERIFY and a MAC mode of CMAC. When keyword PAN-CHG is specified in the rule array, and required command PTR2 ISO-4 to ISO-4 Reformat Requires PTR2AUTH Usage when Authenticated PAN Change Is Required (offset X'0395') is enabled in the active role, this key must have key usage PTR2AUTH.

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

  • TR-31 key usage: M6
  • Algorithm: A
  • TR-31 mode of key use: V
input_PIN_profile_length
A pointer to an integer variable containing the number of bytes of data in the input_PIN_profile variable. Set the value according to 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

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 and optionally followed by either an additional 24 bytes containing the input CKSN extension or an additional 20 bytes containing the input Derivation Data extension. See The PIN profile for additional information.

If the rule array 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 rule array keyword DUKPT-BH or DUKPT-IP is specified, CKSN extension must be included in the input_PIN_profile. The Triple-DES DUKPT algorithm will be used to derive the DUKPT key used to decrypt the input PIN block.

If the rule array keyword ADUKPTBH or ADUKPTIP is specified, the AES-DUKPT algorithm will be used to derive the DUKPT key used to decrypt the input PIN block when the derivation data extension is included in the input_PIN_profile. See Table 1 for the layout of the AES-DUKPT derivation data extension. 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).
input_PAN_data_length
A pointer to an integer variable containing the number of bytes of data in the input_PAN_data variable. Set this value to 10 – 19 if keyword REFORMAT is specified in the rule array and keyword ISO-0, ISO-3, or ISO-4 is specified for the PIN-block format in the input PIN profile, otherwise this value must be 0.
input_PAN_data
A pointer to a string variable containing the PAN data used to recover the PIN from the PIN block if keyword REFORMAT is specified in the rule array and keyword ISO-0, ISO-3, or ISO-4 is specified for the PIN-block format in the input PIN profile. This parameter is required to successfully process an ISO-4 PIN block for both TRANSLAT and REFORMAT modes.

When the PIN block format is ISO-4, the PAN is used to format the output PIN block. The PAN check digit is included in the formation. The PAN check digit is excluded in the test used to determine if the PAN of an ISO-4 PIN block is equivalent to a PAN that is in a non-ISO format 4 PIN block.

Notes:
  1. When using the ISO-0 or ISO-3 PIN-block format, use the 12 rightmost digits of the PAN, excluding the check digit.
  2. No PAN check digit is included in the formation of an output PIN block that is not ISO-4.
  3. No PAN check digit is included in the test to determine if the PAN in an ISO-4 PIN-block is equivalent to a PAN that is not in an ISO-4 PIN block.
input_PIN_block_length
A pointer to an integer variable containing the number of bytes of data in the input_PIN_block variable. The value must be 8 for DES or 16 for AES.
input_PIN_block
A pointer to a string variable containing the encrypted PIN-block.
output_PIN_profile_length
A pointer to an integer variable containing the number of bytes of data in the output_PIN_profile variable. Set the value according to Table 2 for the supported PIN profile lengths.
output_PIN_profile

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).

When the mode rule is TRANSLAT, the first 24 bytes of this parameter are ignored.

When the mode rule is REFORMAT in the rule array, the input PIN profile and output PIN profile can have different PIN block formats.

When UKPTOPIN or UKPTBOTH is specified, the parameter is extended to a 48-byte field and must contain the output current key serial number (CKSN).

When DUKPT-OP or DUKPT-BH is specified, the parameter is extended to a 48-byte field and must contain the output current key serial number (CKSN).

output_PAN_data_length
A pointer to an integer variable containing the number of bytes of data in the output_PAN_data variable. If the PAN-CHG keyword is specified in the rule array or the output PIN profile specifies ISO-0, ISO-3, or ISO-4, this value must be 10 – 19. Otherwise, set this value to 0.
output_PAN_data
A pointer to an optional string variable containing the new primary account number (PAN) data.
  • If the REFORMAT keyword is specified in the rule array and output PIN profile keyword ISO-0, ISO-3, or ISO-4 is specified for the ISO format PIN-block in the output PIN profile (that is, PAN data is available), the verb requires this data to format the output PIN-block.
  • If the PAN-CHG keyword is specified in the rule array, the verb uses the authenticated PAN change method to verify authorization to change the PAN. Otherwise, the access control point method is used to authorize changing the PAN if the input_PAN_data and the output_PAN_DATA values do not match.
Note: When using the ISO-0, ISO-3, or VISA-4 PIN-block format, use the 12 rightmost digits of PAN, excluding the check digit. When using the ISO-4 PIN-block format, the PAN check digit is included in the formation of the PIN blocks.
authentication_data_length
A pointer to an integer variable containing the number of bytes of data in the authentication_data variable. If (1) PAN-CHG is specified in the rule array, (2) the PTR2 ISO-4 Reformat Requires Authenticated PAN Change to Change the PAN command (offset X'038B') is enabled in the active role, and (3) the input and output PIN-block formats are both ISO-4, the verb performs an authenticated PAN change, in which case the value must be a minimum of 2 + 8 + 2 + 0 = 12 up to a maximum of 2 + 16 + 2 + 256 = 276. Otherwise, the value must be 0.
authentication_data
A pointer to a string variable that, when the authentication_data_length variable is greater than 0, contains the MAC that the verb must verify when an authenticated PAN change is required. The variable has a length-value format as shown in the following table:
Offset (bytes) Length (bytes) Description
0 2 Length of NIST SP 800-38B CMAC, c, in bytes: x. Length is in big endian format, and valid values are 8 – 16 (X’0008’ – X’0010’).
2 x NIST SP 800-38B CMAC, c.

The data over which the MAC is calculated is an authentication value defined as follows:

  • Authentication value = Old PAN ∥ New PAN ∥ Optional additional authentication data
The plaintext PAN field format of the Old PAN data and the New PAN data is either ASCII (Old PAN = input_PAN_data and New PAN = output_PAN_data) or, beginning with Release 5.5.12, based on the plaintext PAN field format defined by ISO 9564-1 shown in Table 2. In releases before Release 5.5.12, the PAN format is always ASCII. In Release 5.5.12 or later, rule-array keyword PANAUTI4 specifies to format the input_PAN_data (Old PAN) and output_PAN_data (New PAN) according to ISO 9564-1. If keyword PANAUTI4 is not specified, the ASCII format is used.
2+x 2 Length of optional additional authentication data, a, in bytes: y. Length is in big endian format, and valid values are 0 – 256 (X’0000’ – X’0100’).
4+x y Optional additional authentication data value, a.

If the verb must perform an authenticated PAN change, the CMAC length can be 8 – 16. The verb creates a CMAC over the Old PAN data, New PAN data, and any additional authentication data. This MAC is compared to the CMAC, c, in this length-value structure for CMAC length x bytes. The PAN change request is only performed if the values match.

Note: The rule-array keyword PANAUTAS can be used to specify the format of the plaintext PAN fields in the message is ASCII. This is the default. If keyword PANAUTI4 is specified in the rule array, the verb formats both the input_PAN_dataand the output_PAN_data for the message using the PAN format specified by ISO 9564-1. Table 2 shows the format of an ISO 9564-1 plaintext PAN field.
output_PIN_block_length
A pointer to an integer variable containing the number of bytes of data in the output_PIN_block variable. On input, the value must be 8 for DES or 16 for AES. On output, the variable is updated with the actual length of the output_PIN_block variable.
output_PIN_block
A pointer to a string variable containing the re-enciphered and optionally reformatted PIN-block returned by the verb.
reserved1_length
A pointer to an integer variable containing the number of bytes of data in the reserved1 variable. This value must be 0.
reserved1
A pointer to a string variable. This parameter is reserved for future use.
reserved2_length
A pointer to an integer variable containing the number of bytes of data in the reserved2 variable. This value must be 0.
reserved2
A pointer to a string variable. This parameter is reserved for future use.
reserved3_length
A pointer to an integer variable containing the number of bytes of data in the reserved3 variable. This value must be 0.
reserved3
A pointer to a string variable. This parameter is reserved for future use.