Parameters

Edit online

The parameters for CSNBKTB2.

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. The minimum value is 4.
rule_array
Direction: Input
Type: String array
The rule_array contains keywords that provide control information to the verb. The keywords must be in contiguous storage with each of the keywords left-aligned in its own 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for Key Token Build2

Keywords for Key Token Build2
Keyword Description
Header section
Token identifier (one required)
EXTERNAL Specifies to build an external variable-length symmetric key-token.
INTERNAL Specifies to build an internal variable-length symmetric key-token.
Wrapping information section
Key status (one, optional)
NO-KEY Build the key token without a key value. This creates a skeleton key token that can later be supplied to the Key Generate2 (CSNBKGN2) verb. This is the default.
KEY-CLR Build the key token with a clear key, AES CIPHER and HMAC MAC keys only.
Associated data section
Type of algorithm for which the key can be used (one required)
AES Specifies to build an AES key token.
HMAC Specifies to build an HMAC key token.
CPACF export control
XPRTCPAC Allow this key token to be exported as a CPACF protected key. When CSU_HCPUAPRT is enabled, and this key token (or a label referring to this key token) is used, the key token is translated to CPACF by the CCA library and the handle is used with the CPACF.
Note: Only usable with AES keys of key type CIPHER.
NOEXCPAC Do not allow this key token to be exported as a CPACF protected key. This is the default.
Key type (one required)
CIPHER Build a CIPHER key for encryption, decryption, and translation operations. AES algorithm only.
  • Refer to Figure 1 for valid rule array keyword combinations.
  • Refer to Table 1 for token offsets, offset values, and meanings of these keywords.
  • Refer to Table 1 for the format of the key token.
DKYGENKY Build a diversifying key generating key. AES algorithm only.
EXPORTER Build an EXPORTER key-encrypting key. AES algorithm only.
IMPORTER Build an IMPORTER key-encrypting key. AES algorithm only.
MAC Build a MAC key for message authentication code operations. AES and HMAC algorithms only.
For AES:
For HMAC:
PINCALC Build a DK PIN calculating key. AES algorithm only.
PINPROT Build a DK PIN protection key. AES algorithm only.
PINPRW Build a DK PIN PRW key. AES algorithm only.
SECMSG Build a secure messaging key. AES algorithm only.
Payload format version (one, optional). Identifies format of the payload.
V0PYLD Build a key token with a version 0 payload format. This format has a variable length and the key length can be inferred from the size of the payload. This format is compatible with all releases. This is the default.
V1PYLD Build the key token with a version 1 payload format. This format has a fixed length and the key length cannot be inferred by the size of the payload. An obscured key length is considered more secure.
Compliance (Optional)
COMP-TAG Build a compliant-tagged key token. Not valid with EXTERNAL, HMAC, or V0PYLD.
NOCMPTAG Do not build a compliant-tagged key token. This is the default.
clear_key_bit_length
Direction: Input
Type: Integer
The length of the clear key in bits. Specify 0 when no key value is supplied or a valid HMAC key bit length, between 80 and 2048.
clear_key_value
Direction: Input
Type: String
This parameter is used when the KEY-CLR keyword is specified. This parameter is the clear key value to be put into the token being built.
key_name_length
Direction: Input
Type: Integer
The length of the key_name parameter. Valid values are 0 and 64.
key_name
Direction: Input
Type: String
A 64-byte key store label to be stored in the associated data structure of the token.
user_associated_data_length
Direction: Input
Type: Integer
The length of the user-associated data. The valid values are 0 - 255 bytes.
user_associated_data
Direction: Input
Type: String
User-associated data to be stored in the associated data structure.
token_data_length
Direction: Input
Type: Integer
This parameter is reserved. This value must be 0.
token_data
Direction: n/a
Type: String
This parameter is ignored.
verb_data_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the verb_data variable. The value must be 0.
verb_data
Direction: Input
Type: String
A pointer to a string variable containing key-usage field keywords that are related to the type of key to diversify.

DKYUSAGE specifies that the verb_data variable contains all of the keywords necessary to define the key usage attributes related to the type of key to diversify. Based on the verb_data keywords, CSNBKTB2 appends the key usage attributes of the type of key to diversify to the key usage fields of the DKYGENKY key. The related key usage fields control which key usage attributes are permissible for the finally generated diversified key.

DKYUSAGE is not valid with D-ALL, because the type of key to diversify is unspecified. DKYUSAGE is optional with D-CIPHER, D-EXP, and D-IMP. For these key types, if DKYUSAGE is not specified, CSNBKTB2 assigns default key usage attributes to the related KUF fields. DKYUSAGE is required for the remaining values of type of key to diversify, because those key types do not have default key usage attributes.

Table 2. Related key usage fields when Key Token Build2 builds a DKYGENKY key-token

Related key usage fields when Key Token Build2 builds a DKYGENKY key-token
Type of key to diversify DKYUSAGE usage Related key usage fields for key type DKYGENKY
D-ALL Invalid None.
D-CIPHER Optional If keyword DKYUSAGE is specified, the verb_data variable must contain key usage fields keywords related to an AES CIPHER key. If not specified, the related key usage fields are those of a default AES CIPHER key.
D-EXP Optional If keyword DKYUSAGE is specified, the verb_data variable must contain key usage fields keywords related to an AES EXPORTER key. If not specified, the related key usage fields will be that of a default AES EXPORTER key.
D-IMP Optional If keyword DKYUSAGE is specified, the verb_data variable must contain key usage fields keywords related to an AES IMPORTER key. If not specified, the related key usage fields will be that of a default AES IMPORTER key.
D-KDKGKY Required The verb_data parameter must contain key usage fields keywords related to an AES KDKGENKY key.
D-MAC Required The verb_data variable must contain key usage fields keywords related to an AES MAC key.
When building an AES DKYGENKY D-MAC token for the M of N MAC Scheme, AES MAC key usage keywords must be specified in conjunction with MMSAUTH controls in Table 3.
D-PCALC Required The verb_data variable must contain key usage fields keywords related to an AES PINCALC key.
D-PPROT Required The verb_data variable must contain key usage fields keywords related to an AES PINPROT key.
D-PPRW Required The verb_data variable must contain key usage fields keywords related to an AES PINPRW key.
D-SECMSG Required The verb_data variable must contain key usage fields keywords related to an AES SECMSG key.
target_key_token_length
Direction: Input/Output
Type: Integer
On input, the length of the target_key_token parameter supplied to receive the token. On output, the actual length of the token returned to the caller. Maximum length is 725 bytes.
target_key_token
Direction: Output
Type: String
The key token built by this verb.