Parameters

Edit online

The parameters for CSNBPVR2.

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

The number of keywords you supply in the rule array. The value must be 1, 2, or 3.

rule_array
Direction: Input
Type: String

Keywords that provide control information to the callable service. 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.

Table 1. Keywords for Encrypted PIN Verify2

Keywords for Encrypted PIN Verify2. This table contains two columns: Keyword and Meaning, and it contains rows for Processing rule (one required) and Input PIN unique key per transaction (one, optional).
Keyword Meaning
Processing rule (one required).
REFPIN Specifies that the input PIN is to be compared to the reference PIN.
TRUNCPIN Specifies that the input PIN is to be compared to a truncated version of the reference PIN for the number of digits specified by the PIN_check_length parameter.
Note: The digits of the PINs are checked from the rightmost digit to the left for the number of digits specified.
Input PIN unique key per transaction (one, optional). Valid with DES/TDES or AES keys.
UKPT Specifies the use of the single-DES method of DUKPT key derivation and PIN-block decryption for the input PIN encrypting key.
DUKPT Specifies the use of the triple-DES method of DUKPT key derivation and PIN-block decryption for the input PIN encrypting key.
ADUKPT Specifies the use of the AES DUKPT method of DUKPT key-derivation and PIN-block decryption for the input PIN encrypting key.
Input PIN-extraction method (one, optional). (one, optional). PIN-block format is specified by the first 8-byte element of the input_PIN_profile variable. See The PIN profile and PIN block format 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 is the default.
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-extraction method (one, optional). See PIN block format 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.
reference_PIN_rule_array_count
Direction: Input
Type: Integer

The number of keywords you supplied in the reference_PIN_rule_array parameter. The value must be 0, 1, or 2.

reference_PIN_rule_array
Direction: Input
Type: String
Keywords that provide process information for the reference PIN in the Encrypted PIN Verify2 callable service. 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.
Table 2. Keywords for Encrypted PIN Verify2

Keywords for Encrypted PIN Verify2. This table contains two columns: Keyword and Meaning, and it contains a row for reference PIN unique key per transaction (one, optional).
Keyword Meaning
Reference PIN unique key per transaction (one, optional).
UKPT Specifies the use of the single-DES method of DUKPT key derivation and PIN-block decryption for the reference PIN encrypting key.
DUKPT Specifies the use of the triple-DES method of DUKPT key derivation and PIN-block decryption for the reference PIN encrypting key.
ADUKPT Specifies the use of the AES DUKPT method of DUKPT key-derivation and PIN-block decryption for the reference PIN encrypting key.
Reference PIN-extraction method (one, optional). See PIN block format 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.
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.
PIN_check_length
Direction: Input
Type: Integer

A pointer to an integer variable containing the number of digits of PIN information that the verb should verify if TRUNCPIN is set. The specified number of digits is selected from the low order (right side) of the PIN. Ensure that this parameter always points to an integer variable in application storage.

If TRUNCPIN is set, the PIN check length must be less than or equal to the PIN length and in the range from 4 – 16. If REFPIN is set, this parameter must be 0.

input_PIN_encrypting_key_identifier_length
Direction: Input
Type: Integer

Specifies the length in bytes of the input_PIN_encrypting_key_identifier parameter. 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

This is either the identifier of the key to unwrap the input PIN block or the identifier of the key-generating key used to derive the key to unwrap the input PIN block. The key identifier is an operational token or the key label of an operational token in key storage.

The key identifier must identify an AES key when the input PIN profile specifies a PIN-block format of ISO-4. Otherwise, it must identify a DES key.

For CCA DES keys, the control vector in the key token must specify the IPINENC key-type with EPINVER bit (CV bit 19) set to B'1'.

  • For TR-31 DES keys, the token must have the following attributes:
    • TR-31 key usage: P0
    • Algorithm: T
    • TR-31 mode of key use: D

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 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 function usage EPINVER must be enabled.

  • For TR-31 AES keys, the token must have the following attributes:
    • TR-31 key usage: P0
    • Algorithm: A
    • TR-31 mode of key use: D
