Parameters

Edit online

The parameters for CSNBSPN.

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 elements in the rule_array variable. This value must be 0, 1, or 2.
rule_array
Keywords that provide control information to the verb. The processing method is the algorithm used to create the generated key. The keywords are left-aligned and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for Secure Messaging for PINs control information
Keyword Description
Enciphering mode (One, optional)
AES-CBC Use CBC mode to encipher the message. The secmsg_key_identifier parameter must refer to an AES key.
AES-ECB Use ECB mode to encipher the message. The secmsg_key_identifier parameter must refer to an AES key.
TDES-CBC Use CBC mode to encipher the message. This is the default.
TDES-ECB Use ECB mode to encipher the message.
PIN encryption (One, optional)
CLEARPIN Recovered clear input PIN block (might be reformatted) is placed in the clear in the message for encryption with the secure message key. This is the default.
SELFENC Recovered clear input PIN block (might be reformatted) is self-encrypted and then placed in the message for encryption with the secure message key.
input_PIN_block
The input PIN block that is to be recovered in the clear and, perhaps, reformatted and then placed in the clear_text to be encrypted.

When the input_PIN_profile specifies ISO-4, the input_PIN_block is 16 bytes long. For all other formats, the input_PIN_block is 8 bytes long.

PIN_encrypting_key_identifier
The internal CCA or TR-31 token or key label of the internal token of the PIN encrypting key used in encrypting the input_PIN_block. The key may be a DES key (all input_PIN_profile PIN block formats except ISO-4) or an AES key (input_PIN_profile PIN block format ISO-4).

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

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 both, CCA and TR-31 DES tokens, double and triple length keys are supported.

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 decryption (DECRYPT) with PIN function usage REFORMAT, the encryption mode must be cipher block chaining (CBC), common usage control must be NOFLDFMT, and PIN block format usage must be ISO-4, and PIN function usage REFORMAT 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
input_PIN_profile
The three 8-byte character elements that contain information necessary to extract the PIN from a formatted PIN block. The valid input PIN formats are ISO-0, ISO-1, ISO-2, ISO-3, and ISO-4. See The PIN profile for additional information.
input_PAN_data

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 input_PIN_profile 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 2, padded to 21 bytes with characters that are ignored.
Table 2. PAN data structure
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.
secmsg_key_identifier
The internal CCA or TR-31 token or key label of an internal token of a secure message key for encrypting PINs. This key is used to encrypt the updated content of the clear_text parameter.

The key may be a DES key or an AES key.

For CCA DES keys, the control vector in the fixed-length token must specify an SECMSG type key with the SMPIN control vector 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: E

For CCA AES keys, the variable-length symmetric key token must have a token algorithm of AES and a key type of SECMSG. In addition, secure message encryption enablement must be SMPIN and verb restriction control must be ANY-USE.

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
output_PIN_profile
The three 8-byte character elements that contain information necessary to create a formatted PIN block. If reformatting is not required, the input_PIN_profile and the output_PIN_profile must specify the same PIN block format. Output PIN block formats supported are ISO-0, ISO-1, ISO-2, and ISO-3.
output_PAN_data
The 12 digit personal account number (PAN) if the output PIN format is ISO-0 or ISO-3. Otherwise, this parameter is ignored.

For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit.

text_length
The length of the clear_text parameter that follows. Length must be a multiple of eight. Maximum length is 4096.
clear_text
Cleartext that contains the recovered and/or reformatted/encrypted PIN at offset specified and then encrypted. Any padding or formatting of the message must be done by the caller on input.
initialization_vector

The supplied string for the TDES-CBC or AES-CBC mode of encryption. For TDES-CBC mode, the initialization_vector must be 8 bytes. For AES-CBC mode, the initialization_vector must be 16 bytes.

The initialization_vector is XORed with the first block of clear_text prior to encryption. This field is ignored for TDES-ECB and AES-ECB mode.

PIN_offset
The offset within the clear_text parameter where the reformatted PIN block is to be placed. The first byte of the clear_text field is offset 0.
PIN_offset_field_length
The length of the field within clear_text parameter at PIN_offset where the recovered clear input_PIN_block value is to be placed. The PIN block might be self-encrypted if requested by the rule_array. Length must be eight. The PIN block must fit entirely within the clear_text.
enciphered_text
The field where the ciphertext is returned. The length of this field must be at least as long as the clear_text field.
output_chaining_vector
This field contains the last 8 or 16 bytes of ciphertext and is used as the initialization_vector for the next encryption call if data needs to be chained. For TDES-CBC mode, 8 bytes are returned. For AES-CBC mode, 16 bytes are returned. No data is returned for TDES-ECB or AES-ECB.