MAC Verify2 (CSNBMVR2, CSNBMVR3, CSNEMVR2, and CSNEMVR3)

CALL CSNBMVR2(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_identifier_length,
             key_identifier,
             text_length,
             text,
             chaining_vector_length,
             chaining_vector,
             mac_length,
             mac )

CALL CSNBMVR3(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_identifier_length,
             key_identifier,
             text_length,
             text,
             chaining_vector_length,
             chaining_vector,
             mac_length,
             mac,
             text_id_in )

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return and reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. ICSF and cryptographic coprocessor return and reason codes lists the reason codes.

exit_data_length

Direction	Type
Input/Output	Integer

The length of the data that is passed to the installation exit. The data is identified in the exit_data parameter.

exit_data

Direction	Type
Input/Output	String

The data that is passed to the installation exit.

rule_array_count

Direction	Type
Input	Integer

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

rule_array

Direction	Type
Input	String

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.

Table 1. Keywords for MAC Verify2 control information

Keyword	Meaning
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	Type
Input	Integer

key_identifier_length specifies 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 between the actual length of the token and 725.

key_identifier

Direction	Type
Input/Output	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.

For the HMAC algorithm, the key algorithm must be HMAC and the key usage fields must indicate GENERATE or VERIFY and the hash method selected. For the AES algorithm, the key algorithm must be AES, the key type must be MAC, and the key usage fields must indicate GENERATE or VERIFY and must indicate CMAC.

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

text_length

Direction	Type
Input	Integer

The length of the text you supplied 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 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.

text

Direction	Type
Input	String

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

chaining_vector_length

Direction	Type
Input/Output	Integer

chaining_vector_length specifies the length in bytes of the chaining_vector parameter. The value must be 128.

chaining_vector

Direction	Type
Input/Output	String

An 128-byte string that ICSF 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_length

Direction	Type
Input	Integer

The length of the mac parameter in bytes. For HMAC, the maximum value is 64. For AES, the value must be 16.

mac

Direction	Type
Input	String

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

text_id_in

Direction	Type
Input	Integer

For CSNBMVR3 only, the ALET of the text for which the MAC is to be verified.

SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS.

This table lists the access control points in the domain role that control the function for this service.

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service.