PKA Key Import (CSNDPKI and CSNFPKI)

CALL CSNDPKI(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             source_key_identifier_length,
             source_key_identifier,
             importer_key_identifier,
             target_key_identifier_length,
             target_key_identifier)

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return/reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. ICSF and cryptographic coprocessor return/reason codes lists the reason codes.

exit_data_length

Direction	Type
Input/Output	Integer

The length of the data that is passed to the installation exit. The data is identified in the exit_data parameter.

exit_data

Direction	Type
Input/Output	String

The data that is passed to the installation exit.

rule_array_count

Direction	Type
Input	Integer

The number of keywords you supplied in the rule_array parameter. This may be 0, 1, or 2.

rule_array

Direction	Type
Input	Character String

The rule_array parameter is an array of keywords. The keywords must be 8 bytes of contiguous storage with the keyword left-justified in its 8-byte location and padded on the right with blanks. The rule_array keywords are:

Table 1. Keywords for PKA Key Import

Keyword	Meaning
Token Type (optional)
RSA	Specifies that the key token contains an RSA key. This is the default.
ECC	Specifies that the key token contains an ECC key.
QSA	Specifies that the key token contains a QSA key. Only clear keys are supported.
Transport key type (optional)
IKEK-AES	The importer_key_identifier is a AES key.
IKEK-DES	The importer_key_identifier is a DES key. This is the default.

source_key_identifier_length

Direction	Type
Input	Integer

The length of the source_key_identifier parameter in bytes. The maximum size is 8000 bytes.

source_key_identifier

Direction	Type
Input	String

The external key token of an ECC, RSA, or QSA private key or active external trusted block to be imported. The ECC, RSA, and QSA key token must contain both public-key and private key information. The private key can be in cleartext or it can be enciphered.

importer_key_identifier

Direction	Type
Input/Output	String

The identifier of the key-encrypting key to unwrap the source key. The key identifier is a variable-length operational key token or key block or the label of an operational token or block in key storage.

For RSA keys, this is either a DES limited authority transport key (IMP-PKA) or an AES transport key. For trusted blocks, this must be a DES limited authority transport key (IMP-PKA). For ECC keys, this must be an AES transport key. For QSA keys, this must be a null token.

This parameter contains one of the following:

• 64-byte null token when the source key is a QSA key.
• 64-byte label of a CKDS record that contains the transport key.
• 64-byte DES internal key token containing the transport key.
• a variable-length AES internal key token containing the transport key.
• a variable-length X9.143 (TR-31) key block containing the transport key: key usage K0, algorithm A or T, and mode of use D.

This parameter is ignored for clear tokens.

If the token or key block supplied was encrypted under the old master key, the token or key block will be returned encrypted under the current master key.

target_key_identifier_length

Direction	Type
Input/Output	Integer

The length of the target_key_identifier parameter in bytes. The maximum value is 8000 bytes.

On input, this is the size of the buffer to receive the output key token. If the target_key_identifier is the label of an existing record in the PKDS, the value must be 64.

On output, and if the size is of sufficient length, the parameter is updated with the actual length of the returned key token.

target_key_identifier

Direction	Type
Input/Output	String

This parameter contains the internal token or label of the imported PKA private key or a Trusted Block. If a label is specified on input, a PKDS record with this label must exist. The PKDS record with this label will be overwritten with imported key unless the existing record is a retained key. If the record is a retained key, the import will fail. A retained key record cannot be overwritten.

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

This service imports RSA keys of up to 4096 bits. However, the hardware configuration sets the limits on the modulus size of keys for digital signatures and key management; thus, the key may be successfully imported but fail when used if the limits are exceeded.

The importer_key_identifier is a limited-authority key-encrypting key.

CRT form tokens with a private section ID of X'05' cannot be imported into ICSF.

SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS.

An RSA modulus-exponent form token imported results in a X'06' format.

This service imports keys of any modulus size up to 4096 bits. However, the hardware configuration sets the limits on the modulus size of keys for digital signatures and key management; thus, the key may be successfully imported but fail when used if the limits are exceeded.

The PKA Key Import access control point controls the function of this service. If the source_key_token parameter points to a trusted block, the PKA Key Import - Import an external trusted block access control point must also be enabled.

To prevent the importing of key tokens which have the private key values in the clear, the PKA Key Import – Disallow clear key import must be enabled.

The Allow weak DES wrap of RSA access control allows a weaker DES key-encrypting key to wrap an RSA private key token. The Prohibit weak wrap – Transport keys access control must be enabled and this access control will override the restriction.

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. The CCA releases used in the table are described in CCA release levels.