Parameters

Edit online

The parameter definitions for CSNBKPI.

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 elements in the rule_array variable. This value must be 1 or 2.
rule_array
The keyword that provides control information to the verb. The keywords must be eight bytes of contiguous storage with the keyword left-aligned in its 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1 .
Table 1. Keywords for Key Part Import control information
Keyword Description
Key part (One, required)
FIRST This keyword specifies that an initial key part is being entered. This verb returns this key-part encrypted by the master key in the key token that you supplied.
ADD-PART This keyword specifies that additional key-part information is provided.
COMPLETE This keyword specifies that the key-part bit shall be turned off in the control vector of the key rendering the key fully operational. Note that no key-part information is added to the key with this keyword.
MIDDLE This keyword specifies that an intermediate key part, which is neither the first key part nor the last key part, is being entered. Note that the command control point for this keyword is the same as that for the LAST keyword and different from that for the ADD-PART keyword.
LAST This keyword specifies that the last key part is being entered. The key-part bit is turned off in the control vector.
RETRKPR A key label must be passed as the key_identifier. This key label corresponds to a key stored in a KPIT register inside the crypto-card (not in host key storage). The key in that register has been loaded by label and key part using the KPIT verb by the TKE. This keyword for KPI allows the user to tell the card to wrap that key (it must be in the complete state) using the master key, place it in an internal token, and return that token to the user.

This keyword applies only when using IBM Z® .
RETRKPR token return (Optional)
RT-TOKEN The token returned by the RETRKPR service is returned directly to the caller and not stored in key storage. This optional keyword is usable only with the RETRKPR service.

If this keyword is not used, the RETRKPR service functions normally by storing the token according to the designated key storage label.
Key part buffer length (One, optional). A key part with a length that is less than the buffer size must be left-aligned in the buffer, that is, place the key part in the high-order bytes of the key-part field. Any trailing characters are not used.
KEYBUF16 Specifies a length of 16 bytes for the buffer identified by the key_part parameter. This is the default.
KEYBUF24 Specifies a length of 24 bytes for the buffer identified by the key_part parameter. This is required for a triple-length key when key part keyword COMPLETE is not specified.
Key-wrapping method (One, optional)
USECONFG This is the default. Specifies to wrap the key using the configuration setting for the default wrapping method. The default wrapping method configuration setting may be changed using the TKE. This keyword is ignored for AES keys.
WRAP-ENH Specifies to wrap the key using the legacy wrapping method. This keyword is ignored for AES keys.
WRAP-ECB Specifies to wrap the key using the enhanced wrapping method. Valid only for DES keys.
WRAPENH2 Specifies to wrap the key using the enhanced wrapping method and SHA-256. Valid only for TRIPLE or TRIPLE-O. This method requires CV bit 56 = B’1’ (ENH-ONLY). This is the default for TRIPLE and TRIPLE-O.
WRAPENH3 Specifies to wrap the key using the enhanced wrapping method with TDES-CMAC and the SHA-256 hashing algorithm. This keyword sets CV bit 56 = B’1’ (ENH-ONLY), which is required for the WRAPENH3 wrapping method.
key_part
A 16-byte field containing the clear key part to be entered. If the key is a single-length key, the key part must be left-aligned and padded on the right with zeros. This field is ignored if COMPLETE is specified.
key_identifier
A 64-byte field containing an internal token or a label of an existing key in the key storage file. If rule_array is FIRST, this field is the skeleton of an internal token of a single- or double-length key with the KEY-PART marking. If rule_array specifies MIDDLE or LAST, this is an internal token or key label of a partially combined key. Depending on the input format, the accumulated partial or complete key is returned as an internal token or as an updated key storage file record. The returned key_identifier is encrypted under the current master key.