Parameters

Edit online

The parameters for CSNDPKE.

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 in the range 1 - 8.
rule_array
Direction: Input
Type: String array
A keyword that provides control information to the verb. The 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 Encrypt control information

Keywords for PKA Encrypt control information
Keyword Description
Formatting method (One, required). Specifies the method to use to format the key value prior to encryption.
MRP The key value will be padded on the left with binary zeros to the length of the PKA key modulus. The RSA public key can have an even or odd exponent.
PKCS-1.2 RSA DSI PKCS #1 block type 02 format will be used to format the supplied key value. In the RSA PKCS #1 v2.0 standard, RSA terminology describes this as the RSAES-PKCS1-v1_5 format. This method is deprecated and should not be used for any new development.
PKCSOAEP Specifies that the key is formatted as defined in the RSA PKCS #1 v2.0 standard for the RSAES-OAEP encryption/decryption scheme. See PKCS #1 hash formats.
PKOAEP2 Specifies that the key is formatted as defined in the RSA PKCS #1 v2.1 standard for the RSAES-OAEP encryption/decryption scheme. See PKCS #1 hash formats.
ZERO-PAD The key value is padded on the left with binary zeros to the length of the PKA key modulus. The exponent of the RSA public key must be odd. Required if the PKA_key_identifier parameter specifies a CRYSTALS-Kyber or ML-KEM public key. This method is deprecated and should not be used for any new development.
Hash method (One required for PKCSOAEP and PKOAEP2. Not allowed for any other recovery method).
SHA-1 Specifies to use the SHA-1 hash method to calculate the OAEP message hash.
SHA-224 Specifies to use the SHA-224 hash method to calculate the OAEP message hash. Only valid with keyword PKOAEP2.
SHA-256 Specifies to use the SHA-256 hash method to calculate the OAEP message hash.
SHA-384 Specifies to use the SHA-384 hash method to calculate the OAEP message hash. Only valid with keyword PKOAEP2.
SHA-512 Specifies to use the SHA-512 hash method to calculate the OAEP message hash. Only valid with keyword PKOAEP2.
Mask Generation Function Method (one, optional). Available for PKOAEP2 Formatting method only. Requires CCA releases 7.5 or 8.2. Default is to match the Hash method).
MSHA-1 Specifies to use the SHA-1 MGF method to calculate the OAEP mask.
MSHA-224 Specifies to use the SHA-224 MGF method to calculate the OAEP mask.
MSHA-256 Specifies to use the SHA-256 MGF method to calculate the OAEP mask.
MSHA-384 Specifies to use the SHA-384 MGF method to calculate the OAEP mask.
MSHA-512 Specifies to use the SHA-512 MGF method to calculate the OAEP mask.
Key rule (Optional. Exception: Key rule RANDOM is required for ML-KEM).
RANDOM This indicates to generate a random 32-byte value and return this value, encrypted and formatted according to the Formatting method keyword. The random 32-byte value can be returned in one of three ways:
  1. encrypted under the provided AES CIPHER key provided in parameter sym_key_identifier, using the AES encryption initialization vector provided as input through the keyvalue parameter. This encrypted value is returned as output to the keyvalue parameter
  2. encrypted under the QSA public key provided in the PKA_key_identifier, returned in the PKA_enciphered_keyvalue parameter.
  3. In the clear. The random value may be returned in the clear only when using an ML-KEM public key. Only valid with ZERO-PAD and when the PKA_key_identifer parameter contains a QSA public key. Required when the PKA_key_identifer parameter contains an ML-KEM public key.
Key Format (one, optional). Only allowed when PKA_key_identifier contains an ML-KEM key, otherwise it must not be specified. If no keyword from this group is specified, nothing is written to the keyvalue parameter on output.
CLEAR Specifies that the 32 byte random value is written to the keyvalue parameter in the clear.
AES-ENC Specifies that the 32 byte random value is written to the keyvalue parameter encrypted using the AES key provided in parameter sym_key_identifer.
AES-KB Specifies that the 32 byte random value is written to the keyvalue parameter in an AES key block as defined by the skeleton key token provided in parameter sym_key_identifer.
Regeneration data option (one, optional). Valid only for ML-KEM X’06’ keys.
RAWSEED Specifies that the given raw seed located after the first two bytes of the keyvalue parameter are used to seed the encryption process. This means that the caller cannot supply the data to be encrypted. The first two bytes of the keyvalue parameter define the length of the seed. Requires the RANDOM and CLEAR rules to be specified.

If using an ML-KEM key, the 32-byte formatted random value is returned in the format specified by the Key Format rule.