When any of the DUKPT rule array keywords are used for the input PIN encrypting key, the following applies:
  • When you use the DES DUKPT process for the input PIN-block:
    • For CCA DES keys, specify the base derivation key as a KEYGENKY key type with the UKPT bit (CV bit 18) set to B'1'.
    • For TR-31 DES keys, the base derivation key must have the following attributes:
      • TR-31 key usage: B0
      • Algorithm: T
      • TR-31 mode of key use: X
  • When you use the AES DUKPT process for the input PIN-block:
    • For CCA AES keys, the base derivation key must have the following attributes:
      • TR-31 key usage: B0
      • Algorithm: A
      • TR-31 mode of key use: X

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

reference_PIN_encrypting_key_identifier_length
Direction: Input
Type: Integer

Specifies the length in bytes of the reference_PIN_encrypting_key_identifier parameter. If the reference_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.

reference_PIN_encrypting_key_identifier
Direction: Input
Type: String

This is either the identifier of the key to unwrap the reference PIN block or the identifier of the key-generating key used to derive the key to unwrap the reference PIN block. The key identifier is an operational token or the key label of an operational token in key storage.

The key identifier must identify an AES key when the reference PIN profile specifies a PIN-block format of ISO-4. Otherwise, it must identify a DES key.

For CCA DES keys, the control vector in the key token must specify the IPINENC key-type with EPINVER bit (CV bit 19) set to B'1'.

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

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

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 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 function usage EPINVER must be enabled.

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

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

When you use any of the DUKPT rule array keywords for this verb, you must distinguish between the DES DUKPT process and the AES DUKPT process for the reference PIN encrypting key:

  • If you use the DES DUKPT process for the input PIN-block, the following applies:
    • For CCA DES keys, specify the base derivation key as a KEYGENKY key type with the UKPT bit (CV bit 18) set to B'1'.
    • For TR-31 DES keys, the base derivation key 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, the following applies:
    • For CCA AES keys, the base derivation key is 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.
    • For TR-31 AES keys, the base derivation key must have the following attributes:
      • TR-31 key usage: B0
      • Algorithm: A
      • TR-31 mode of key use: X

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

input_PIN_profile_length
Direction: Input
Type: Integer
The length of the input_PIN_profile parameter in bytes.
Table 3. Supported Encrypted PIN Verify2 input 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 three 8-byte character elements that contain information necessary to extract the PIN from a formatted PIN block. See The PIN profile for additional information.

When the DUKPT keywords are specified for the input PIN encrypting key, additional bytes must be present containing the CKSN or derivation data extension. The DES DUKPT algorithm will be used to derive the DUKPT key used to decrypt the input PIN block when the CKSN extension is included in the input_PIN_profile. 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 either X'0000' (2-key TDES) or X'0001' (3-key TDES). The key usage indicator must be set to X'1000' (PIN Encryption).
input_PIN_block_length
Direction: Input
Type: Integer

The length of the input_PIN_block in bytes. The value must be 16 for ISO-4 PIN blocks and 8 for all other PIN blocks.

input_PIN_block
Direction: Input
Type: String

The encrypted PIN block containing the PIN to compare against the reference PIN.

reference_PIN_profile_length
Direction: Input
Type: Integer
The length of the reference_PIN_profile parameter in bytes.
Table 4. Supported Encrypted PIN Verify2 reference 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
reference_PIN_profile
Direction: Input
Type: String

The three 8-byte character elements that contain information necessary to extract the reference PIN from a formatted PIN block. See The PIN profile for additional information.

When the DUKPT keywords are specified for the reference PIN encrypting key, additional bytes must be present containing the CKSN or derivation data extension. The DES DUKPT algorithm is used to derive the DUKPT key used to decrypt the input PIN block when the CKSN extension is included in the reference_PIN_profile. The AES DUKPT algorithm is used to derive the DUKPT key used to decrypt the input PIN block when the derivation data extension is included in the reference_PIN_profile. See Table 1 for the layout of the AES-DUKPT derivation data extension. The algorithm indicator must be set to either X'0000' (2-key TDES) or X'0001' (3-key TDES). The key usage indicator must be set to X'1000' (PIN Encryption).
reference_PIN_block_length
Direction: Input
Type: Integer

