EDHOC Context¶

The EDHOC context is the central state object of the library. A context is initialised, configured with methods and cipher suites, bound to a set of callbacks (keys, crypto, credentials, optionally EAD), driven through the message-exchange phase, and finally torn down. See the lifecycle section of API Reference for the strict call order.

Header file: include/edhoc_context.h

Context object¶

group EDHOC context

Defines

EDHOC_SM_RECEVIED_M4¶

Deprecated:: Use EDHOC_SM_RECEIVED_M4 instead.

Enums

enum edhoc_role¶

RFC 9528: 2. EDHOC Outline.

Values:

enumerator EDHOC_INITIATOR¶: EDHOC role - initiator.

enumerator EDHOC_RESPONDER¶: EDHOC role - responder.

enum edhoc_state_machine¶

RFC 9528: Appendix I. Example Protocol State Machine.

Values:

enumerator EDHOC_SM_START¶: State machine - start.

enumerator EDHOC_SM_ABORTED¶: State machine - aborted.

enumerator EDHOC_SM_RECEIVED_M1¶: State machine - received message 1.

enumerator EDHOC_SM_VERIFIED_M1¶: State machine - verified message 1.

enumerator EDHOC_SM_WAIT_M2¶: State machine - waiting for message 2.

enumerator EDHOC_SM_RECEIVED_M2¶: State machine - received message 2.

enumerator EDHOC_SM_VERIFIED_M2¶: State machine - verified message 2.

enumerator EDHOC_SM_WAIT_M3¶: State machine - waiting for message 3.

enumerator EDHOC_SM_RECEIVED_M3¶: State machine - received message 3.

enumerator EDHOC_SM_RECEIVED_M4¶: State machine - received message 4.

enumerator EDHOC_SM_COMPLETED¶: State machine - completed.

enumerator EDHOC_SM_PERSISTED¶: State machine - persisted.

enum edhoc_method¶

RFC 9528: 3.2. Method.

Values:

enumerator EDHOC_METHOD_0¶: Initiator signature Key to responder signature Key.

enumerator EDHOC_METHOD_1¶: Initiator signature Key to responder static DH Key.

enumerator EDHOC_METHOD_2¶: Initiator static DH Key to responder signature Key.

enumerator EDHOC_METHOD_3¶: Initiator static DH Key to responder static DH Key.

enumerator EDHOC_METHOD_MAX¶: Sanity check maximum.

enum edhoc_th_state¶

EDHOC transcript hashes states.

Values:

enumerator EDHOC_TH_STATE_INVALID¶: Transcript hash invalid.

enumerator EDHOC_TH_STATE_1¶: Transcript hash 1.

enumerator EDHOC_TH_STATE_2¶: Transcript hash 2.

enumerator EDHOC_TH_STATE_3¶: Transcript hash 3.

enumerator EDHOC_TH_STATE_4¶: Transcript hash 4.

enum edhoc_prk_state¶

EDHOC pseudorandom keys states.

Values:

enumerator EDHOC_PRK_STATE_INVALID¶: Pseudorandom key invalid.

enumerator EDHOC_PRK_STATE_2E¶: Pseudorandom key RFC 9528: 4.1.1.1. PRK_2e.

enumerator EDHOC_PRK_STATE_3E2M¶: Pseudorandom key RFC 9528: 4.1.1.2. PRK_3e2m.

enumerator EDHOC_PRK_STATE_4E3M¶: Pseudorandom key RFC 9528: 4.1.1.3. PRK_4e3m.

enumerator EDHOC_PRK_STATE_OUT¶: Pseudorandom key RFC 9528: 4.1.3. PRK_out.

enumerator EDHOC_PRK_STATE_EXPORTER¶: Pseudorandom key RFC 9528: 4.2.1. EDHOC_Exporter.

enum edhoc_connection_id_type¶

EDHOC connection identifier encoding type.

Values:

enumerator EDHOC_CID_TYPE_ONE_BYTE_INTEGER¶: Encode connection identifier as CBOR integer.

enumerator EDHOC_CID_TYPE_BYTE_STRING¶: Encode connection identifier as CBOR byte string.

enum edhoc_error_code¶

EDHOC error code. RFC 9528: 6. Error Handling.

Values:

enumerator EDHOC_ERROR_CODE_SUCCESS¶: RFC 9528: 6.1. Success.

enumerator EDHOC_ERROR_CODE_UNSPECIFIED_ERROR¶: RFC 9528: 6.2. Unspecified Error.

enumerator EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE¶: RFC 9528: 6.3. Wrong Selected Cipher Suite.

enumerator EDHOC_ERROR_CODE_UNKNOWN_CREDENTIAL_REFERENCED¶: RFC 9528: 6.4. Unknown Credential Referenced.

struct edhoc_connection_id¶

#include <edhoc_context.h>

RFC 9528: 3.3.2. Representation of Byte String Identifiers.

Public Members

enum edhoc_connection_id_type encode_type¶

Encoding type of connection identifier.

It must follow representation of byte string identifiers described in RFC 9528: 3.3.2.

int8_t int_value¶: Connection identifier as CBOR integer.

uint8_t bstr_value[CONFIG_LIBEDHOC_MAX_LEN_OF_CONN_ID + 1]¶: Connection identifier as CBOR byte string buffer.

size_t bstr_length¶: Size of the bstr_value buffer in bytes.

struct edhoc_error_info¶

#include <edhoc_context.h>

EDHOC error information. RFC 9528: 6. Error Handling.

Public Members