Certificate validation method (One, required for VAL-CERT)
RFC-2459 Attempt to validate the certificate using the semantics of RFC-2459.
RFC-3280 Attempt to validate the certificate using the semantics of RFC-3280
RFC-5280 Attempt to validate the certificate using the semantics of RFC-5280
RFC-ANY Attempt to validate the certificate using first the semantics of RFC-2459, then RFC-3280, and then RFC-5280. If the certificate is not compliant with any RFC, the first error encountered (from RFC-2459 processing) is returned.
Public key infrastructure usage (one, optional).
PKI-CHK Specifies that the X.509 certificate for the other party (KRD) is to be validated against the trust chain of the PKI hosted in the adapter. This requires that the CA credentials have been installed using the Trusted Key Entry (TKE) workstation.

This is the default.
PKI-NONE Specifies that the X.509 certificate for the other party (KRD) is not to be validated against the trust chain of the PKI hosted in the adapter. This is suitable if the certificate has been validated using host-based PKI services.
keyvalue_length
Direction: Input/Output
Type: Integer

The length of the keyvalue parameter in bytes. The maximum length is 9992 bytes.

When the PKA_key_identifier is an RSA key:

  • The actual maximum size depends on the modulus length and the formatting method you specify in the rule_array parameter.

When the PKA_key_identifier is a CRYSTALS-Kyber public key, and

  • the RANDOM keyword has not been specified, then the keyvalue_length parameter must be 32 bytes.
  • the RANDOM keyword is specified, and
    • the sym_key_identifier parameter contains an AES CIPHER key, this parameter must be 32 bytes or larger. On return this field is updated to the actual length of the keyvalue parameter.
    • the sym_key_identifier does not contain a key, this parameter is required to be set to zero, and is not updated.

When the PKA_key_identifier is an ML-KEM public key, and

  • if the RAWSEED rule_array keyword is specified, then the keyvalue_length parameter must be 34 bytes or larger. On return, this field is updated with the actual length of the keyvalue parameter.
  • if the CLEAR or AES-ENC keyword is specified, then the keyvalue_length parameter must be 32 bytes or larger. On return, this parameter is updated with the actual length of the keyvalue parameter.
  • if the AES-KB keyword is specified, then the keyvalue_length parameter must be large enough to hold the output key token or key block. The maximum output is 9992 bytes.
  • if no keyword from the Key Format group is specified, then this parameter must be set to zero and is not updated.
keyvalue
Direction: Input/Output
Type: String
This field contains the supplied clear key value to be encrypted under the PKA_key_identifier.

When the PKA_key_identifier is an RSA key:

  • On input, this field contains the supplied clear key value to be encrypted under the PKA_key_identifier. It is not updated on output.

When the PKA_key_identifier is a CRYSTALS-Kyber public key and:

  • the RANDOM keyword has not been specified:

    On input, this field contains the supplied clear key value to be encrypted under the PKA_key_identifier.

    On output, it contains the encrypted key value.

  • The RANDOM keyword has been specified and
    • sym_key_identifier contains an AES CIPHER key, a random 32-byte value is generated and returned in an encrypted form.

      On input, this parameter should contain the 16-byte initialization vector for the AES encryption left justified in the buffer.

      On output, the keyvalue parameter is updated to contain the random 32-byte value enciphered by the AES CIPHER key passed in the sym_key_identifier parameter.

    • sym_key_identifier does not contain an AES CIPHER key, this parameter is not used.

When the PKA_key_identifier is an ML-KEM public key:

  • on input:
    • If the RAWSEED keyword is specified, the first two bytes must be the seed length (n) followed by n bytes of seed data. The seed length (n) must be 32 bytes.
    • If the AES-ENC keyword is specified, this parameter should contain the 16-byte initialization vector for the AES encryption left justified in the buffer.
    • Otherwise, this parameter is not used on input.
  • on output: it contains the keyvalue in the format specified in the Key Format rule array group.

If the RAWSEED rule_array keyword is specified, the first two bytes of the keyvalue parameter are interpreted as the length <num> of the raw seed to be used in the encryption process. The seed is located after the seed length field. The data to be encrypted is located after both, the two-byte length field, and <num> number of seed bytes.

RAWSEED requires both the RANDOM and the CLEAR rule_array keywords to be specified. RAWSEED is also only valid for ML-DSA and ML-KEM.

sym_key_identifier_length
Direction: Input
Type: Integer

