Parameters

Edit online

The parameters for CSNBCPA.

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

PIN_encryption_key_identifier
Direction: Input/Output
Type: String

The identifier of the key to encrypt the PIN block. The key identifier is an operational token or the key label of an operational token in key storage. The key may be a DES key (all PIN block formats except ISO-4) or an AES key (PIN block format ISO-4).

For CCA DES keys, the control vector in the fixed-length token must specify an IPINENC or OPINENC key type.

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

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

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 may indicate that the key can be used for encryption (ENCRYPT) with PIN function usage PIN generate (EPINGEN) or decryption (DECRYPT) with PIN function usage CPINGENA. The encryption mode must be Cipher Block Chaining (CBC), common usage control must be NOFLDFMT, and PIN block format usage must be ISO-4.

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

  • TR-31 key usage: P0
  • Algorithm: A
  • TR-31 mode of key use: D or E
PIN_generation_key_identifier
Direction: Input/Output
Type: String

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

For a CCA DES token, it must have a key type of PINGEN. In addition, the control vector of the key token must have CV bit 21 = B’1’ (CPINGENA).

For a TR-31 token, it must have the following attributes based on the PIN calculation method used:

IBM-PINO:

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

VISA-PVV:

  • TR-31 key usage: V2
  • Algorithm: T
  • TR-31 mode of key use: C or G
PIN_profile
Direction: Input
Type: String
The three 8-byte character elements that contain information necessary to extract a PIN from a formatted PIN block. The pad digit is needed to extract the PIN from a 3624 or 3621 PIN block in the Clear PIN Generate Alternate verb. 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 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 to 19 bytes of PAN data.
2+p 0-9 Padding.
encrypted_PIN_block
Direction: Input
Type: String
The field that receives the 8-byte or 16-byte encrypted PIN block. 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. The service uses the key that is specified in the PIN_encryption_key_identifier parameter to encrypt the block.
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 or 2. If the default extraction method for a PIN block format is desired, specify the rule_array_count value as 1.
rule_array
Direction: Input
Type: String array
The process rule for the PIN generation algorithm. Specify IBM-PINO or VISA-PVV (the VISA PIN verification value) in an 8-byte field, left-aligned, and padded with blanks. The rule_array points to an array of one or two 8-byte elements. The rule_array keywords are described in Table 1.
Table 1. Keywords for Clear PIN Generate Alternate control information

Keywords for Clear PIN Generate Alternate control information
Keyword Description
PIN calculation method (One required)
IBM-PINO This keyword specifies use of the IBM® 3624 PIN Offset calculation method.
VISA-PVV This keyword specifies use of the VISA PVV calculation method.
PIN extraction method (One optional) See the text following this table.
If the PIN extraction method is provided, one of the PIN extraction method keywords shown in Table 2 can be specified for the given PIN block format. 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.
The PIN extraction methods operate as follows:
PINBLOCK
Specifies that the verb use one of the following:
  • 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.
PADDIGIT
Specifies that the verb use the pad value in the PIN profile to identify the end of the PIN.
HEXDIGIT
Specifies that the verb 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.
PINLENnn
Specifies that the verb use the length specified in the keyword, where nn can range from 04 - 16, to identify the PIN.

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 command (bit X'0313') must be enabled using a TKE.

PADEXIST
Specifies that the verb use the character in the 16th position of the PIN block as the value of the pad value.
PIN_check_length
Direction: Input
Type: Integer
The length of the PIN offset used only for the IBM-PINO process rule. Otherwise, this parameter is ignored. Specify an integer from 4 - 16.
Note: The PIN check length must be less than or equal to the integer specified in the PIN_length parameter.
data_array
Direction: Input
Type: String
Three 16-byte elements. Table 2 describes the format when IBM-PINO is specified. Table 3 describes the format when VISA-PVV is specified.
Table 2. Array elements for Clear PIN Generate Alternate, data_array (IBM-PINO)

Array elements for Clear PIN Generate Alternate, data_array (IBM-PINO)
Array element Description
Decimalization_table This element contains the decimalization table of 16 characters (0 - 9) that are used to convert hexadecimal digits (X'0' - X'F') of the enciphered validation data to the decimal digits (X'0' - X'9').

If the ANSI X9.8 PIN - Use stored decimalization table only access control point (X'0356') is enabled in the active role, this table must match one of the active decimalization tables in the coprocessors.
validation_data This element contains 1 - 16 characters of account data. The data must be left-aligned and padded on the right with space characters.
Reserved-3 This field is ignored, but you must specify it.
Table 3. Array elements for Clear PIN Generate Alternate, data_array (VISA-PVV)

Array elements for Clear PIN Generate Alternate, data_array (VISA-PVV)
Array element Description
Trans_sec_parm For VISA-PVV only, the leftmost twelve digits. Eleven digits of the personal account number (PAN). One digit key index. The rest of the field is ignored.
Reserved-2 This field is ignored, but you must specify it.
Reserved-3 This field is ignored, but you must specify it.
returned_PVV
Direction: Output
Type: String
A 16-byte area that contains the result left-aligned and padded with blanks. When VISA-PVV is specified, this is a 4 byte value. When IBM-PINO is specified, the value is the same length as the clear PIN.