PKA Encrypt (CSNDPKE and CSNFPKE)

CALL CSNDPKE(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             keyvalue_length,
             keyvalue,
             sym_key_identifier_length,
             sym_key_identifier,
             PKA_key_identifier_length,
             PKA_key_identifier,
             PKA_enciphered_keyvalue_length,
             PKA_enciphered_keyvalue)

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 that are 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 value can be 1 to 6 inclusive.

rule_array

Direction	Type
Input	String

A keyword that provides control information to the callable service. The keyword is left-justified in an 8-byte field and padded on the right with blanks.

Table 1. Keywords for PKA Encrypt

Keyword	Meaning
Formatting Method (required) specifies the method to use to format the key value prior to encryption.
PKCS-1.2	RSA PKCS #1 V1.5 block type 02 format will be used to format the supplied key value.
ZERO-PAD	The key value will be 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 when the PKA_key_identifier is a CRYSTALS-Kyber public key.
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 may have an even or odd exponent.
PKCSOAEP	Specifies to format the data using the RSAES-OAEP encoding scheme defined in the RSA PKCS #1 V2.0 standard. The formatted key is encrypted by the RSA public-key provided as the transport key and returned as an opaque data buffer.
PKOAEP2	Specifies that the key is formatted as defined in the RSA PKCS #1 v2.1 standard for the RSAES-OAEP encryption/decryption scheme.
Hash Method (one required when PKCSOAEP or PKOAEP2 is specified. Otherwise, not allowed.)
SHA-1	Specifies to use the SHA-1 method to calculate the OAEP message digest.
SHA-224	Specifies to use the SHA-224 method to calculate the OAEP message digest. Only supported with PKOAEP2.
SHA-256	Specifies to use the SHA-256 method to calculate the OAEP message digest.
SHA-384	Specifies to use the SHA-384 method to calculate the OAEP message digest. Only supported with PKOAEP2.
SHA-512	Specifies to use the SHA-512 method to calculate the OAEP message digest. Only supported with PKOAEP2.
Key Rule (optional)
KEYIDENT	This indicates that the value in the keyvalue field is the label of a clear key token in the CKDS. The keyvalue_length must be 64. Not supported when the PKA_key_identifier is a CRYSTALS-Kyber public key.
RANDOM	This indicates to generate a random 32-byte value and return this value, formatted according to the formatting method keyword and encrypted. The random 32-byte value can be returned in one of two ways: Encrypted under the provided AES CIPHER key provided in sym_key_identifier, using the AES encryption IV provided as input through the keyvalue parameter. This encrypted value is returned as output to the keyvalue parameter. Encrypted under the CRYSTALS-Kyber public key provided in the PKA_key_identifier parameter, returned in the PKA_enciphered_keyvalue parameter. Only valid with ZERO-PAD and when the PKA_key_identifier contains a CRYSTALS-Kyber public key.
Certificate validation method (one required when the input is an X.509 certificate. Otherwise, must not be specified.)
RFC-2459	Validate the certificate using the semantics of RFC-2459.
RFC-3280	Validate the certificate using the semantics of RFC-3280.
RFC-5280	Validate the certificate using the semantics of RFC-5280.
RFC-ANY	Attempt to validate the certificate by first using the semantics of RFC-2459, then the semantics of RFC-3280, and finally, the semantics of RFC-5280.
Public Key Infrastructure Usage (one optional when the input is an X.509 certificate. Otherwise, must not be specified.)
PKI-CHK	Specifies that the X.509 certificate is to be validated against the trust chain of the PKI hosted in the adapter. This requires that the CA credentials have been installed into all coprocessors using the Trusted Key Entry workstation. This is the default.
PKI-NONE	Specifies that the X.509 certificate 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 or if using a self-signed certificate.
Mask Generation Function Method (one, optional, PKOAEP2 formatting method only, 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.

keyvalue_length

Direction	Type
Input/Output	Integer

The length of the keyvalue parameter. The maximum field size is 512 bytes. The actual maximum size depends on the RSA modulus length of PKA_key_identifier and the formatting method you specify in the rule_array parameter. When key rule KEYIDENT is specified, then the keyvalue_length parameter is required to be 64 bytes.

When the PKA_key_identifier is a CRYSTALS-Kyber public key and the RANDOM keyword has not been specified, the keyvalue_length parameter is required to be 32 bytes.

When the RANDOM keyword is specified and sym_key_identifier contains an AES CIPHER key, the keyvalue_length parameter must be 32 bytes or larger. On return, this field will be updated with the actual length of the keyvalue parameter.

When PKA_key_identifier is a CRYSTALS-Kyber public key, the RANDOM keyword has been specified, and sym_key_identifier does not contain a key, this parameter is required to be set to zero and is not updated.

keyvalue

Direction	Type
Input	String

This field contains the supplied clear key value to be encrypted under the PKA_key_identifier. When key rule KEYIDENT is specified, the keyvalue parameter is assumed to contain a label for a valid CKDS clear key token.

When the PKA_key_identifier is a CRYSTALS-Kyber public key, 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 will be updated to contain the random 32-byte value enciphered by the AES CIPHER key passed in the sym_key_identifier parameter.

When the PKA_key_identifier is a CRYSTALS-Kyber public key, the RANDOM keyword has been specified, and the sym_key_identifier does not contain an AES CIPHER key, this parameter is not updated.

sym_key_identifier_length

Direction	Type
Input	Integer

The length of the sym_key_identifier parameter in bytes.

When the PKA_key_identifier is a CRYSTALS-Kyber public key, the RANDOM keyword has been specified, and the sym_key_identifier is needed to encrypt the output value:

• When the sym_key_identifier contains a label, the length must be 64.
• When the sym_key_identifier contains a key token, the length must be between the actual length of the token and 9992.

Otherwise, this value must be 0.

sym_key_identifier

Direction	Type
Input/Output	String

The identifier of the data-encrypting key to encrypt the output value. The key identifier is a variable-length key token or key block or the label of a token or block in key storage.

When sym_key_identifier_length is zero, this parameter is ignored.

For CCA keys, the identifier is a variable-length AES key token of key type CIPHER with key usage attributes ENCRYPT and CBC enabled.

For X9.143 (TR-31) keys, the identifier is a variable-length key block of an AES data-encrypting key usage D0, algorithm A, and mode of use B or E.

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

PKA_key_identifier_length

Direction	Type
Input	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 8000 bytes.

PKA_key_identifier

Direction	Type
Input	String

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

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: keyEncipherment or dataEncipherment.

CRYSTALS-Kyber public key usage attribute must allow dataEncipherment.

PKA_enciphered_keyvalue_length

Direction	Type
Input/Output	Integer

The length of the PKA_enciphered_keyvalue parameter in bytes. The maximum size that can be generated when the PKA_key_identifier is an RSA key is 512 bytes. This length should be the same as the modulus length of the PKA_key_identifier.

When the PKA_key_identifier is a CRYSTALS-Kyber public key, the PKA_enciphered_keyvalue_length is the same as the size of the public key material. For a Crystals-Kyber(1024) key, this is 1568 bytes.

On return, this field is updated with the actual length of PKA_enciphered_keyvalue.

PKA_enciphered_keyvalue

Direction	Type
Output	String

This field contains the key value protected under an RSA or CRYSTALS-Kyber public key. This byte-length string is left-justified within the PKA_enciphered_keyvalue parameter.

The exponent for RSA public keys must be odd.

RSA keys 512-bit to 2048-bit may have a public exponent of 3, 5, 17, 257, 65537, or random. Support for RSA public exponents 5, 17, and 257 requires the October 2016 or later licensed internal code (LIC).

The PKA Encrypt access control point controls the function of this service.

Use of a CRYSTALS-Kyber public key in the PKA_key_identifier parameter requires the PKA Encrypt - Allow CRYSTALS-Kyber keys access control point.

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.