The length of the reference_PIN_block in bytes. The value must be 16 for ISO-4 PIN blocks and 8 for all other PIN blocks.

reference_PIN_block
Direction: Input
Type: String

The encrypted PIN block containing the reference PIN.

input_PAN_data
Direction: Input
Type: String

The PAN data for the input_PIN_block. The PAN data is used if the input PIN profile specifies the ISO-0, ISO-3, ISO-4, or VISA-4 keyword for the PIN block format. The input_PAN_data parameter is 21 bytes long.

When using the ISO-0, ISO-3, VISA-4, or ISO-4 keyword, the length of the PAN data and the PAN data are contained in the structure below padded to 21 bytes with characters that are ignored.

Offset Length Description
0 2 Length of the PAN data field, p.
2 p 10 – 19 bytes of PAN data.
2+p 0-9 Padding.
When using the ISO-0, IS0-3, or VISA-4 keyword, the PAN (p in the table) is 12 bytes long. Use the 12 rightmost digits of the PAN data, excluding the check digit. For example, an ISO-3 PAN of 999988887777 (0x393939393838383837373737) should be sent in as: 
0x000C393939393838383837373737PPPPPPP
where each P is a padding byte, such as 0x30. The final input string would be: 
0x000C39393939383838383737373730303030303030
When using the ISO-4 keyword, the PAN data is 10 –19 bytes long. For example, a 10 byte ISO-4 PAN of 1111122222 would be sent in as: 
0x000A31313131313232323232PPPPPPPPP
where P is a padding byte, such as 0x00. The final input string with 0x00 as padding would be: 
0x000A31313131313232323232000000000000000000
Note: If the reference_PAN_data and the input_PAN_data are different lengths, the rightmost 12 digits must be the same excluding the check digit. For reference, see Table 1.
reference_PAN_data
Direction: Input
Type: String

The PAN data for the reference_PIN_block. The PAN data is used if the reference PIN profile specifies the ISO-0, ISO-3, ISO-4, or VISA-4 keyword for the PIN block format. The reference_PAN_data parameter is 21 bytes long.

When using the ISO-0, ISO-3, VISA-4, or ISO-4 keyword, the length of the PAN data and the PAN data are contained in the structure below padded to 21 bytes with characters that are ignored.

Offset Length Description
0 2 Length of the PAN data field, p.
2 p 10 – 19 bytes of PAN data.
2+p 0-9 Padding.
When using the ISO-0, IS0-3, or VISA-4 keyword, the PAN (p in the table) is 12 bytes long. Use the 12 rightmost digits of the PAN data, excluding the check digit. For example, an ISO-3 PAN of 999988887777 (0x393939393838383837373737) should be sent in as 
0x000C393939393838383837373737PPPPPPP
where P is a padding byte.
When using the ISO-4 keyword, the PAN data is 10 –19 bytes long. For example, a 10 byte ISO-4 PAN of 1111122222 would be sent in as 
0x000A31313131313232323232PPPPPPPPP
where P is a padding byte, such as 0x00. The final input string with 0x00 as padding would be:
0x000A31313131313232323232000000000000000000
Note: If the reference_PAN_data and the input_PAN_data are different lengths, the rightmost 12 digits must be the same excluding the check digit.
reserved1_length
Direction: Input/Output
Type: Integer

Length in bytes of the reserved1 parameter. The value must be 0.

reserved1
Direction: Input/Output
Type: String

This parameter is ignored.

reserved2_length
Direction: Input/Output
Type: Integer

Length in bytes of the reserved2 parameter. The value must be 0.

reserved2
Direction: Input/Output
Type: String

This parameter is ignored.

reserved3_length
Direction: Input/Output
Type: Integer

Length in bytes of the reserved3 parameter. The value must be 0.

reserved3
Direction: Input/Output
Type: String

This parameter is ignored.

reserved4_length
Direction: Input/Output
Type: Integer

Length in bytes of the reserved4 parameter. The value must be 0.

reserved4
Direction: Input/Output
Type: String

This parameter is ignored.