Cipher Suites¶

A cipher suite bundles the key-exchange, signature, AEAD and hash algorithms of a handshake. The public header describes every suite as plain data (struct edhoc_cipher_suite) and resolves it to a crypto backend through a pair of getters keyed by enum edhoc_cipher_suite_id.

libedhoc ships production-ready cipher-suite implementations built on widely-used, audited libraries. Each suite is selected individually with its own Kconfig gate (CONFIG_LIBEDHOC_CIPHER_SUITE_<id>_ENABLE); a disabled suite is dropped from the build and its get_crypto getter returns NULL.

Supplied cipher-suite implementations¶
Suite	Algorithms (key exchange / signature / AEAD / hash)	Backend dependencies
0	X25519 / EdDSA / AES-CCM-16-64-128 / SHA-256	mbed TLS (PSA Crypto) + compact25519
2	P-256 / ES256 / AES-CCM-16-64-128 / SHA-256	mbed TLS (PSA Crypto)
4	X25519 / EdDSA / ChaCha20-Poly1305 / SHA-256	mbed TLS (PSA Crypto) + compact25519
24	P-384 / ES384 / A256GCM / SHA-384	mbed TLS (PSA Crypto)
-24 (draft)	ML-KEM-512 / ML-DSA-44 / AES-CCM-16-128-128 / SHAKE256	mbed TLS (PSA Crypto) + liboqs + XKCP

Suite -24 is work in progress, tracking the draft-ietf-lake-pqsuites specification; its code point is provisional.

Bring your own backend¶

The supplied suites are the batteries-included option, not a hard requirement. All cryptography is reached through the Cryptographic Interface vtable, so you can provide your own implementation for any suite — for example to drive a secure element or an accelerator that libedhoc knows nothing about — and bind it with edhoc_bind_crypto(). The supplied suites also serve as complete working examples for doing exactly that.

Public interface¶

Header file: include/edhoc/cipher_suite.h

group EDHOC cipher suite

Enums

enum edhoc_cipher_suite_id¶

Identifiers of the cipher suites shipped as reference implementations.

The enum tag differs from the edhoc_cipher_suite struct tag on purpose: struct and enum share the C tag namespace.

Values:

enumerator EDHOC_CIPHER_SUITE_0¶: X25519 / EdDSA / AES-CCM-16-64-128 / SHA-256.

enumerator EDHOC_CIPHER_SUITE_2¶: P-256 / ES256 / AES-CCM-16-64-128 / SHA-256.

enumerator EDHOC_CIPHER_SUITE_4¶: X25519 / EdDSA / ChaCha20-Poly1305 / SHA-256.

enumerator EDHOC_CIPHER_SUITE_24¶: P-384 / ES384 / A256GCM / SHA-384.

enumerator EDHOC_CIPHER_SUITE_PQC_1¶: ML-KEM-512 / ML-DSA-44 / AES-CCM-16-128-128 / SHAKE256.

struct edhoc_cipher_suite¶

#include <cipher_suite.h>

Cipher suite value and the byte lengths of its algorithms.

  Generalized for both NIKE (classical Diffie-Hellman) and KEM
  (e.g. ML-KEM) key exchange. For a classical suite the ephemeral leg
  is a NIKE-as-KEM shim, so the encapsulation key, the ciphertext and
  the static-DH key all share the elliptic-curve public-key length.

Public Members

int32_t value¶: Cipher suite IANA registry value.

bool supports_dh_nike¶: Whether the suite provides static Diffie-Hellman authentication (RFC 9528: 3.2, methods 1/2/3); method 0 (signatures only) needs no static DH and is always available.

size_t kem_encapsulation_key_length¶: Key exchange: encapsulation key (G_X) length in bytes.

size_t kem_ciphertext_length¶: Key exchange: ciphertext (G_Y) length in bytes.

size_t nike_key_length¶: Static-DH authentication key length in bytes; 0 if unsupported.

size_t sign_length¶: Signature length in bytes.

size_t aead_key_length¶: EDHOC AEAD algorithm key length in bytes.

size_t aead_tag_length¶: EDHOC AEAD algorithm tag length in bytes.

size_t aead_iv_length¶: EDHOC AEAD algorithm iv length in bytes.

size_t hash_length¶: EDHOC hash algorithm: hash length in bytes.

size_t mac_length¶: EDHOC MAC length in bytes.

group EDHOC cipher suite getters

Look up the parameters and reference crypto backend of a bundled suite by its edhoc_cipher_suite_id, to pass to edhoc_set_cipher_suites and edhoc_bind_crypto. A suite disabled in the build configuration is not compiled in, so both getters return NULL for it.

Functions

const struct edhoc_cipher_suite *edhoc_cipher_suite_get_params(enum edhoc_cipher_suite_id id)¶

Look up the algorithm lengths of a cipher suite.

Parameters:: id – Cipher suite identifier.
Returns:: Pointer valid for the lifetime of the program, or NULL if id is unknown or its suite is not compiled in.

const struct edhoc_crypto *edhoc_cipher_suite_get_crypto(enum edhoc_cipher_suite_id id)¶

Look up the reference cryptographic operations of a cipher suite.

Parameters:: id – Cipher suite identifier.
Returns:: Pointer valid for the lifetime of the program, or NULL if id is unknown or its suite is not compiled in.

Note

The suite implementations under library/cipher_suites/ are internal: their headers are not installed and are not part of the public API. Reach a suite through edhoc_cipher_suite_get_crypto(), or read the sources as a starting point when writing your own backend.