EDHOC Context¶

The EDHOC context is the central state object of libedhoc. It is initialised, configured and bound to the application’s callbacks, driven through the message-exchange phase, and finally torn down. See the lifecycle section of API Reference for the strict call order.

The context is opaque and forward-declared, so it must be allocated through edhoc_context_size() — on the stack (a VLA) or on the heap.

Header file: include/edhoc/edhoc.h

Lifecycle¶

group EDHOC API context lifecycle

The context is opaque: size it with edhoc_context_size, initialise it with edhoc_context_init, and release it with edhoc_context_deinit.

Functions

int edhoc_context_init(struct edhoc_context *edhoc_context)¶

Initialize EDHOC context.

Parameters:: edhoc_context – [inout] EDHOC context.
Return values:: EDHOC_SUCCESS – Success.
Returns:: Negative error code on failure (EDHOC error codes).

size_t edhoc_context_size(void)¶

Size in bytes of an EDHOC context for this build.

The size depends on the build-time configuration, so it is a run-time value. Allocate at least this many bytes (on the stack or heap) for the edhoc_context passed to edhoc_context_init.

Returns:: Size in bytes of edhoc_context.

int edhoc_context_deinit(struct edhoc_context *edhoc_context)¶

Deinitialize EDHOC context.

Parameters:: edhoc_context – [inout] EDHOC context.
Return values:: EDHOC_SUCCESS – Success.
Returns:: Negative error code on failure (EDHOC error codes).

Library version¶

group EDHOC API version

Defines

EDHOC_API_VERSION_MAJOR¶: Major version of the EDHOC API.

EDHOC_API_VERSION_MINOR¶: Minor version of the EDHOC API.

EDHOC_API_VERSION_PATCH¶: Patch version of the EDHOC API.

Setters¶

The setters configure a freshly-initialised context with the local authentication method(s), cipher suite(s) and the local connection identifier. They may be called in any order, and must all run before the message-exchange phase.

group EDHOC API setters

After edhoc_context_init, a context must be fully configured before the message-processing API will run. A message compose or process call made before every mandatory input is present returns EDHOC_ERROR_BAD_STATE.

Mandatory inputs:

method(s)
cipher suite(s)
connection identifier
crypto interface
credentials interface
platform interface

Optional inputs:

user context
external authorization data (EAD) interface

Functions

int edhoc_set_methods(struct edhoc_context *edhoc_context, const enum edhoc_method *method, size_t method_count)¶

Set EDHOC method(s) (mandatory).

Configures the authentication method(s) the context may use (RFC 9528: 3.2). At least one and at most CONFIG_LIBEDHOC_MAX_NR_OF_METHODS entries, each a value of edhoc_method. The role selects how the list is used:

the Initiator uses the first method when composing message 1;
the Responder accepts message 1 if its method matches any provided entry.

Parameters:

edhoc_context – [inout] EDHOC context.
method – [in] EDHOC method.
method_count – Number of entries in the method array.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_set_cipher_suites(struct edhoc_context *edhoc_context, const struct edhoc_cipher_suite *cipher_suite, size_t cipher_suite_count)¶

Set EDHOC cipher suite(s) (mandatory).

Configures the cipher suite(s) the context supports (RFC 9528: 3.6). At least one and at most CONFIG_LIBEDHOC_MAX_NR_OF_CIPHER_SUITES entries. The Initiator offers them in SUITES_I and the Responder checks the selected suite against those it supports (RFC 9528: 5.2.1).

Parameters:

edhoc_context – [inout] EDHOC context.
cipher_suite – [in] EDHOC cipher suites.
cipher_suite_count – Number of entries in the cipher_suite array.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_set_connection_id(struct edhoc_context *edhoc_context, const struct edhoc_buffer *connection_id)¶

Set EDHOC connection identifier (mandatory).

Sets the connection identifier the peer uses to reference this endpoint in the session: C_I for the Initiator (sent in message 1) or C_R for the Responder (sent in message 2) (RFC 9528: 3.3).

A connection identifier is a byte string, at most CONFIG_LIBEDHOC_MAX_LEN_OF_CONN_ID bytes long; the empty one is legal. The library copies it and applies the compact CBOR integer encoding of RFC 9528: 3.3.2 on its own.

Note

C_I and C_R are chosen independently, but an application deriving an OSCORE security context must not end up with equal ones (RFC 9528: 3.3.3); see edhoc_export_oscore_context().

Parameters:

edhoc_context – [inout] EDHOC context.
connection_id – [in] EDHOC connection identifier.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_set_user_context(struct edhoc_context *edhoc_context, void *user_context)¶

Set user context (optional).

The pointer is stored as it is and handed back to every application callback. Passing NULL clears a previously set context.

Parameters:

edhoc_context – [inout] EDHOC context.
user_context – [in] User context.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_bind_crypto(struct edhoc_context *edhoc_context, const struct edhoc_crypto *crypto)¶

Bind the cryptographic operations interface (mandatory).

Provides the crypto primitives the library uses: key exchange, AEAD, hash, signature/MAC and key derivation. Every entry of crypto is mandatory.

Parameters:

edhoc_context – [inout] EDHOC context.
crypto – [in] EDHOC cryptographic operations structure with callbacks.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_bind_credentials(struct edhoc_context *edhoc_context, const struct edhoc_credentials *credentials)¶

Bind the authentication credentials interface (mandatory).

Provides the select_local / authenticate_peer callbacks the library uses to obtain the local authentication credential and to authenticate the peer’s (RFC 9528: 3.5). Both are mandatory.

Parameters:

edhoc_context – [inout] EDHOC context.
credentials – [in] EDHOC authentication credentials structure with callbacks.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_bind_platform(struct edhoc_context *edhoc_context, const struct edhoc_platform *platform)¶

Bind the platform services interface (mandatory).

Provides the platform services the library uses. Every entry of platform is mandatory.

Parameters:

edhoc_context – [inout] EDHOC context.
platform – [in] EDHOC platform structure with callbacks.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_bind_ead(struct edhoc_context *edhoc_context, const struct edhoc_ead *ead)¶

Bind the external authorization data (EAD) interface (optional).

Provides the compose/process callbacks for the EAD items carried in the EDHOC messages (RFC 9528: 3.8). Optional; bind it only if the application sends or receives EAD, and then both callbacks are mandatory.

Parameters:

edhoc_context – [inout] EDHOC context.
ead – [in] EDHOC EAD structure with callbacks.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).