Parameters

The parameters for CSNBHMG.

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

The number of keywords you supplied in the rule_array parameter. This value must be 2 or 3.

rule_array


Direction:	Input
Type:	String array

Keywords that provide control information to the verb. The following table lists the keywords. Each keyword is left-aligned in 8-byte fields 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 HMAC Generate control information
Keywords for HMAC Generate control information
Keyword	Description
*Token algorithm* (One required)
HMAC	Specifies the HMAC algorithm to be used to generate the MAC.
*Hash method* (One required).
SHA-1	Specifies the FIPS-198 HMAC procedure using the SHA-1 hash method, a symmetric key and text to produce a 20-byte (160-bit) MAC.
SHA-224	Specifies the FIPS-198 HMAC procedure using the SHA-224 hash method, a symmetric key and text to produce a 28-byte (224-bit) MAC.
SHA-256	Specifies the FIPS-198 HMAC procedure using the SHA-256 hash method, a symmetric key and text to produce a 32-byte (256-bit) MAC.
SHA-384	Specifies the FIPS-198 HMAC procedure using the SHA-384 hash method, a symmetric key and text to produce a 48-byte (384-bit) MAC.
SHA-512	Specifies the FIPS-198 HMAC procedure using the SHA-512 hash method, a symmetric key and text to produce a 64-byte (512-bit) MAC.
*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

The length of the key_identifier parameter. The maximum value is 9992.

key_identifier


Direction:	Input
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. The key algorithm of this key must be HMAC, the key type must be MAC, and the key usage fields must indicate GENERATE and match the hash method specified in the rule array.

When using a TR-31 token, it must have the following attributes:

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

Furthermore, for TR-31 tokens, the HM optional block must contain the same hash identifier as the hash method rule.

Table 2. Hash methods and HMAC key sizes
Hash methods and HMAC key sizes
Specified hash method	Minimum HMAC key size (in bits)
SHA-1	80
SHA-224	112
SHA-256	128
SHA-384	192
SHA-512	256

text_length


Direction:	Input
Type:	Integer

The length of the text you supply in the text parameter. The maximum length of text is 214783647 bytes. For FIRST and MIDDLE calls, the text_length must be a multiple of 64 for SHA-1, SHA-224 and SHA-256 hash methods, and a multiple of 128 for SHA-384 and SHA-512 hash methods.

text


Direction:	Input
Type:	String

The application-supplied text for which the MAC is generated.

chaining_vector_length


Direction:	Input/Output
Type:	Integer

The length of the chaining_vector in bytes. This value must be 128.

chaining_vector


Direction:	Input/Output
Type:	String

An 128-byte string used 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_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. The minimum value is 4, and the maximum value is 64.

mac


Direction:	Output
Type:	String

The field in which the verb returns the MAC value if the segmenting rule is ONLY or LAST.