EC Diffie-Hellman (CSNDEDH)

Edit online

Use the EC Diffie-Hellman verb to create symmetric key material from various input sources.

With the EC Diffie-Hellman verb, you can create:

  • symmetric key material from a pair of elliptic curve cryptography (ECC) keys using Elliptic Curve Diffie-Hellman (ECDH) protocol and the static unified model key agreement scheme.
  • "Z" - The "secret" material output from Elliptic Curve Diffie-Hellman process.
  • symmetric key material from a hybrid quantum safe key exchange scheme involving a CRYSTALS-Kyber encrypted value or an AES encrypted value and a pair of ECC keys using the Elliptic Curve Diffie-Hellman protocol.

For more information, see EC Diffie-Hellman key agreement models or Creating a hybrid quantum safe key exchange scheme.

ECDH is a key-agreement protocol that allows two parties, each having an elliptic curve public-private key pair, to establish a shared secret over an insecure channel. This shared secret is used to derive another symmetric key. The ECDH protocol is a variant of the Diffie-Hellman protocol using elliptic curve cryptography. ECDH derives a shared secret value from a secret key owned by an Entity A and a public key owned by an Entity B, when the keys share the same elliptic curve domain parameters. Entity A can be either the initiator of a key-agreement transaction, or the responder in a scheme. If two entities both correctly perform the same operations with corresponding keys as inputs, the same shared secret value is produced.

Both parties must create an ECC public-private key pair. See PKA Key Token Build (CSNDPKB) and PKA Key Generate (CSNDPKG). A key can be internal or external, as well as encrypted or in the clear. Both keys must have the same elliptic curve domain parameters (curve type and key size):
  • Brainpool (key size 160, 192, 224, 256, 320, 384, or 512)
  • Prime (key size 192, 224, 256, 384, or 521)
  • Edwards (key size 255, 448)
  • Koblitz (key size 256)

In addition to having the same elliptic curve domain parameters, the keys must have their key-usage field set to permit key establishment (either KEY-MGMT or KM-ONLY). See ECC key token.

To use this verb, specify the following:
  • One to six rule-array keywords:
    • A required key-agreement keyword
    • An optional transport key-type (required if output_KEK_key_identifier is a label) that identifies which key-storage dataset contains the output KEK key-token
    • An optional output key-type (required if output_key_identifier is a label) that identifies which key-storage dataset contains the output key-token
    • When the output is a DES key-token, an optional key-wrapping method and an optional translation control keyword
    • An optional hash type for rule-array keyword DERIV02.
  • The internal or external ECC key-token containing the private key (public-private key pair).

    If the private key is in an external key-token and is not in the clear, specify the internal KEK that was used to wrap the private key. Otherwise, specify a private KEK key-length of 0.

  • An internal or external ECC key-token containing the public key (public key only or public-private key pair) of the other party.

    If the public key is in a key token that contains a public-private key pair, only the public-key portion is used. No attempt is made to decrypt the private key.

  • Party information data in parameter party_info:
    • When rule-array keyword DERIV01 is given: From 8 - 64 bytes, specify the party information data of the initiator and the responder entities, according to NIST SP800-56A Section 5.8
    • When rule-array keyword DERIV02 is given: From 0 - 256 bytes, specify party information data, according to section 5.6.3 of ANS X9.63-2011
  • The number of bits of key material, from 64 - 256, to derive and place in the provided output key-token
  • The length in bytes of the buffer for the output key-identifier
  • An internal or external skeleton key-token to be used as input for the output key-token

    The skeleton key-token must be an AES key or a DES key, as shown in the following table:

    Table 1. CSNDEDH skeleton key-tokens
    Algorithm Token version number Key type (see note)
    AES X'04' (legacy fixed-length symmetric key-token) DATA
    X'05' (variable-length symmetric key-token)
    • CIPHER

      Both parties can provide any combination of encryption or decryption for key-usage field.

    • EXPORTER or IMPORTER

      Both parties can provide any combination of EXPORTER or IMPORTER.
    DES X'00', X'01', X'03' (legacy fixed-length symmetric key-token)
    • CIPHER, DECIPHER, ENCIPHER

      Both parties can provide any combination of Encipher or Decipher key-usage bits in the control vector.

    • CIPHER XI, CIPHERXL, CIPHERXO

      Both parties can provide any combination of Encipher or Decipher key-usage bits in the control vector.

    • EXPORTER or IMPORTER

      Both parties can provide any combination of EXPORT or IMPORT key-usage bits in the control vector.
    Note:
    1. Except as otherwise noted, both parties must provide identical skeleton key tokens for the output key in order to derive identical keys. For legacy skeletons, control vector parity bits are not used in the key derivation process.
    2. Control vector bits and key-usage fields are not used in the key derivation process when rule-array keyword DERIV02 is specified.

    If the skeleton key-token is an external key-token, specify the internal KEK to be used to wrap the output key-token. Otherwise, specify an output KEK length of 0.

    If the output_key_identifier specifies a DES key-token, then the output_KEK_key_token must identify a legacy DES KEK. Otherwise it must identify a variable-length symmetric AES KEK key-token.