char *text_string¶: Pointer used only for error code: EDHOC_ERROR_CODE_UNSPECIFIED_ERROR.

int32_t *cipher_suites¶: Pointer used only for error code: EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE.

size_t total_entries¶: Total number of entries from: text_string or cipher_suites.

size_t written_entries¶: Number of written entries to: text_string or cipher_suites.

struct edhoc_context¶

#include <edhoc_context.h>

EDHOC context.

Public Members

enum edhoc_method chosen_method¶: EDHOC chosen method.

enum edhoc_method method[EDHOC_METHOD_MAX]¶: EDHOC supported methods.

size_t method_len¶: Length of the method buffer.

size_t chosen_csuite_idx¶: EDHOC cipher suite chosen index.

struct edhoc_cipher_suite csuite[CONFIG_LIBEDHOC_MAX_NR_OF_CIPHER_SUITES]¶: EDHOC cipher suite buffer.

size_t csuite_len¶: Length of the csuite buffer.

struct edhoc_cipher_suite peer_csuite[CONFIG_LIBEDHOC_MAX_NR_OF_CIPHER_SUITES]¶: EDHOC peer cipher suite buffer.

size_t peer_csuite_len¶: Length of the peer_csuite buffer.

struct edhoc_connection_id cid¶: EDHOC connection identifier.

struct edhoc_connection_id peer_cid¶: EDHOC peer connection identifier.

uint8_t dh_pub_key[CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY]¶: EDHOC ephemeral Diffie-Hellman public key.

size_t dh_pub_key_len¶: Size of the dh_pub_key buffer in bytes.

uint8_t dh_priv_key[CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY]¶: EDHOC ephemeral Diffie-Hellman private key.

size_t dh_priv_key_len¶: Size of the dh_priv_key buffer in bytes.

uint8_t dh_peer_pub_key[CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY]¶: EDHOC ephemeral Diffie-Hellman peer public key.

size_t dh_peer_pub_key_len¶: Size of the dh_peer_pub_key buffer in bytes.

uint8_t dh_secret[CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY]¶: EDHOC ephemeral Diffie-Hellman key agreement.

size_t dh_secret_len¶: Size of the dh_secret buffer in bytes.

bool is_init¶: Is context initialized?

bool is_oscore_export_allowed¶: Is OSCORE security session export allowed?

enum edhoc_state_machine status¶: EDHOC context state machine.

enum edhoc_message message¶: Current processing EDHOC message.

enum edhoc_role role¶: EDHOC role.

enum edhoc_th_state th_state¶: EDHOC context transcript hash state.

uint8_t th[CONFIG_LIBEDHOC_MAX_LEN_OF_MAC]¶: EDHOC context transcript hash buffer.

size_t th_len¶: Size of the th buffer in bytes.

enum edhoc_prk_state prk_state¶: EDHOC context pseudorandom key state.

uint8_t prk[CONFIG_LIBEDHOC_MAX_LEN_OF_MAC]¶: EDHOC context pseudorandom key buffer.

size_t prk_len¶: Size of the prk buffer in bytes.

struct edhoc_ead ead¶: EDHOC interface for external authorization data.

struct edhoc_keys keys¶: EDHOC interface for cryptographic key operations.

struct edhoc_crypto crypto¶: EDHOC interface for cryptographic function operations.

struct edhoc_credentials cred¶: EDHOC interface for authentication credentials.

struct edhoc_ead_token ead_token[CONFIG_LIBEDHOC_MAX_NR_OF_EAD_TOKENS + 1]¶: EDHOC EAD tokens buffer.

size_t nr_of_ead_tokens¶: Length of the ead_token buffer.

void *user_ctx¶: User context.

enum edhoc_error_code error_code¶: EDHOC error code.

Library version¶

Header file: include/edhoc.h

group EDHOC API version

Defines

EDHOC_API_VERSION_MAJOR¶: The major version of this implementation of the EDHOC API.

EDHOC_API_VERSION_MINOR¶: The minor version of this implementation 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, but must all run before any binder or message-exchange call.

Header file: include/edhoc.h

group EDHOC API setters

Functions

int edhoc_context_init(struct edhoc_context *edhoc_context)¶

Initialize EDHOC context.

Parameters:

edhoc_context – EDHOC context.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Input parameter is invalid.

int edhoc_context_deinit(struct edhoc_context *edhoc_context)¶

Deinitialize EDHOC context.

Parameters:

edhoc_context – EDHOC context.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Input parameter is invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

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

Set EDHOC methods.

According to RFC 9528: 3.2. Method. At least one method must be set, but no more than EDHOC_METHOD_MAX.

Behavior depends on the role:

Initiator always uses the first value (method[0]) when composing message 1.
Responder iterates over all methods to find a match when processing message 1.

Parameters:

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

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

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

Set EDHOC cipher suites.

Parameters:

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

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

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

Set EDHOC connection identifier.

Parameters:

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

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

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

Set user context.

Parameters:

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

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

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

Bind EDHOC external authorization data (EAD) callbacks.

Parameters:

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

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

int edhoc_bind_keys(struct edhoc_context *edhoc_context, const struct edhoc_keys *keys)¶

Bind EDHOC cryptographic keys callbacks.

Parameters:

edhoc_context – EDHOC context.
keys – [in] EDHOC cryptographic keys structure with callbacks.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

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

Bind EDHOC cryptographic operations callbacks.

Parameters:

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

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

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

Bind EDHOC authentication credentials callbacks.

Parameters:

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

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.