Parameters

Edit online

The parameter definitions for CSNBMMS.

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
A pointer to an integer variable containing the number of keywords you are supplying in the rule_array variable. This value must be in the range 2 - 4.
rule_array
A pointer to a string variable containing an array of keywords that provide control information to the verb. The keyword must be in eight bytes of contiguous storage, left-aligned and padded on the right with blanks. The rule_array keywords for CSNBMMS are described in Table 1.
Table 1. Keywords for Multi-MAC Scheme control information
Keyword Description
Diversification process (one, required).
KDFFM-DK Specifies to use the DK version of the key derivation function in feedback mode. This method uses AES CMAC to encipher the derivation data with the k-bit diversified key generating key, where k = 128, 192, or 256.
Bit length of generated key (one, optional). Valid only with the KDFFM-DK keyword. Default is to use the bit length of the generating key as the bit length of the generated key.
KLEN128 Specifies the bit length of the generated key to be 128.
KLEN192 Specifies the bit length of the generated key to be 192. Only allowed if the bit length of the generating key is greater than or equal to 192.
KLEN256 Specifies the bit length of the generated key to be 256. Only allowed if the bit length of the generating key is 256.
IV usage (one, optional). Valid only with the KDFFM-DK keyword.
DEFLT-IV Specify this keyword to use the DK input_initial_vector '52 52 52 52 52 52 52 52 25 25 25 25 25 25 25 25' as the input IV in the derivation function. This is the default.
USE-IV Specify this keyword to use the contents of the input_initial_vector parameter as the input IV in the derivation function.
MAC algorithm (one, required).
CMAC Specifies the use of the CMAC algorithm when verifying the values in the MAC_values parameter.
generating_key_identifier_length

Specifies the length in bytes of the generating_key_identifier parameter. If the generating_key_identifier contains a label, the value must be 64. Otherwise, the value must be between the actual length of the token and 725.

generating_key_identifier

The identifier of the key-generating key known as K-base-2 in the M of N MAC Scheme. 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 AES and the key type must be DKYGENKY:D-MAC with MMSAUTH2.

derivation_data0_length

Specifies the length in bytes of the derivation_data0 parameter. When the process rule KDFFM-DK is specified, the value must be in the range 4 - 2048.

derivation_data0

The derivation data to be used in the first level of the key derivation process. This data encodes the parameters of the M of N MAC Scheme according to the format provided in the derivation_data0 parameter.

The format of the derivation_data0 parameter is fixed for the length and position of the M of N MAC Scheme parameters. For more information, see Table 2. The fixed format protects the scheme security and allows the CSNBMMS service to pull the important fields out of the derivation_data0 parameter. For examples of derivation_data0 input, see Table 1.
Table 2. Format of parameter derivation_data0
Offset (bytes) Length (bytes) Description
0 x Optional service specific data ds. This field is application or service specific and must be the same when used with CSNBDKG2 andCSNBMMS. This field is not required. The maximum length is 2044 bytes (2048 - 4).
x 1 L, required field: The length of a single MAC value. The MAC_values parameter contains an array of MAC values, each of length L. The maximum value for this field is 16 (X'10').
x+1 1 N, required field: The maximum number of MACs. It is expected that not more than N MAC values are contained in the MAC_values parameter. The maximum value for this field is 32 (X'20'), and minimum is 1.
x+2 1 M, required field: The minimum number of MACs that must successfully verify. It is expected that at least M MAC values are contained in the MAC_values parameter. The maximum value of the M parameter is the value for the N parameter, and minimum is 1.
x+3 1 c, required field: The derivation key counter. The value for this field in the derivation_data0 parameter is ignored. CSNBMMS derives the MAC keys using the correct counter values in this location. test
derivation_data1_length

Specifies the length in bytes of the derivation_data parameter. When the process rule KDFFM-DK is specified and K-base-2 is level DKYL1 or DKYL2, the value must be between 1 to 2048. Otherwise, the value must be 0.

derivation_data1

The derivation data to be used in the key generation process at the DKYL0 derivation level when K-base-2 is level DKYL1 or DKYL2. When derivation_data1_length is 0, this parameter is ignored.

derivation_data2_length

Specifies the length in bytes of the derivation_data2 parameter. When the process rule KDFFM-DK is specified and K-base-2 is level DKYL2, the value must be between 1 to 2048. Otherwise, the value must be 0.

derivation_data2

The derivation data to be used in the key generation process at the DKYL1 derivation level when K-base-2 is level DKYL2. When derivation_data2_length is 0, this parameter is ignored.

MAC_values_length

The length of the text you supplied in the MAC_values parameter. The maximum length is 512 bytes (maximum L value * maximum N value). If there is a warning or error code returned that one or more MAC values failed verification, this field is updated with the length of the returned MACs that failed.

MAC_values

The application-supplied MAC values expected to be each of length L. It is expected that the count of MAC values is greater than or equal to M and less than or equal to N. These are the MAC values generated by the cooperating nodes and that are used in CSNBMMS for verification. At least M values from MAC_values must successfully verify. If there is a warning or error code returned that one or more MAC values failed verification, this field is updated with the returned MACs that failed.

text_length

The length of the text that you supplied in the text parameter. The maximum length is 4096 bytes. The length must be a multiple of 16 and larger than 0.

text

The application-supplied text for which the MAC_values were generated and are used for verification.

input_initial_vector_length

A pointer to an integer variable containing the number of bytes of data in the input_initial_vector variable. This value must be in the range 0 - 16.

input_initial_vector

A pointer to a string variable containing a 16-byte input initial vector to be used for the KDMFFM-DK diversification process instead of the default initial vector. Valid only with the KDFFM-DK keyword. If the input_initial_vector length is 0, the value '52 52 52 52 52 52 52 52 25 25 25 25 25 25 25 25' is used if no IV usage rule array keyword is specified or if the DFLT-IV rule array keyword is specified. If the input_initial_vector length is 0 and the USE-IV rule array keyword is specified, the empty set is used for the input_initial_vector.

final_MAC_length

The length of the text returned in the final_MAC parameter. The maximum length is 16 bytes (maximum L value). Actual length is the L length provided in the derivation data, or 0 on error.

final_MAC

The final MAC calculated by the service is returned in this parameter.

reserved1_length

Length of the reserved1 parameter. This value must be 0.

reserved1

This parameter is ignored.

reserved2_length

Length of the reserved2 parameter. This value must be 0.

reserved2

This parameter is ignored.

reserved3_length

Length of the reserved3 parameter. This value must be 0.

reserved3

This parameter is ignored.