Parameters

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 1, 2, or 3.

rule_array

Direction:	Input
Type:	String array

The rule_array contains keywords that provide control information to the MAC Verify2 callable service. The keywords are described in Table 1.

Table 1. Keywords for MAC Verify2 control information

Keywords for MAC Verify2 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)
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.

key_identifier_length

Direction:	Input
Type:	Integer

Length of the key_identifier parameter in bytes. 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 verify 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 GENERATE or VERIFY 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 GENERATE or VERIFY 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 V

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 V

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 cleartext 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
Type:	Integer

Specifies 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. Important: Application programs must not alter the contents of this variable between related FIRST, MIDDLE, and LAST calls.

mac_length

Direction:	Input
Type:	Integer

Specifies the length in bytes of the mac parameter. The value must be equal to the number of MAC bytes to be verified, up to a maximum of 64.

mac

Direction:	Input
Type:	String

The field that contains the MAC value you want to verify.