Parameters

Edit online

The parameter definitions for CSNDEDH.

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. Valid values are 1 - 6.
rule_array
Direction: Input
Type: String array
A pointer to a string variable containing an array of keywords. The keywords are 8 bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords for this verb are shown below:
Table 1. Keywords for EC Diffie-Hellman control information

Keywords for EC Diffie-Hellman control information
Keyword Meaning
Scheme (one, optional).
ECDH Specifies to follow the Elliptic Curve Diffie Hellman Key Agreement Scheme. This is the default.
QSA-ECDH Specifies to follow the Hybrid QSA Key Exchange Scheme as described in Creating a hybrid post quantum key exchange scheme. The hybrid_key_identifier parameter must contain the key used to decrypt the value in the hybrid_ciphertext parameter.
Key agreement (one required). Initiator and responder must have a sufficient level of trust such that they each derive only one element of any key pair. DERIV01 is designed for CCA-to-CCA interaction.
DERIV01 Use input skeleton key-token and derive one element of any key pair. Denotes ANS X9.63 protocol static unified model key-agreement scheme (see NIST SP800-56A).
DERIV02 Use input skeleton key-token and derive one element of any key pair. Denotes key derivation function ANS-X9.63-KDF (refer to ANS X9.63-2011 section 5.6.3).
PASSTHRU Skip key derivation step and return raw Z material.
Note: This keyword is available only for Linux® on IBM® Z.
Hybrid Scheme Encrypted Value Key Type (one required for QSA-ECDH, if hybrid_key_identifier parameter is present)
IHKEYKYB The hybrid key identifier is an ML-KEM or CRYSTALS-Kyber private key token.
IHKEYAES The hybrid key identifier is an AES key token.
Transport key-type (one, optional; one required if output_KEK_key_identifier is a label)
OKEK-AES The output_KEK_key_identifier represents an AES key token.
OKEK-DES The output_KEK_key_identifier represents a DES key token.
Output key-type (one, optional; required if output_key_identifier is a label)
KEY-AES The outbound key-encrypting key represents an AES skeleton key token.
KEY-DES The outbound key-encrypting key represents a DES skeleton key token.
Key-wrapping method (one, optional). Keywords are valid for DES keys only and cannot be used with TR-31 tokens.
USECONFG This is the default. Specifies to wrap the key using the configuration setting for the default wrapping method. The default wrapping method configuration setting may be changed using the TKE. This keyword is ignored for AES keys.
WRAP-ECB Specifies to wrap the key using the legacy wrapping method. This keyword is ignored for AES keys.
WRAP-ENH Specifies to wrap the key using the enhanced wrapping method. Valid only for DES keys.
WRAPENH2 Specifies to wrap the key using the enhanced wrapping method and SHA-256. Valid only for TRIPLE or TRIPLE-O. This method requires CV bit 56 = B’1’ (ENH-ONLY). This is the default for TRIPLE and TRIPLE-O.
WRAPENH3 Specifies to wrap the key using the enhanced wrapping method with TDES-CMAC and the SHA-256 hashing algorithm. This keyword sets CV bit 56 = B’1’ (ENH-ONLY), which is required for the WRAPENH3 wrapping method.
Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when the default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to binary zeros, nor can it be used with TR-31 tokens.
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method once it has been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the control vector to B'1'.

This restricts translation to the legacy method. If the keyword is not specified, translation to the legacy method is allowed. This keyword is not valid if processing a zero CV data key.
Hash method (one, optional). Only valid with DERIV02 key agreement keyword.
SHA-224 Specifies the use of the SHA-224 method.
SHA-256 Specifies the use of the SHA-256 method. This is the default.
SHA-384 Specifies the use of the SHA-384 method.
SHA-512 Specifies the use of the SHA-512 method.
private_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes in the private_key_identifier variable.
private_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing an internal or external ECC key-token, or a key label identifying a PKA key-storage record for such a token. The ECC key-token will contain a public-private key pair. A clear private-key is only allowed when rule-array keyword DERIV01 is specified.

The ECC curve type and size must be the same as the type (Prime, Brainpool, or Koblitz) and size of the ECC key-token specified by the public_key_identifier parameter. The key-usage flag of the ECC key-token identified by the private_key_identifier parameter must permit key establishment (either KEY-MGMT or KM-ONLY).

For rule-array keyword DERIV02, the ECC key-token identified by the private_key_identifier parameter must contain an ECC key-derivation information section (section identifier X'23'). Refer to Table 8.
private_KEK_key_identifier_length
Direction: Input
Type: Integer

