Security & Key Handling

libedhoc is built so that raw secret key material never sits in library memory. This page explains where key material lives, how the crypto interface models both classical and post-quantum key exchange, and how transient secrets are wiped.

Handle-only key material

Every private key and derived secret — the long-lived authentication key, the session’s ephemeral key, the shared secret and the PRK chain — is an opaque handle into the crypto backend’s key store, never a raw byte buffer inside the context. Depending on the backend, the key store may be:

  • volatile key slots in a software crypto library;

  • the secure world of a TrustZone / TF-M system;

  • dedicated slots on a secure element.

The guarantee is confinement: a secret is born inside a backend call (key generation, key agreement, extract, expand), is referenced only by its handle, and is never serialised. A leaked context therefore reveals no key material.

What is held by reference, and what is raw

Material

Form

Rationale

Ephemeral and static keys, shared secrets, the PRK chain, exported keys

handle

Secret — stays in the key store.

Peer public keys (G_X / G_Y), transcript hashes, info

raw

Public protocol inputs.

Keystream, IV / nonce, MAC, exporter bytes

raw

One-shot outputs; the keystream and any decrypted plaintext are zeroized immediately after use.

The library computes no cryptography itself: it sequences backend calls and assembles the public inputs. See Cryptographic Interface.

Ephemeral key exchange: one KEM-shaped interface

The crypto interface models the ephemeral exchange as a KEM (generate_key_pair / encapsulate / decapsulate):

  • Post-quantum — ML-KEM (and other KEMs) drop in directly.

  • Classical — ECDH plugs in as a thin shim that exposes bare ECDH through the KEM calls. It is deliberately not DHKEM (RFC 9180), so the bytes on the wire stay exactly those of RFC 9528 (G_X = encapsulation key, G_Y = ciphertext) and classical interop is preserved.

Static Diffie-Hellman authentication (methods 1/2/3) uses a separate key_agreement entry, available only on NIKE suites.

Memory zeroization

Transient raw secrets — the keystream, decrypted plaintext, IVs and MACs — are wiped with a compiler-non-elidable zeroize the moment they are no longer needed, including on error paths. The application supplies zeroize through the mandatory platform binding (see Platform Services).