Parameters

Edit online

The parameters for CSNBMGN2.

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
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
The rule_array contains keywords that provide control information to the callable service. The keywords must be in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for MAC Generate2 control information

Keywords for MAC Generate2 control information
Keyword Description
Token algorithm (One, required)
AES Specifies the use of the AES CMAC algorithm to generate a MAC.
HMAC Specifies the use of the HMAC algorithm to generate a MAC.
Hash method (One, required for HMAC only)
SHA-1 Specifies the use of the SHA-1 hash method.
SHA-224 Specifies the use of the SHA-224 hash method.
SHA-256 Specifies the use of the SHA-256 hash method.
SHA-384 Specifies the use of the SHA-384 hash method.
SHA-512 Specifies the use of the SHA-512 hash method.
Segmenting Control (One, optional)
ONLY Only call. Segmenting is not employed by the application program. This is the default value.
FIRST First call. This is the first segment of data from the application program.
MIDDLE Middle call. This is an intermediate data segment.
LAST Last call. This is the last data segment.
key_identifier_length
Direction: Input/Output
Type: String
The length in bytes of the key_identifier parameter. If the key_identifier parameter contains a label, the value must be 64. Otherwise, the value must be at least the actual token length, up to 9992.
key_identifier
Direction: Input/Output
Type: String
The identifier of the key to generate the MAC. The key identifier is an operational token or the key label of an operational token in key storage.

When using a CCA token together with the AES algorithm, the key type must be MAC, and the key usage fields must indicate GENONLY or GENERATE and must indicate CMAC.

When using a CCA token together with the HMAC algorithm, the key identifier may be a clear or secure operational key token. The key usage fields must indicate GENONLY or GENERATE and the hash method must be selected.

When using a TR-31 token together with the AES algorithm, the token must have the following attributes:

  • TR-31 key usage: M6
  • Algorithm: A
  • TR-31 mode of key use: C or G

When using a TR-31 token together with the HMAC algorithm, the token must have the following attributes:

  • TR-31 key usage: M7
  • Algorithm: H
  • TR-31 mode of key use: C or G

If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.

message_text_length
Direction: Input
Type: Integer
The length of the text you supply in the message_text parameter. The maximum length of text is 214783647 bytes. For FIRST and MIDDLE calls, the message_text_length must be:
  • a multiple of 64 for the SHA-1, SHA-224, and SHA-256 hash methods
  • a multiple of 128 for the SHA-384 and SHA-512 hash methods
  • a multiple of 16 for the AES CMAC method.
message_text
Direction: Input
Type: String
The application-supplied text for which the MAC is generated.
chaining_vector_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable specifying the length in bytes of the chaining_vector parameter. The value must be 128.
chaining_vector
Direction: Input/Output
Type: String
A pointer to a string variable containing a work area that the security server uses to carry segmented data between procedure calls. When the segmenting control is FIRST or ONLY, this value is ignored, but must be declared.
mac_length
Direction: Input/Output
Type: Integer
The length of the mac parameter in bytes. This parameter is updated to the actual length of the MAC parameter on output. For HMAC, the minimum value is 4 and the maximum value is 64. For AES, the value must be 16.
mac
Direction: Output
Type: String
The field in which the callable service returns the MAC value if the segmenting rule is ONLY or LAST.