A pointer to an integer variable containing the number of bytes in the private_KEK_key_identifier variable. The maximum value is 9992. If the private_key_identifier contains an internal ECC token, this value must be a zero.

private_KEK_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing an internal CCA KEK key-token, or the key label of such a record in AES key storage. Or an internal TR-31 KEK key-token, or the key label of such a record in combined key storage with the following attributes:
  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: D or E

The KEK key-token must be present if the key token specified by the private_key_identifier contains an external encrypted ECC key-token.

public_key_identifier_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes in the public_key_identifier variable.

Note that even though this variable is not currently updated on output, it is reserved as an output field for future use.

public_key_identifier
Direction: Input/Output
Type: String
A pointer to a string variable containing an ECC key-token, or a key label identifying an AES key-storage record for such a key token. The ECC curve type and size must be the same as the type and size of the ECC key-token specified by the private_key_identifier parameter. If the public_key_identifier parameter identifies a key token containing a public-private key pair, no attempt to decrypt the private part is made.

Note that even though this variable is not currently updated on output, it is reserved as an output field for future use.

hybrid_key_identifier_length
Direction: Input
Type: Integer

If IHKEYKYB or IHKEYAES keywords are passed, this parameter contains the length of the hybrid_key_identifier in bytes. If neither IHKEYKYB nor IHKEYAES keywords are passed, this parameter must be zero.

If the hybrid_key_identifier contains a label, the value must be 64.

If the hybrid_key_identifier contains an ML-KEM or CRYSTALS-Kyber private token, the value must be between the actual length of the token and 8000.

Otherwise, the value must be between the actual length of the token and 9992.

hybrid_key_identifier
Direction: Input
Type: String
The hybrid_key_identifier key is used to decrypt the hybrid_ciphertext parameter.

When IHKEYKYB is passed, the hybrid_key_identifier parameter must contain an ML-KEM or CRYSTALS-Kyber private token or the label of such a private token. The hybrid_key_identifier parameter specifies the private key which must have the U-DATENC capability.

When IHKEYAES is passed, the hybrid_key_identifier parameter must contain a variable length CCA AES CIPHER token or the label of an AES token. Or it must contain a TR-31 CIPHER token or the label of such a key. The AES CIPHER key must have DECRYPT capability and the CBC mode of encryption.

For a TR-31 token this means that the following attributes are required:
  • TR-31 key usage: D0
  • Algorithm: A
  • TR-31 mode of key use: B or D

When neither IHKEYKYB nor IHKEYAES is passed, this parameter is ignored.

party_info_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes in the party_info variable. The value must be 8 - 64 for DERIV01. For DERIV02, the value must be 0 - 256.
party_info
Direction: Input/Output
Type: String
A pointer to a string variable. For DERIV01, the string contains the combined entity identifier information, including nonce. This information must contain data of both entities according to NIST SP800-56A Section 5.8. For DERIV02, the string contains optional shared data according to ANS X9.63-2011 section 5.6.3.
key_bit_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bits of key material to derive and place in the provided output key-token. The value must be 0 if the PASSTHRU rule-array keyword is specified. Otherwise, the value must be 64 - 2048.
initialization_vector_length
Direction: Input
Type: Integer

When IHKEYAES is passed, this parameter contains the length of the initialization_vector in bytes. For IHKEYAES, the value must be 16 bytes.

When IHKEYAES is not passed, the value must be zero.

initialization_vector
Direction: Input
Type: String
When IHKEYAES is passed, this parameter contains the initialization vector that is used to decrypt the content of the hybrid_ciphertext parameter. For IHKEYAES, the value must be 16 bytes long.

When IHKEYAES is not passed, this parameter is ignored.

hybrid_ciphertext_length
Direction: Input
Type: Integer

When IHKEYKYB or IHKEYAES are passed, this parameter contains the length of the hybrid_ciphertext parameter in bytes. For IHKEYAES, the value must be 32 bytes.

For IHKEYKYB, the value must be 1568 bytes for ML-KEM (1024) or CRYSTALS-Kyber (1024) Round 2 and 3, and the value must be 1088 bytes for ML-KEM (768) or CRYSTALS-Kyber (768) Round 2 and 3.

When neither IHKEYKYB nor IHKEYAES are passed, this parameter must be zero.

hybrid_ciphertext
Direction: Input
Type: String

When IHKEYKYB or IHKEYAES is passed, this parameter must contain an encrypted value that is deciphered with the hybrid_key_identifier and used in the Hybrid QSA Key Exchange Scheme described in Creating a hybrid post quantum key exchange scheme.

When neither IHKEYKYB nor IHKEYAES is passed, this parameter is ignored.