The length of the sym_key_identifier parameter in bytes. Only used when the PKA_key_identifier is a CRYSTALS-Kyber or ML-KEM key. For ML-KEM keys, this field must be greater than zero, if the AES-KB or AES-ENC rule_array keywords have been specified.

For non CRYSTALS-Kyber or ML-KEM cases, this value is 0.

sym_key_identifier
Direction: Input
Type: String

When the PKA_key_identifier is a CRYSTALS-Kyber or ML-KEM public key, the RANDOM keyword has been specified, and the sym_key_identifier is needed to encrypt the output value, this parameter contains the identifier of the key to encrypt the value.

Otherwise, this field is ignored.

This key identifier is an operational CCA or TR-31 token or the key label of such a token in key storage. For CCA tokens, the key algorithm must be AES, the key type must be CIPHER (variable-length token, version X'05'). The key usage must indicate ENCRYPT and the CBC mode of encryption.

For TR-31 tokens, the key must have the following attributes:

  • TR-31 key usage: D0
  • Algorithm: A
  • TR-31 mode of key use: B or E

If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.

For ML-KEM keys, if the AES-ENC keyword or a variable length AES key token with keyword RANDOM is specified and the token is an internal TR-31 token, the key must have the following attributes:
  • TR-31 key usage: D0
  • Algorithm: A
  • TR-31 mode of key use: B or E
For ML-KEM, you need not provide the rule_array keyword AES-ENC, even if sym_key_identifer_length is larger than zero. But if you do provide the keyword AES-ENC, then the sym_key_identifier must be provided.
PKA_key_identifier_length
Direction: Input
Type: Integer
The length of the PKA_key_identifier parameter. When the PKA_key_identifier is a key label, this field specifies the length of the label. The maximum size that you can specify is 5000 bytes.
PKA_key_identifier
Direction: Input
Type: String

The token or label of an RSA public or private key token, or the X.509 certificate containing the RSA public key to be used to encrypt the supplied key value.

A CRYSTALS-Kyber or ML-KEM public key may also be specified. The CRYSTALS-Kyber or ML-KEM public key usage attribute must allow Data encipherment using the U-DATENC keyword of the CSNDPKB service.

Certificates may be PEM-formatted EBCDIC text or DER-encoded. The certificate may either have no RSA key usage attribute or it must have at least one of the following usages: Key encipherment or Data encipherment.

PKA_enciphered_keyvalue_length
Direction: Input/Output
Type: Integer
The length of the PKA_enciphered_keyvalue parameter in bytes.
  • The public key size for CRYSTALS-Kyber Round 2, (768), CRYSTALS-Kyber Round 3, (768), and ML-KEM (768) is the same = 1184 bytes.
  • The public key size for CRYSTALS-Kyber Round 2, (1024), CRYSTALS-Kyber Round 3, (1024), and ML-KEM (1024) is the same = 1568 bytes.
  • The private key size for CRYSTALS-Kyber Round 2, (768), CRYSTALS-Kyber Round 3, (768), and ML-KEM (768) is the same = 1216 bytes.
  • The private key size for CRYSTALS-Kyber Round 2, (1024), CRYSTALS-Kyber Round 3, (1024), and ML-KEM 1024 is the same = 1600 bytes.
  • The ciphertext size for CRYSTALS-Kyber Round 2, (768), CRYSTALS-Kyber Round 3, (768), and ML-KEM (768) is the same = 1088 bytes.
  • The ciphertext size for CRYSTALS-Kyber Round 2, (1024), CRYSTALS-Kyber Round 3, (1024), and ML-KEM 1024 is the same = 1568 bytes.
Table 2. Key and ciphertext sizes for ML-KEM and ML-DSA key types

Key and ciphertext sizes for ML-KEM and ML-DSA key types. A table with seven columns.
Algorithm and parameter set Security strength (bits) Security category Private key length (bytes) Public key length (bytes) Ciphertext length (bytes) Signature length (bytes)
ML-KEM 768 192 3 1216 1184 1088 N/A
ML-KEM 1024 256 5 1600 1568 1568 N/A
ML-DSA (4,4) 128 2 2528 1312 N/A 2420
ML-DSA (6,5) 192 3 4000 1952 N/A 3309
ML-DSA (8,7) 256 5 4864 2592 N/A 4627

On return, this field is updated with the actual length of PKA_enciphered_keyvalue. This length should be the same as the modulus length of the PKA_key_identifier.

PKA_enciphered_keyvalue
Direction: Output
Type: String
This field contains the key value protected under an RSA, CRYSTALS-Kyber, or ML-KEM public key. This byte-length string is left-aligned within the PKA_enciphered_keyvalue parameter.