MAC Verify (CSNBMVR or CSNBMVR1 and CSNEMVR or CSNEMVR1)

CALL CSNBMVR(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             key_identifier,
             text_length,
             text,
             rule_array_count,
             rule_array,
             chaining_vector,
             mac ) 

CALL CSNBMVR1(
              return_code,
              reason_code,
              exit_data_length,
              exit_data,
              key_identifier,
              text_length,
              text,
              rule_array_count,
              rule_array,
              chaining_vector,
              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.

key_identifier

Direction	Type
Input/Output	String

The 64-byte key label or internal key token that identifies a single, double-length, or triple-length MAC verify key, a single, double length, or triple-length MAC generation key, a DATAM or DATAMV key, a single-length DATA key, or double-length DATA keys (valid when rule is TDES-MAC). The type of key depends on the MAC process rule in the rule_array parameter.

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 supply in the text parameter. The maximum length of text is 214783647 bytes. If the text_length parameter is not a multiple of 8 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.

Note: The MAXLEN value may still be specified in the options data set, but only the maximum value limit will be enforced (2147483647).

text

Direction	Type
Input	String

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

rule_array_count

Direction	Type
Input	Integer

The number of keywords specified in the rule_array parameter. The value can be 0, 1, 2, or 3.

rule_array

Direction	Type
Input	String

Zero to three keywords that provide control information to the callable service. The keywords are shown in Table 1. The keywords must be in 24 bytes of contiguous storage with each of the keywords left-justified 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.

Table 1. Keywords for MAC Verify control information

Keyword	Meaning
MAC Process Rules (optional)
EMVMAC	EMV padding rule with a single-length MAC key. The key_identifier parameter must identify a single-length MAC, MACVER, or DATA key. The text is always padded so that the resulting text length is a multiple of 8 bytes. The first pad character is X'80'. The remaining 0 to 7 pad characters are X'00'.
EMVMACD	EMV padding rule with double key MAC. The key_identifier parameter must identify a double-length, or triple-length MAC or MACVER key. The padding rules are the same as for EMVMAC.
X9.19OPT	ANSI X9.19 optional double key MAC procedure. The key_identifier parameter must identify a double-length or triple-length MAC key. The padding rules are the same as for X9.9-1. ANSI X9.9-1 and X9.19 basic procedure.
X9.9-1	ANSI X9.9-1 and X9.19 basic procedure. The key_identifier parameter must identify a single-length MAC, or single-length DATA key. 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 8 bytes. If padding is required, the pad character X'00' is used. This is the default value.
TDES-MAC	ISO 16609 procedure. The key_identifier must identify a double-length or triple-length MAC or a double-length DATA key. The text is padded only if the text length is not a multiple of 8 bytes.
Segmenting Control (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; the application program does not employ segmenting. This is the default value.
MAC Length and Presentation (optional)
HEX-8	Verifies a 4-byte MAC value that is represented as 8 hexadecimal characters.
HEX-9	Verifies a 4-byte MAC value that is represented as 2 groups of 4 hexadecimal characters with a space character between the groups.
MACLEN4	Verifies a 4-byte MAC value. This is the default value.
MACLEN6	Verifies a 6-byte MAC value.
MACLEN8	Verifies an 8-byte MAC value.

chaining_vector

Direction	Type
Input/Output	String

An 128-byte string that ICSF uses as a system work area. The chaining vector permits data to be chained from one invocation call to another.

On calls that use ONLY or FIRST rules, initialize this parameter as binary zeros. On calls that use MIDDLE or LAST rules, your application program must not change the data in this string.

mac

Direction	Type
Input	String

The 8- or 9-byte field that contains the MAC value you want to verify. The value in the field must be left-justified and padded with zeros. If you specified the X'09' keyword in the rule_array parameter, the input MAC is 9 bytes.

text_id_in

Direction	Type
Input	Integer

For CSNBMVR1/CSNEMVR1 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 or PKDS.

To verify a MAC in one call, specify the ONLY keyword on the segmenting rule keyword for the rule_array parameter. For two or more calls, specify the FIRST keyword for the first input block, MIDDLE for intermediate blocks (if any), and LAST for the last block.

For a given text string, the MAC resulting from the verification process is the same regardless of how the text is segmented, or how it was segmented when the original MAC was generated.

The MAC Verify access control point controls the function of this service.

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

For more information about MAC processing rules and segmenting control, refer to IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface reference.

The MAC Generate callable service is described in MAC Generate (CSNBMGN or CSNBMGN1 and CSNEMGN or CSNEMGN1).