Parameters

Edit online

The parameter definitions for CSNDPKI.

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
A pointer to an integer variable containing the number of elements in the rule_array variable. This value may be in the range 0 - 3.
rule_array
Direction: Input
Type: String array
The rule_array parameter is a pointer to a string variable containing a keyword. The keyword is 8 bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords are described in Table 1.
Table 1. Keywords for PKA Key Import control information

Keywords for PKA Key Import control information
Keyword Description
Token type (One, optional)
ECC Specifies that the key being imported is an ECC key.
RSA Specifies that the key being imported is an RSA key or a trusted block. This is the default.
QSA Specifies that the key token contains a QSA key. Only clear keys are supported.
Transport key type (optional, not valid with PQC keys).
IKEK-AES The transport_key_identifier is an AES key in a CCA or TR-31 key token.
IKEK-DES The transport_key_identifier is a DES key in a CCA or TR-31 key token. This is the default.
IKEK-PKA The inbound key-encrypting key identified by the transport_key_identifier parameter is a PKA key.
Note: This option is only valid with the CKM-RAKW keyword, and the key-encrypting key must be an RSA key.
Key wrap type (one, required when IKEK-PKA is specified).
CKM-RAKW Specifies that the source_key_token is wrapped using the CKM_RSA_AES_KEY_WRAP openCryptoki/PKCS #11 mechanism. Only valid for RSA and ECC.
source_key_token_length
Direction: Input
Type: Integer
The length of the source_key_token parameter. The maximum size is 8000 bytes.
source_key_token
Direction: Input
Type: String
The source_key_token parameter contains one of the following:
  • A PKA (RSA, ECC, or QSA) key token.
  • An active external trusted block.
  • An RSA AES key wrapped object (that is, structure corresponding to the output from the PKCS #11 mechanism CKM_RSA_AES_KEY_WRAP).
For an RSA, ECC, or QSA key token, the token must contain both public-key and private-key information. The private key can be in clear-text or it can be enciphered.
transport_key_identifier
Direction: Input/Output
Type: String

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

For source 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 transporter key.
  • A variable-length AES internal key token containing the transport key.
  • An RSA private key when the source is a CKM_RSA_AES_KEY_WRAP formatted object.
  • A variable-length X9.143 (TR-31) key block containing the transport key:
    • TR-31 key usage: K0
    • Algorithm: A or T
    • TR-31 mode of key 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: Input/Output
Type: Integer
The length of the target_key_identifier parameter in bytes. The maximum size 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 PKA key storage, 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: Input/Output
Type: String
This field contains the internal token or label of the imported PKA private key or a trusted block. If a label is specified on input, a PKA key storage record with this label must exist. The PKA key storage record with this label will be overwritten with the 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. If no label is specified on input, this field is ignored and should be set to binary zeros.

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

When importing CKM-RAKW wrapped keys, the target_key_identifier is used to indicate the token type and attributes for the imported key. For RSA keys, only private section types X'30', X'31', and X'08' are supported. For ECC keys, private section type X'20' is supported. Because only the key material is wrapped and not the key attributes, compliant-tagged key tokens are not supported. The PKA Key Token Build (CSNDPKB) callable service can be used to build the skeleton token for the target_key_identifier.