Parameters

Edit online

The parameters for CSNBPVR.

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 key label or internal key token of a PIN-encrypting key or key-generating key.

If none of the DUKPT keywords is used, the key token must contain the input PIN-block encrypting key to be used to decrypt the input PIN-block. The key may be a TR-31 or CCA DES key (all PIN block formats except ISO-4) or a TR-31 or CCA AES key (PIN block format ISO-4).

  • 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 be a IPINENC key-type. Therefore, it 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 be a PINPROT key type. Therefore, it must have the following attributes:
    • TR-31 key usage: P0
    • Algorithm: A
    • TR-31 mode of key use: D

If one of the DUKPT keywords is used:

  • 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, specify the base derivation key as a 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 specified with the ADUKPTIP keyword for the input PIN-block, the following applies:
    • For CCA AES keys, 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.
    • For TR-31 AES keys, specify the base derivation key as a DKYGENKY key. Therefore, it must have the following attributes:
      • TR-31 key usage: B0
      • Algorithm: A
      • TR-31 mode of key use: X
PIN_verifying_key_identifier
Direction: Input/Output
Type: String

The internal CCA or TR-31 key token that identifies the PIN verify key, or the 64-byte key label of such a token in key storage.

For a CCA token, it must be a DES PINVER or PINGEN key with the EPINVER bit valued to B'1' in the control vector.

For a TR-31 token, it must be a DES key with the following attributes for each Algorithm value rule:

GBP-PIN and INBK-PIN:

  • TR-31 key usage: V0
  • Algorithm: T
  • TR-31 mode of key use: C or V

IBM-PIN and IBM-PINO:

  • TR-31 key usage: V1
  • Algorithm: T
  • TR-31 mode of key use: C or V

VISA-PVV and VISAPVV4:

  • TR-31 key usage: V2
  • Algorithm: T
  • TR-31 mode of key use: C or V
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. 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 specify DUKPT-IP or UKPTIPIN 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 Verify verb.

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

If you specify ADUKPTIP in the rule_array parameter, the input_PIN_profile parameter is extended to a 44-byte field and must contain the AES-DUKPT Derivation Data extension. The Derivation Data is 20-byte structure which specifies AES DUKPT input parameters. See The PIN profile for additional information.

PAN_data
Direction: Input
Type: String

A primary account number (PAN) in character format. The service uses this parameter if the PIN profile specifies the ISO-0, ISO-3, ISO-4, or VISA-4 keyword for the PIN block format. Otherwise, ensure that this parameter is a 12-byte value in application storage. The information in this parameter is ignored, but the parameter must be specified.

When using the ISO-0, ISO-3, or VISA-4 keyword, the value is 12 bytes long. Use the 12 rightmost digits of the PAN data, excluding the check digit.

When using the ISO-4 keyword, the value is 21 bytes long. The PAN data is 10 – 19 bytes long. The length of the PAN data and the PAN data are contained in the structure shown in Table 1.
Table 1. CSNBPVR PAN data structure

CSNBPVR PAN data structure showing offset, length and a description
Offset Length Description
0 2 Length of the PAN data field, p.
2 p 10 to 19 bytes of PAN data.
2+p 0-9 Padding to 21 bytes with characters that are ignored.
encrypted_PIN_block
Direction: Input
Type: String

The enciphered PIN block that contains the PIN to be verified. When the PIN block format is ISO-4, the PIN block is 16 bytes long. For all other formats, the PIN block is 8 bytes long.

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 PIN verify algorithm, described in Table 2.
Table 2. Keywords for Encrypted PIN Verify control information

Keywords for Encrypted PIN Verify control information
Keyword Description
Algorithm value (One, required)
GBP-PIN The IBM® German Bank Pool PIN. It verifies the PIN entered by the customer and compares that PIN with the institution generated PIN by using an institution key.
IBM-PIN The IBM 3624 PIN, which is an institution-assigned PIN. It does not calculate the PIN offset.
IBM-PINO The IBM 3624 PIN offset, which is a customer-selected PIN and calculates the PIN offset.
INBK-PIN The Interbank PIN verify algorithm.
VISA-PVV The VISA PIN verify value.
VISAPVV4 The VISA PIN verify value. If the length is 4 digits, normal processing for VISA-PVV will occur.
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.

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

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.
DUKPT keyword - single length key derivation (optional)
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.
DUKPT keyword - double length key derivation (optional)
DUKPT-IP The input_PIN_encrypting_key_identifier is to be derived using the DUKPT algorithm. The input_PIN_encrypting_key_identifier must be a KEYGENKY key with the DUKPT usage bit enabled. The input_PIN_profile must be 48 bytes and contain the key serial number.
ADUKPTIP The input_PIN_encrypting_key_identifier is to be derived using the AES-DUKPT algorithm. It must be an AES DKYGENKY with the A-DUKPT bit set to 1 in the low-order byte of key usage field 1. The input_PIN_profile must be 44 bytes and contain the AES-DUKPT derivation data.
PIN_check_length
Direction: Input
Type: String
The PIN check length for the IBM-PIN or IBM-PINO process rules only. Otherwise, it is ignored. Specify the rightmost digits, 4 - 16, for the PIN to be verified.
data_array
Direction: Input
Type: Integer
Three 16-byte elements required by the corresponding rule_array parameter. The data array consists of three 16-byte fields whose specification depend on the process rule. If a process rule requires only one or two 16-byte fields, the rest of the data array is ignored by the verb. Table 3 describes the array elements.
Table 3. Array elements for Encrypted PIN Verify data_array parameter

Array elements for Encrypted PIN Verify data_array parameter
Array element Description
Decimalization_table Decimalization table for IBM and GBP only. Sixteen decimal digits of 0 - 9.

If the ANSI X9.8 PIN - Use stored decimalization tables only command (offset X'0356') access control point is enabled in the active role, this table must match one of the active decimalization tables in the coprocessors.
PIN_offset Offset data for IBM-PINO. One to twelve numeric characters, 0 - 9, left-aligned and padded on the right with blanks. For IBM-PINO, the PIN offset length is specified in the PIN_check_length parameter. For IBM-PIN and GBP-PIN, the field is ignored.
Trans_sec_parm For VISA, only the leftmost twelve digits of the 16-byte field are used. These consist of the rightmost eleven digits of the personal account number (PAN) and a one-digit key index. The remaining four characters are ignored.

For Interbank only, all 16 bytes are used. These consist of the rightmost eleven digits of the PAN, a constant of X'6', a one-digit key index, and three numeric digits of PIN validation data.
RPVV For VISA-PVV only, referenced PVV (four bytes) that is left-aligned. The rest of the field is ignored.
Validation_data Validation data for IBM and GBP padded to 16 bytes. 1 - 16 characters of hexadecimal account data left-aligned and padded on the right with blanks.
Table 4 lists the data array elements required by the process rule (rule_array parameter). The numbers refer to the process rule's position within the array.
Table 4. Array elements required by the process rule

Array elements required by the process rule
Process rule IBM-PIN IBM-PINO GBP-PIN VISA-PVV INBK-PIN
Decimalization_table 1 1 1
Validation_data 2 2 2
PIN_offset 3 3 3    
Trans_sec_parm       1 1
RPVV       2