Concepts at a Glance¶

This page sketches the EDHOC mental model used throughout the libedhoc documentation. Every term marked in italics is defined in Glossary.

Security properties¶

A successful EDHOC handshake provides mutual authentication, forward secrecy and identity protection of the responder credential against active attackers (and of the initiator credential against passive attackers). See RFC 9528 §9 for the full security analysis.

Roles¶

An EDHOC handshake involves two peers, the Initiator (I) and the Responder (R). RFC 9528 Appendix A.2 defines a forward and a reverse message flow over CoAP; libedhoc is transport-agnostic and supports both. The library itself is role-agnostic: the same context type is used on both sides, and the role is implied by which compose / process calls you make.

Methods and cipher suites¶

A handshake is parameterised by:

an authentication method (0 – 3) that selects whether each peer authenticates with a signature key or a static DH key;
a cipher suite that bundles an AEAD, a hash, an ECDH group and a signature algorithm. libedhoc supports suites 0 (X25519 / EdDSA) and 2 (P-256 / ES256).

Authentication methods¶
Value	Initiator key	Responder key
0	Signature key	Signature key
1	Signature key	Static DH key
2	Static DH key	Signature key
3	Static DH key	Static DH key

Credentials¶

Each peer presents an authentication credential — CRED_I or CRED_R — identified on the wire by one of the COSE credential identifications: kid, x5chain or x5t. libedhoc does not embed credential storage or validation; the application supplies a credentials callback and is free to consult a CRL or any other policy.

Key schedule and exports¶

The handshake yields a chain of PRK values culminating in PRK_out. Application keys are derived from PRK_out through the PRK exporter. The most common use of the exporter is to bootstrap an OSCORE security context — see Exporters.

Wire format and transport¶

EDHOC messages are CBOR sequences, normally transported over CoAP. libedhoc itself is transport-agnostic; the message buffers it returns can be handed to any CoAP stack. The diagram on Protocol Flow shows the canonical CoAP exchange.

Feature → reference matrix¶

Feature / module	Concept page	API page
Context lifecycle & setup	This page	EDHOC Context
Message composition / processing	Protocol Flow	EDHOC Messages
OSCORE export / key update	This page	Exporters
Authentication credentials	This page	Authentication Credentials
Cryptographic keys & operations	This page	Cryptographic Interface
External Authorization Data (EAD)	This page	External Authorization Data
Cipher-suite helpers	This page	Helpers, Macros and Utilities