Table 2 provides the format for the concatenation string from which the key is derived when DERIV01 is specified in the rule-array.
Table 2. CSNDEDH concatenation string format for DERIV01
Offset (bytes) Length (bytes) Value Comments
0 4 Initialized to X'00000001' Counter (four-byte unsigned integer)
4 xx Z A shared secret bit string or octet string
4 + xx tt

See the note in next row.

 T

Plaintext decrypted from the hybrid_ciphertext parameter.

 Plaintext used for the Hybrid QSA Key Exchange Scheme (see also Creating a hybrid quantum safe key exchange scheme).
Note:
  • tt = hybrid_ciphertext_length for QSA-ECDH
  • tt = 0 for all other cases, T is not included in the concatenation string
4 + xx + tt 1
Value
Meaning
X'03'
DES
X'04'
AES
 Algorithm identifier
5 + xx + tt 1 Passed party_info_length variable Party information length passed by caller, converted to a one-byte unsigned integer
6 + xx + tt Value of party_info_length parameter String identified by party_info parameter Party information passed by the caller
6 + xx + tt + party_info_length 2 Supplied public information length, zz Two-byte unsigned integer specifying length of supplied public information
8 + xx + tt + party_info_length zz Supplied public information Token data extracted from the skeleton key token identified by the output_key_identifier parameter (refer to Table 3.
Note: All integers are in big-endian format.
Table 3. DERIV01 supplied public information
Algorithm Key-token version Key type Supplied public information length, zz (bytes) Supplied public information
AES X'04' (legacy fixed-length symmetric key-token) DATA 8 Control vector (CV) from key token beginning at offset 48 for zz bytes. If flag byte indicates no CV present, information valued to binary zeros.
X'05' (variable-length symmetric key-token) CIPHER 1 + (key usage fields count * 2) + 1 + (key management fields count * 2) Key usage and key management information from key token beginning at offset 44 for zz bytes, with ENCRYPT and DECRYPT bits (B'11xx xxxx' ) of KUF 1 high-order byte masked off to maintain compatibility between keys with different key usage for these bits
EXPORTER or IMPORTER 1 + (key usage fields count * 2) + 1 + (key management fields count * 2) Key usage and key management information from key token beginning at offset 44 for zz bytes, with no bits masked off
DES X'00', X'01', X'03' (legacy fixed-length symmetric key token) CIPHER, DECIPHER, or ENCIPHER 8 for single-length keys, 16 for double-length keys CV from key token beginning at offset 32 for zz bytes, with CV bits 18, 19, and 23 (X'xx11 xxx1') masked off (in both CV halves if double-length key) to maintain compatibility between keys with different Encipher, Decipher, and parity bit values.
EXPORTER or IMPORTER 16 CV from key token beginning at offset 32 for zz bytes, with CV bits 9, 14, and 15 (X'x1xx xx11') masked off (in both CV halves) to maintain compatibility between different KEK key types and parity bit values.
Table 4 provides the format for the concatenation string from which the key is derived when DERIV02 is specified in the rule-array:
Table 4. CSNDEDH concatenation string format for DERIV02
Offset (bytes) Length (bytes) Value Comments
0 xx Z A shared secret bit string or octet string
xx tt

See the note in next row.

 T

Plaintext decrypted from the hybrid_ciphertext parameter.

 32 byte plaintext decrypted from the hybrid_ciphertext parameter. The length is not an explicit field in the concatenation string.
Note:
  • tt = hybrid_ciphertext_length for QSA-ECDH
  • tt = 0 for all other cases, T is not included in the concatenation string
xx + tt 4 Initialized to X'00000001' Counter (four-byte unsigned integer)
xx + tt + 4 yy String identified by the party_info parameter Party information passed by the caller. The length is not an explicit field in the concatenation string.
Note: All integers are in big-endian format.

The output from this verb can be one of the following formats:

  • Internal CCA token (DES or AES): AES keys are in the variable-length symmetric key token format. DES keys are in the DES external key token format.
  • External CCA token (DES or AES): AES keys are in the variable-length symmetric key token format. DES keys are in the DES external key token format.
  • "Z" – The "secret" material output from Elliptic Curve Diffie-Hellman process.
  • Symmetric key material from a quantum safe hybrid key exchange scheme involving a CRYSTALS-Kyber encrypted value or an AES encrypted value and a pair of ECC keys using the Elliptic Curve Diffie-Hellman protocol. The scheme is outlined in Creating a hybrid quantum safe key exchange scheme, along with the role of CSNDEDH in that scheme.

The PASSTHRU service is provided as a convenience to users who wish to implement their own key completion process in host application software. While the "Z" derivation process is not reversible (the ECC keys cannot be discovered by obtaining "Z") there is a level of security compromise associated with returning the clear "Z" to the application. Future derivations for CCA key tokens using ECC keys previously used in PASSTHRU must be considered to have lower security, and using the same ECC keys for PASSTHRU as for DERIV01 is strongly discouraged. It should also be noted that since "Z" is the secret material, returning it in the clear to the host application reduces security level of the "Z" from the HSM level to the host application level, and keys made from this material should not be regarded as having any HSM protection.

For more information, see EC Diffie-Hellman key agreement models.