Parameters

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. This value must be 2 or 3.

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 Part Import2 control information

Keywords for Key Part Import2 control information

Keyword	Description
Token algorithm (Required)
HMAC	Specifies to import an HMAC key token.
AES	Specifies to import an AES key token.
DES	Specifies to import a DES key token. This keyword is only valid with a TR-31 key block header in the key_identifier parameter.
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.
RETRKPR	A key label must be passed as the key_identifier. This key label corresponds to a key stored in an internal register inside the cryptographic coprocessor (not in host key storage). The key in that register has been loaded by label and key part securely form the TKE. The RETRKPR keyword for CSNBKPI2 allows the user to tell the card to wrap that key loaded from the TKE (it must be in the complete state) using the master key, place it in an internal token, and return that token to the user.
RETRKPR token return (Optional)
RT-TOKEN	Using the RETRKPR keyword returns the token directly to the caller and does not store it in key storage. The optional RT-TOKEN keyword is usable only together with the RETRKPR keyword. If this keyword is not used, the RETRKPR service functions normally by storing the token according to the designated key storage label.
Split knowledge (Optional, required when keyword FIRST is used)
MIN3PART	Specifies that the key must be entered in at least three parts.
MIN2PART	Specifies that the key must be entered in at least two parts.
MIN1PART	Specifies that the key must be entered in at least one part.

key_part_bit_length

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of clear-key bits in the key_part variable. For keywords FIRST and ADD-PART, this value must be 128, 192, or 256 for an AES key, 80 - 2048 for an HMAC key, and 64, 128, or 192 for a DES key.

For 8-byte DES keys, place the key part in the high-order bytes of the 16-byte or 24-byte key_part parameter. According to FIPS PUB 198, the size of an HMAC key shall be equal to or greater than L/2, where L is the size of the hash function output. The value must be 0 for the COMPLETE and RETRKPR keywords.

key_part

Direction:	Input
Type:	String

This parameter is the clear key value to be applied. The key part must be left-aligned. This parameter is ignored if COMPLETE is specified.

key_identifier_length

Direction:	Input/Output
Type:	Integer

On input, the length of the buffer for the key_identifier parameter. For labels, the value is 64. The key_identifier must be left-aligned in the buffer. The buffer must be large enough to receive the updated token. The maximum value is 725. The output token will be longer when the first key part is imported.

On output, the actual length of the token returned to the caller. For labels, the value will be 64.

If the rule_array parameter contains the keyword RETRKPR, on input the key_identifier_length must be 64 to indicate the input label size, while the buffer must be large enough to receive the returned token, (725 is recommended). On output, key_identifier_length is updated to the length of the returned key_identifier parameter.

key_identifier

Direction:	Input/Output
Type:	String

A pointer to a string variable containing an internal variable-length symmetric key token or a key label identifying a key storage record for such a token. If a key label identifies a key record in AES key-storage, the returned key token replaces any key token associated with that label. If the first byte of the identified string does not indicate a key label (that is, not in the range X’20’ – X’FE’), and the variable is of sufficient length to receive the result, then the key token is returned in the identified variable.

Starting with CCA release 8.1, this variable can also contain a TR-31 key block header that the clear key will be placed in. This requires the access control point (ACP) KPI2 TR31 IMPORT (’03BC’) to be set.

If keyword ADD-PART is specified, this is an internal token or the label of a key storage file record 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 record in a key storage file. The returned value in key_identifier will be encrypted under the current master key.