Parameters

Edit online

The parameters for CSNBEPG.

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

PIN_generating_key_identifier
Direction: Input/Output
Type: String

A pointer to a string that contains an operational CCA or TR-31 DES key token, or the label of such a token in key storage containing a PIN-generating key.

For a CCA key, the internal key token must have a control vector that specifies the PINGEN key type and have the EPINGEN usage bit set to B'1'.

For a TR-31 key, the token must have the following attributes based on the used Processing rule:

IBM-PIN:

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

GPB-PIN or INBK-PIN:

  • TR-31 key usage: V0
  • Algorithm: T
  • TR-31 mode of key use: C or G
outbound_PIN_encrypting_key_identifier
Direction: Input
Type: String

The identifier of the key to encrypt the PIN block. The key identifier is an operational CCA or TR-31 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 OPINENC key type with EPINGEN usage bit set to 1.

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), 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 EPINGEN must be enabled.

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: E

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: E
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.
rule_array
Direction: Input
Type: String array
Keywords that provide control information to the verb. Each keyword is left-aligned in an 8-byte field and padded on the right with blanks. All keywords must be in contiguous storage. The rule_array keywords are described in Table 1.
Table 1. Keywords for Encrypted PIN Generate control information

Keywords for Encrypted PIN Generate control information
Keyword Description
Processing rule (One, required)
GBP-PIN This keyword specifies the IBM® German Bank Pool Institution PIN calculation method is to be used to generate a PIN.
IBM-PIN This keyword specifies the IBM 3624 PIN calculation method is to be used to generate a PIN.
INBK-PIN This keyword specifies the Interbank PIN calculation method is to be used to generate a PIN.

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

PIN_length
Direction: Input
Type: String
An integer defining the PIN length for those PIN calculation methods with variable length PINs. Otherwise, the variable should be set to zero.
data_array
Direction: Input
Type: Integer
Three 16-byte character strings, which are equivalent to a single 48-byte string. The values in the data array depend on the keyword for the PIN calculation method. Each element is not always used, but you must always declare a complete data array. The numeric characters in each 16-byte string must be from 1 - 16 bytes in length, uppercase, left-aligned, and padded on the right with space characters. Table 2 describes the array elements.
Table 2. Array elements for Encrypted PIN Generate data_array parameter

Array elements for Encrypted PIN Generate data_array parameter
Array element Description
Decimalization_table Decimalization table for IBM and GBP only. Sixteen characters that are used to map the hexadecimal digits (X'0' - X'F') of the encrypted validation data to decimal digits (X'0' - X'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.
Trans_sec_parm For Interbank only, sixteen digits. Eleven rightmost digits of the personal account number (PAN). A constant of 6. One digit key selector index. Three digits of PIN validation data.
Validation_data Validation data for IBM and IBM German Bank Pool padded to 16 bytes. 1 - 16 characters of hexadecimal account data left-aligned and padded on the right with blanks.
Table 3 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 3. Keywords for Encrypted PIN Generate control information

Keywords for Encrypted PIN Generate control information
Process rule IBM-PIN GBP-PIN INBK-PIN
Decimalization_table 1 1
Validation_data 2 2
Trans_sec_parm 1
PIN_profile
Direction: Input
Type: String array
A 24-byte string containing the PIN profile including the PIN block format. 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 4.
Table 4. CSNBEPG PAN data structure

CSNBEPG 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.
sequence_number
Direction: Input
Type: Integer
The 4-byte string that contains the sequence number used by certain PIN block formats. The verb uses this parameter if the PIN profile specifies the 3621 or 4704-EPP keyword for the PIN block format. Otherwise, ensure this parameter is a 4-byte variable in application data storage. The information in the variable will be ignored, but the variable must be declared. To enter a sequence number, do the following:
  • Enter 99999 to use a random sequence number that the service generates.
  • For the 3621 PIN block format, enter a value in the range from 0 - 65,535.
  • For the 4704-EPP PIN block format, enter a value in the range from 0 - 255.
encrypted_PIN_block
Direction: Output
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.