Parameters

Edit online

The parameter definitions for CSNBDDK.

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

A pointer to an integer variable containing the number of 8-byte elements in the rule_array variable. The value must be 2.

rule_array
Direction Type
Input String array

A pointer to a string variable containing an array of keywords. The keywords are eight bytes in length and must be left-aligned and padded on the right with space characters.

Table 1. Keywords for Diversify Directed Key

Keywords for Diversify Directed Key. This table contains two columns: Keyword and Meaning, and it contains rows for Diversification Process (One required) and Function (one required).
Keyword Meaning
Diversification Process (One required)
KDFFM Specifies to use the Key Derivation Function (KDF) in Feedback Mode (NIST SP 800-108) to generate keys. The key_type_vector variable is used as the IV for this process.

This method uses AES CMAC to process 16 – 40 bytes of derivation data (V, with V =additional_derivation_data || random_data) with the key diversification key (KDK) to produce a k-bit AES key, where k = 128, 192, or 256.
Function (one required)
DERIVE Specifies to derive the passive diversified key of a pair of directed keys.
GENERATE Specifies to generate the active diversified key of a pair of directed keys.
kdk_identifier_length
Direction Type
Input Integer

A pointer to an integer variable containing the number of bytes of data in the kdk_identifier variable. The maximum length is 900. A key label must be at least 64 bytes.

kdk_identifier
Direction Type
Input String

A pointer to a string variable containing the operational variable-length symmetric key-token or the key label of such a record in AES key-storage. The key must have a token algorithm of AES and a key type of KDKGENKY. This is a key diversification key (KDK). In addition, the key usage fields must indicate if the key is to be derived for entity Type A (KDKTYPEA) or Type B (KDKTYPEB).

Note: When the GENERATE function is specified and the generating key has usage of KDKTYPEA, the associated DERIVE function must have usage of KDKTYPEB. Likewise, when the GENERATE function is specified and this key has usage of KDKTYPEB, the associated DERIVE function must have usage of KDKTYPEA.
key_type_vector_length
Direction Type
Input Integer

A pointer to an integer variable containing the number of elements in the key_type_vector variable. The value must be 16.

key_type_vector
Direction Type
Input String

A pointer to a string variable that defines the rules for the key to be generated and also contains information needed to restrict the usage of the key to be generated. The format of the key type vector is defined in Key type vectors. The key_type_vector is also used as the initialization vector (IV) for the key derivation process.

additional_derivation_data_length
Direction Type
Input Integer

A pointer to an integer variable containing the number of bytes of data in the additional_derivation_data variable. The value must be between 0 and 2032 starting with CCA releases 6.7 and 7.4. Otherwise, the value must be in the range 0 - 24.

The sum of the additional_derivation_data_length and the random_data_length cannot exceed 2048.

additional_derivation_data
Direction Type
Input String

A pointer to a string variable containing optional custom diversification data used in the key generation or derivation process. The additional derivation data concatenated with the random data cannot exceed 2048 for CCA releases 6.7, 7.4, and later. Otherwise, the random data cannot exceed 40 bytes.

random_data_length
Direction Type
Input/Output Integer
A pointer to an integer variable which specifies the number of bytes of random data in the random_data variable. The value must be from 16 – 40. The length of the additional derivation data concatenated with the random data cannot exceed 2048 bytes for CCA releases 6.7, 7.4, and later. Otherwise, the random data cannot exceed 40 bytes.
  • When keyword GENERATE is specified in the rule array, this is an input and an output parameter. On input, this value specifies the number of bytes of data to use as the random data portion of the diversification data used in diversifying the first key of a key pair. On output, the returned value indicates the number of bytes of data actually returned in the random_data variable.
  • When keyword DERIVE is specified in the rule array, this is an input only parameter. Except on error, this value is set to 0. On input, this value specifies the number of bytes of data to use as the random data portion of the diversification data used in diversifying the second key of a key pair. To produce the desired results, this value must be the same length returned by a previous associated GENERATE function call.
random_data
Direction Type
Input/Output String
A pointer to a string variable containing the random data used in the diversification process. When the GENERATE function is specified, on input this variable is ignored, and on output this variable contains the random data created and used to diversify the first output key of a key pair.

When the DERIVE function is specified, on input this variable must contain the random data previously created during a previous GENERATE function and is used to diversify the second output key of a key pair. The derivation data, V, that is input to the diversification process for creating the key must be 16 – 40 bytes and is created by concatenating the additional_derivation_data with the random_data. The random data must be at least 16 bytes.

Note: For a given pair of output keys, the DERIVE function must provide the same random data and additional derivation data as the GENERATE function used.

The additional derivation data concatenated with the random data cannot exceed 2048 for CCA release 7.4, and later. Otherwise, the random data cannot exceed 40 bytes.

output_key_identifier_length
Direction Type
Input/Output Integer

A pointer to an integer variable containing the number of bytes of data in the output_key_identifier variable. On input, this is the size of the buffer. On output, the verb sets the variable to the length of the returned output_key_identifier variable. The maximum value is 900.

output_key_identifier
Direction Type
Input/Output String
A pointer to a string variable containing a variable-length symmetric key-token, or the label of such a record in AES key-storage, for the key token that is to receive the output key. On input, this parameter must identify a null variable-length symmetric key-token. The key characteristics are identified by the key_type_vector parameter. The output key token will be:
  • Internal
  • Payload format version X’01’
  • No key label in the associated data
  • No IBM extended associated data (IEAD)
  • No user-defined associated data (UAD)
  • General export control: NOEXPORT
  • The key length defined in the key type vector determines the length of the output key.

When the kdk_identifier is compliant-tagged, a compliant-tagged key token is created.