Parameters

Edit online

The parameter definitions for CSNDPKG.

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 must be 1, 2, or 3.
rule_array
Direction: Input
Type: String array
A keyword that provides control information to the verb. A keyword is left-aligned in an 8-byte field and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for PKA Key Generate control information

Keywords for PKA Key Generate control information
Keyword Description
Private key encryption (One, required)
CLEAR Return the private key in cleartext. The private key in cleartext is an external token.
MASTER Uses a master key to either encipher the PKA private-key or to encipher the object protection key (OPK) and its data. The OPK is used to encipher the ECC private key, QSA private key, or private key of RSA sections X'30' or X'31'. The transport_key_identifier parameter should specify a null key-token. The keyword is not supported if a skeleton token with a X'09' section is provided.
RETAIN Retains the private key within the cryptographic engine and returns the public key. This is only valid for RSA signature keys. Because of this, the RETAIN keyword is not supported for:
  • an RSA skeleton token with a X'09', X'30' or X'31' section provided
  • a non-RSA key token.

Before using this keyword, see the information about retained keys in Using retained keys.

Note: Take special notice on the types of skeleton key tokens that can be passed. The PKA Key Token Build verb will, of course, let you create many more types of skeleton key tokens than can be used to generate retained keys, because this is the minority of supported function.
XPORT Enciphers the private key under the IMPORTER or EXPORTER key-encrypting-key identified by the transport_key_identifier parameter. For an RSA key, this is an EXPORTER or IMPORTER transport key in a fixed-length operational DES key-token. For an ECC key, this is an EXPORTER or IMPORTER transport key in an operational variable-length AES key-token. Additionally, an EXPORTER or IMPORTER TR-31 KEK can be used for both RSA and ECC keys. This keyword is valid only for RSA and ECC keys.

This keyword is supported for ML-KEM and pure and pre-hash ML-DSA key tokens.

This keyword is not supported for CRYSTALS-Dilithium and CRYSTALS-Kyber tokens.
RETAIN option (one, optional). Valid only with the RETAIN keyword.
CLONE Mark a generated and retained private key as usable in cryptographic engine cloning process. This keyword is supported only if RETAIN is also specified. Only valid for RSA keys. Because of this, the CLONE keyword is not supported for:
  • an RSA skeleton token with a X'09', X'30' or X'31' section provided
  • a non-RSA key token.
Regeneration data option (One, optional).
ITER-38 Force 38 iterations of tests for primality, as required by ANSI X9.31 for the Miller-Rabin primality tests. This option produces a more secure key, but it is labor intensive. This keyword is invalid for ECC key generation.
RAWSEED Specifies that the given raw seed in the regeneration_data parameter is used to seed the key generation process. Only valid for ML-DSA/ML-KEM key types X’05’, X’06’. X’07’.
Transport key-type (one, optional; one required if transport_key_identifier is a label). If this keyword is specified, it must match the type of key to be transported, whether the identifier is a label or not.
OKEK-AES The outbound key-encrypting key represents an AES key-token.
OKEK-DES The outbound key-encrypting key represents a DES key-token. This is the default.
regeneration_data_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the regeneration_data variable.

This parameter must be 0 for ECC tokens (section X'20'), CRYSTALS-Dilithium tokens, and CRYSTALS-Kyber tokens.

For RSA tokens, the value must be 8 - 512.

For ML-DSA tokens this must be either 0 or 32, for ML-KEM tokens this must be either 0 or 64.

Otherwise, this must be a value of 0, or in the range from 8 – 256.

If the value is 0, the generated keys are based on a random-seed value. If this value is between 8 - 256, the regeneration data is hashed to form a seed value used in the key generation process to provide a means for recreating a public-private key pair.

If the key token is ML-DSA or ML-KEM, the regeneration data is used unaltered to regenerate the public and private key pair.

regeneration_data
Direction: Input
Type: String
This parameter points to a string variable containing a value used as the basis for creating a particular public-private key pair in a repeatable manner. For key tokens other than ML-DSA or ML-KEM, the regeneration data is hashed to form a seed value used in the key generation process and provides a means for recreating a public and private key pair.

For ML-DSA and ML-KEM tokens, the regeneration data is used unaltered to regenerate the public and private key pair.

skeleton_key_identifier_length
Direction: Input
Type: Integer
The length of the skeleton_key_identifier parameter in bytes. The maximum allowed value is 6500 bytes.
skeleton_key_identifier
Direction: Input
Type: String
A pointer to the application-supplied skeleton key token generated by PKA Key Token Build, or the label of the token that contains the required modulus length and public exponent for RSA key generation, or the required curve type and bit length for ECC key generation.

If RETAIN was specified and the skeleton_key_identifier is a label, the label must match the private key name of the key. For RSA keys, the skeleton_key_identifier parameter must contain a token that specifies a modulus length in the range 512 - 4096 bits.

To generate a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.

transport_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing an operational AES or DES key-encrypting-key token, a null key-token, or a key label of such a key. Use an IMPORTER key to encipher a private key to be used at this node. Use an EXPORTER key to encipher a private key to be used at another node. Choose one of the following:
  • When generating an ECC key with the XPORT rule-array keyword, provide the variable-length symmetric IMPORTER or EXPORTER key-token to be used to wrap the generated ECC key. Key bit lengths of 128, 192, and 256 are supported. If this parameter points to a key label, specify rule-array keyword OKEK-AES to indicate that the AES key-storage dataset contains the key token.
  • When generating an RSA key with the XPORT rule-array keyword, provide the fixed-length DES IMPORTER> or EXPORTER key-token to be used to wrap the generated RSA key. If this parameter points to a key label, specify rule-array keyword OKEK-DES to indicate that the DES key-storage dataset contains the key token.
  • When using a TR-31 KEK with the XPORT rule-array keyword, then provide the TR-31 symmetric IMPORTER or EXPORTER key token to be used to wrap the generated RSA or ECC key. The TR-31 token must have the following properties:
    • TR-31 key usage: K0
    • Algorithm: A or T
    • TR-31 mode of key use: D or E
  • If the XPORT rule array keyword is not used, then specify a null key-token. If this parameter points to a key label, specify keyword OKEK-AES for an ECC key or keyword OKEK-DES for an RSA key.
generated_key_identifier_length
Direction: Input/Output
Type: Integer
The length of the generated key token. The field is checked to ensure that it is at least equal to the size of the token being returned. The maximum size is 8000 bytes. On output, this field is updated with the actual token length.
generated_key_identifier
Direction: Input/Output
Type: String

The internal token or label of the generated key. The label can be that of a retained key for most RSA key tokens.

Checks are made to ensure that:

  • An ECC or QSA token in the public key data set (PKDS) can only be overlaid with a token of the same type.
  • A retained key cannot be overlaid in the PKDS. If the label is that of a retained key, the private name in the token must match the label name.

    If a label is specified in the generated_key_token parameter, the generated_key_token_length returned to the application is the same as the input length.

    If RETAIN was specified, but the generated_key_token was not specified as a label, the generated key length returned to the application is zero (the key was retained in the cryptographic coprocessor).

    If the record already exists in the PKDS with the same label as the one specified as the generated_key_token, the record is overwritten with the newly generated key token (unless the PKDS record is an existing retained private key, in which case it cannot be overwritten).

    If there is no existing PKDS record with this label in the case of generating a retained key, a record is created.

  • For generation of a non-retained key, if a label is specified in the generated_key_token parameter, a record must already exist in the PKDS with this same label or the service will fail.
    Note: Tokens containing a X'09' section (RSA private key, 4096-bit Modulus-Exponent format) can only be used in a PKA Key Translate verb.