reserved_3_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes in the reserved_3 variable. The value must be 0.
reserved_3
Direction: Input/Output
Type: String
A pointer to a string variable that is currently not used.
reserved_4_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes in the reserved_4 variable. The value must be 0.
reserved_4
Direction: Input/Output
Type: String
A pointer to a string variable that is currently not used.
reserved_5_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes in the reserved_5 variable. The value must be 0.
reserved_5
Direction: Input/Output
Type: String
A pointer to a string variable that is currently not used.
output_KEK_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes in the output_KEK_key_identifier variable. The maximum value is 9992. The output_KEK_key_identifier_length> must be zero if output_key_identifier contains an internal token or if the PASSTHRU rule-array keyword was specified.
output_KEK_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing an internal KEK key-token, or a key label identifying a key-storage record for such a token. This parameter must identify a KEK key-token whenever the output_key_identifier specifies an external key-token. If the output_key_identifier specifies a DES key-token, then the output_KEK_key_identifier must identify a legacy CCA DES KEK, otherwise it must identify a variable-length symmetric CCA AES or TR-31 KEK key-token.

If this variable contains a key label, specify a transport key-type rule-array keyword (OKEK-DES or OKEK-AES) to identify which key-storage dataset contains the key token. If a transport key-type keyword is specified, it must match the type of key identified by this parameter, whether the key is in key storage or not.

If the output_KEK_key_identifier specifies a legacy DES KEK, then the key token must contain either an EXPORTER control vector with bit 21 on (EXPORT) or an IMPORTER control vector with bit 21 set to B'1' (IMPORT). The XLATE bit (bit 22) is not checked. Similarly, if the output_KEK_key_identifier identifies a variable-length symmetric AES KEK, then the KEK must have a key type of EXPORTER or IMPORTER. Key-usage field 1 of the KEK must be set so that the key can be used for EXPORT or IMPORT. In addition, key-usage field 4 must be set so that the key can wrap DERIVATION class keys.

If the output_KEK_key_identifier specifies a TR-31 DES KEK, then the key token must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: T
  • TR-31 mode of key use: D or E
Note: If the output_key_identifier is a TR-31 token, then the K1 TR-31 key usage is required.

If the output_KEK_key_identifier specifies a TR-31 AES KEK, then the key token must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: A
  • TR-31 mode of key use: D or E
Note: If the output_key_identifier is a TR-31 token, then the K1 TR-31 key usage is required.
output_key_identifier_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes in the output_key_identifier variable. On input, the output_key_identifier_length variable must be set to the total size of the buffer pointed to by the output key identifier parameter. On output, this variable contains the number of bytes of data returned by the verb in the output key identifier variable. The maximum allowed value is 9992 bytes.
output_key_identifier
Direction: Input/Output
Type: String
A pointer to a string variable. On input, it must contain an internal or an external skeleton key-token, or a key label identifying a key-storage record for such a token. The skeleton key-token must be one of the following:
DES (legacy DES key-token)
  • CIPHER, DECIPHER, or ENCIPHER
  • EXPORTER or IMPORTER
AES
  • DATA (legacy AES key-token)
  • CIPHER (variable-length symmetric key-token) with key-usage field set so that the key can be used for decryption, encryption, or both)
  • EXPORTER or IMPORTER (variable-length symmetric key-token)
TR-31 DES skeleton key token with the following attributes:
  • TR-31 key usage: K0, K1, or D0
  • Algorithm: D or T
  • TR-31 mode of key use: B, D, or E
Note: TR-31 mode of key use B is not usable with any K* Key Usage
TR-31 AES skeleton key token with the following attributes:
  • TR-31 key usage: K0, K1, or D0
  • Algorithm: A
  • TR-31 mode of key use: B, D, or E
Note: TR-31 mode of key use B is not usable with any K* Key Usage
On successful completion, this variable contains either:
  • An updated key-token that contains the generated symmetric key material, or the key label of the key-token that has been updated in key storage.
  • "Z" data (in the clear) if the PASSTHRU rule-array keyword was specified.

If this variable contains an external key-token on input, then the output_KEK_key_identifier is used to securely encrypt it for output. If this variable contains a key label, specify an output key-type rule-array keyword (KEY-DES or KEY-AES) to identify which key-storage dataset contains the key token. If an output key-type keyword is specified, it must match the type of key identified by this parameter, whether the key is in key storage or not.

If this variable identifies an external DES key-token, then the output_KEK_key_identifier must identify a DES KEK key-token. If this variable is present and identifies an external key-token other than a DES key-token, then the output_KEK_key_identifier must identify an AES KEK key-token.