Parameters

The parameters for CSNDSYI2.

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 may be 2, 3, or 4.

rule_array


Direction:	Input
Type:	String array

The keywords that provide control information to the verb. The following table provides a list. The recovery method is the method to use to recover the symmetric key. The keywords must be 8 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 Symmetric Key Import2 control information
Keywords for Symmetric Key Import2 control information
Keyword	Description
*Algorithm* (One, required)
AES	The key being imported is an AES key.
DES	The key being imported is a DES key.
HMAC	The key being imported is an HMAC key.
*Key formatting method* (One, required)
AESKW	Specifies that the enciphered input key is wrapped with the ANS X9.102 AESKW key-formatting method. Not valid with the DES token algorithm keyword.
AESKWCV	Specifies that the enciphered input key contains a control vector (key type DESUSECV) and is wrapped with the ANS X9.102 AESKW key-formatting method. Only valid with the DES token algorithm keyword.
CKM-RAKW	Specifies the enciphered_key is wrapped with the CKM_RSA_AES_KEY_WRAP mechanism. Not valid with the DES token algorithm keyword.
PKOAEP2	Specifies that the enciphered input key is wrapped with the key-wrapping method found in the RSA PKCS #1 v2.1 standard for the RSAES-OAEP encryption/decryption scheme. Not valid with the DES token algorithm keyword.
*Key wrapping method* (Optional, valid only for DES algorithm. The access control point Symmetric Key Import2 – Allow wrapping override keywords must be enabled to specify these keywords)
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 that the new enhanced wrapping method is to be used to wrap the key.
WRAP-ECB	Specifies that the original wrapping method is to be used.
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.
*Translation Control* (Optional, valid only for enhanced wrapping)
ENH-ONLY	Specify this keyword to indicate that the key once wrapped with the enhanced method cannot be wrapped with the original method. This restricts translation to the original method.

Note: There is no need for a hash method keyword, because the hash method is encoded in the external key-token carrying the encoded and encrypted payload.

enciphered_key_length


Direction:	Input
Type:	Integer

The length of the enciphered_key parameter. The maximum size is 900 bytes.

enciphered_key


Direction:	Input
Type:	String

The key to import, protected under either an RSA public key or an AES KEK. If the recovery method is PKOAEP2, the encrypted key is in the low-order bits (right-aligned) of a string whose length is the minimum number of bytes that can contain the encrypted key. If the recovery method is AESKW, the encrypted key is an AES key or HMAC key in the external variable length key token.

An AES key can also be in a CKM_RSA_AES_KEY_WRAP-wrapped payload (as produced by the CSNDSYX verb with the CKM-RAKW keyword). However, since just the key-material is wrapped and not the key-usage, compliance tagged key tokens are not supported.

transport_key_identifier_length


Direction:	Input
Type:	Integer

The length of the transport_key_identifier parameter. When the transport_key_identifier parameter is a key label, this field must be 64. The maximum size is 9992 bytes for a TR-31 token, 3500 bytes for an RSA private key, or 725 bytes for a CCA AES IMPORTER token.

transport_key_identifier


Direction:	Input
Type:	String

An internal RSA private key token, internal CCA AES IMPORTER KEK, internal TR-31 token, or the 64-byte label of such a key token whose corresponding key protects the symmetric key.

For key-formatting methods AESKW and AESKWCV, this must be a TR-31 token or a variable-length CCA AES key token. If it is a TR-31 token it must have the following attributes:

TR-31 key usage: K0
Algorithm: A
TR-31 mode of key use: D

If the token is a variable-length CCA AES key-token, then it must have IMPORTER key usage attributes. In addition, it must have the required algorithm wrap control attribute based on the token algorithm of the source key imported, and the required class wrap control attribute based on the class of source key imported as shown in the following tables:

Table with two columns
Token algorithm of source key imported	Required algorithm wrap control attribute
AES	WR-AES (Key can wrap or unwrap AES keys).
DES	WR-DES (Key can wrap or unwrap DES keys).
HMAC	WR-HMAC (Key can wrap or unwrap HMAC keys).

Table with two columns
Class of source key imported	Required class wrap control attribute
Data – key types: CIPHER, DATA, DATAC, DATAM, DATAMV, DECIPHER, ENCIPHER, MAC, MACVER, SECMSG	WR-DATA (Key can wrap or unwrap data class keys).
KEK – key types: EXPORTER, IKEYXLAT, IMPORTER, OKEYXLAT	WR-KEK (Key can wrap or unwrap KEK class keys).
PIN – key types: IPINENC, OPINENC, PINCALC, PINGEN, PINPROT, PINPRW, PINVER	WR-PIN (Key can wrap or unwrap PIN class keys).
Derivation – key types: DKYENKY, KEYGENKY	WRDERIVE (Key can wrap or unwrap derivation class keys).
Cryptovariable – key types: CVARENC, CVARPINE, CVARXCVL, CVARXCVR	WR-CVAR (Key can wrap or unwrap cryptovariable class keys).

For key-formatting method PKOAEP2, this is an operational key with the RSA private-key to be used to decrypt the OAEP-formatted message in the enciphered_key variable, or the label of such a record in PKA key-storage.

key_name_length


Direction:	Input
Type:	Integer

The length of the key_name parameter for target_key_identifier. 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 target_key_identifier.

target_key_identifier_length


Direction:	Input/Output
Type:	Integer

On input, the length in bytes of the buffer for the target_key_identifier parameter. The buffer must be large enough to receive the target key token. The maximum value is 725 bytes.

On output, the parameter will hold the actual length of the target key token.

target_key_identifier


Direction:	Output
Type:	String

This parameter contains the internal token of the imported symmetric key.

When the transport_key_identifier is compliant-tagged, the key is imported as a compliant-tagged key token.

When using the CKM-RAKW keyword, the target_key_identifier must be a variable length symmetric AES skeleton token. The skeleton token must be of type CIPHER and provide the desired key usage in the skeleton (for example, ANY-MODE mode, GCM mode, and so on). Use the Key Token Build2 service (CSNBKTB2) to create a skeleton with the desired attributes.