Parameters

Edit online

The parameters for CSNBMGN.

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

key_identifier
Direction: Input/Output
Type: String
The 64-byte key label or internal CCA key token that identifies a variable-length operational MAC generate key or a single-length DATA or DATAM key. Or an internal TR-31 MAC token. The specific type and attributes of the key depend on the MAC process rule in the rule_array parameter.

For CCA key tokens, the identifier is a 64-byte DES key token containing a MAC, DATAM, or DATA key.

For X9.143/TR-31 key blocks, the identifier is a variable-length key block of a DES or TDES MAC key with mode of use C or G, and key usage M0, M1, M3, M6, dependent upon the MAC process rule specified (see Table 1).
text_length
Direction: Input
Type: Integer
The length of the text you supply in the text parameter. If the text_length is not a multiple of eight bytes and if the ONLY or LAST keyword of the rule_array parameter is called, the text is padded in accordance with the processing rule specified.
text
Direction: Input
Type: String
The application-supplied text for which the MAC is generated.
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 0, 1, 2, or 3.
rule_array
Direction: Input
Type: String array
Zero to three keywords that provide control information to the verb. The keywords are described in Table 1. The keywords must be in 24 bytes of contiguous storage with each of the keywords left-aligned in its own 8-byte location and padded on the right with blanks. For example, 
'X9.9-1  MIDDLE  MACLEN4 '
The order of the rule_array keywords is not fixed.
You can specify one of the MAC processing rules and then choose one of the segmenting control keywords and one of the MAC length keywords. The rule_array keywords are described in Table 1.
Table 1. Keywords for MAC Generate control information

Keywords for MAC Generate control information
Keyword Description
MAC process rules (One, optional)
EMVMAC EMV padding rule with a single-length MAC key. For CCA keys, the key_identifier parameter must identify a single-length MAC or a single-length DATA key.

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

  • TR-31 key usage: M1
  • Algorithm: D
  • TR-31 mode of key use: C or G

The text is always padded with 1 - 8 bytes so the resulting text length is a multiple of eight bytes. The first pad character is X'80'. The remaining pad characters are X'00'.

EMVMACD EMV padding rule with a double-length or triple-length MAC key. For CCA keys, the key_identifier parameter must identify a double-length or triple-length MAC key.

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

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

The padding rules are the same as for keyword EMVMAC.
X9.19OPT ANSI X9.19 optional double or triple key MAC procedure. For CCA keys, the key_identifier parameter must identify a double-length or triple-length MAC key.

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

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

The padding rules are the same as for keyword X9.9-1.
X9.9-1 ANSI X9.9-1 and X9.19 basic procedure. For CCA keys, the key_identifier parameter must identify a single-length MAC or a single-length DATA key.

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

  • TR-31 key usage: M1
  • Algorithm: D
  • TR-31 mode of key use: C or G

X9.9-1 causes the MAC to be computed from all of the data. The text is padded only if the text length is not a multiple of eight bytes. If padding is required, the pad character X'00' is used. This is the default value.
TDESCMAC NIST SP800-38B (2005) procedure. For CCA keys, the key_identifier parameter must identify a double-length or triple-length MAC or a double-length DATA key.

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

  • TR-31 key usage: M6
  • Algorithm: T
  • TR-31 mode of key use: C or G
TDES-MAC ANSI X9.9-1 procedure using ISO 16609 CBC mode triple-DES (TDES) encryption of the data. Uses a double-length key. See Triple-DES ciphering algorithms.

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

  • TR-31 key usage: M0
  • Algorithm: T
  • TR-31 mode of key use: C or G
Segmenting control (One, optional)
FIRST First call; this is the first segment of data from the application program.
LAST Last call; this is the last data segment.
MIDDLE Middle call; this is an intermediate data segment.
ONLY Only call; segmenting is not employed by the application program. This is the default value.
MAC length and presentation (One, optional)
HEX-8 Generates a 4-byte MAC value and presents it as 8 hexadecimal characters.
HEX-9 Generates a 4-byte MAC value and presents it as two groups of 4 hexadecimal characters with a space between the groups.
MACLEN4 Generates a 4-byte MAC value. This is the default value.
MACLEN6 Generates a 6-byte MAC value.
MACLEN8 Generates an 8-byte MAC value.
chaining_vector
Direction: Input/Output
Type: String
An 18-byte string that CCA uses as a system work area. Your application program must not change the data in this string. The chaining vector permits data to be chained from one invocation call to another.

On the first call, initialize this parameter as binary zeros.

mac
Direction: Output
Type: String
The 8-byte or 9-byte field in which the verb returns the MAC value if the segmenting rule is ONLY or LAST. Allocate an 8-byte field for MAC values of four bytes, six bytes, eight bytes, or HEX-8. Allocate a 9-byte MAC field if you specify HEX-9 in the rule_array parameter.