EDHOC API & Interfaces

Lifecycle

The EDHOC context must be used following a strict call order. Deviating from this sequence results in EDHOC_ERROR_BAD_STATE.

1. Initialization

struct edhoc_context ctx;
edhoc_context_init(&ctx);

2. Configuration (order within this group does not matter)

edhoc_set_methods(&ctx, methods, methods_len);
edhoc_set_cipher_suites(&ctx, suites, suites_len);
edhoc_set_connection_id(&ctx, &conn_id);
edhoc_set_user_context(&ctx, user_ctx);

3. Bind callbacks (order within this group does not matter)

edhoc_bind_keys(&ctx, &keys);
edhoc_bind_crypto(&ctx, &crypto);
edhoc_bind_credentials(&ctx, &cred);
edhoc_bind_ead(&ctx, &ead);          /* optional */

4. Message exchange (strict order; role determines which side composes or processes)

/* Initiator composes, Responder processes: */
edhoc_message_1_compose / edhoc_message_1_process
edhoc_message_2_compose / edhoc_message_2_process
edhoc_message_3_compose / edhoc_message_3_process
edhoc_message_4_compose / edhoc_message_4_process  /* optional */

5. Export and teardown

edhoc_export_oscore_session(&ctx, ...);
/* Optionally perform key update and re-export: */
edhoc_export_key_update(&ctx, entropy, entropy_len);
edhoc_export_oscore_session(&ctx, ...);
edhoc_context_deinit(&ctx);

Error handling

All API functions return EDHOC_SUCCESS (0) on success or a negative error code on failure. Error codes are defined in include/edhoc_values.h.

After a message processing function fails, use edhoc_error_get_code() to retrieve the EDHOC-level error code (RFC 9528: Section 6):

int ret = edhoc_message_1_process(&ctx, msg1, msg1_len);
if (ret != EDHOC_SUCCESS) {
    enum edhoc_error_code err;
    edhoc_error_get_code(&ctx, &err);

    if (err == EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE) {
        /* Retrieve own and peer cipher suites for renegotiation: */
        edhoc_error_get_cipher_suites(&ctx, own, own_size, &own_len,
                                      peer, peer_size, &peer_len);
    }
}

To send an EDHOC error message to the peer:

struct edhoc_error_info info = { .text_string = "details", .total_entries = 7 };
edhoc_message_error_compose(buf, buf_size, &buf_len,
                            EDHOC_ERROR_CODE_UNSPECIFIED_ERROR, &info);

Main API

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.

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.

group EDHOC messages API

Functions

int edhoc_message_1_compose(struct edhoc_context *edhoc_context, uint8_t *message_1, size_t message_1_size, size_t *message_1_length)

Compose EDHOC message 1.

Parameters:

edhoc_context – EDHOC context.
message_1 – [out] Buffer where the generated message 1 is to be written.
message_1_size – Size of the message_1 buffer in bytes.
message_1_length – [out] On success, the number of bytes that make up the message 1.

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.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman operation failed.
EDHOC_ERROR_EAD_COMPOSE_FAILURE – EAD compose callback failed.

int edhoc_message_1_process(struct edhoc_context *edhoc_context, const uint8_t *message_1, size_t message_1_length)

Process EDHOC message 1.

Parameters:

edhoc_context – EDHOC context.
message_1 – [in] Buffer containing the message 1.
message_1_length – Length of the message_1 in bytes.

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.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_MSG_1_PROCESS_FAILURE – EDHOC message processing failed.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_EAD_PROCESS_FAILURE – EAD process callback failed.

int edhoc_message_2_compose(struct edhoc_context *edhoc_context, uint8_t *message_2, size_t message_2_size, size_t *message_2_length)

Compose EDHOC message 2.

Parameters:

edhoc_context – EDHOC context.
message_2 – [out] Buffer where the generated message 2 is to be written.
message_2_size – Size of the message_2 buffer in bytes.
message_2_length – [out] On success, the number of bytes that make up the message 2.

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.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Transcript hash computation failed.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman operation failed.
EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials operation failed.
EDHOC_ERROR_EAD_COMPOSE_FAILURE – EAD compose callback failed.

int edhoc_message_2_process(struct edhoc_context *edhoc_context, const uint8_t *message_2, size_t message_2_length)

Process EDHOC message 2.

Parameters:

edhoc_context – EDHOC context.
message_2 – [in] Buffer containing the message 2.
message_2_length – Length of the message_2 in bytes.

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.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_MSG_2_PROCESS_FAILURE – EDHOC message processing failed.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Transcript hash computation failed.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman operation failed.
EDHOC_ERROR_INVALID_MAC_2 – MAC_2 verification failed.
EDHOC_ERROR_INVALID_SIGN_OR_MAC_2 – Signature_or_MAC_2 verification failed.
EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials operation failed.
EDHOC_ERROR_EAD_PROCESS_FAILURE – EAD process callback failed.

int edhoc_message_3_compose(struct edhoc_context *edhoc_context, uint8_t *message_3, size_t message_3_size, size_t *message_3_length)

Compose EDHOC message 3.

Parameters:

edhoc_context – EDHOC context.
message_3 – [out] Buffer where the generated message 3 is to be written.
message_3_size – Size of the message_3 buffer in bytes.
message_3_length – [out] On success, the number of bytes that make up the message 3.

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.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Transcript hash computation failed.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.
EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials operation failed.
EDHOC_ERROR_EAD_COMPOSE_FAILURE – EAD compose callback failed.

int edhoc_message_3_process(struct edhoc_context *edhoc_context, const uint8_t *message_3, size_t message_3_length)

Process EDHOC message 3.

Parameters:

edhoc_context – EDHOC context.
message_3 – [in] Buffer containing the message 3.
message_3_length – Length of the message_3 in bytes.

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.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_MSG_3_PROCESS_FAILURE – EDHOC message processing failed.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Transcript hash computation failed.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.
EDHOC_ERROR_INVALID_MAC_3 – MAC_3 verification failed.
EDHOC_ERROR_INVALID_SIGN_OR_MAC_3 – Signature_or_MAC_3 verification failed.
EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials operation failed.
EDHOC_ERROR_EAD_PROCESS_FAILURE – EAD process callback failed.

int edhoc_message_4_compose(struct edhoc_context *edhoc_context, uint8_t *message_4, size_t message_4_size, size_t *message_4_length)

Compose EDHOC message 4.

Parameters:

edhoc_context – EDHOC context.
message_4 – [out] Buffer where the generated message 4 is to be written.
message_4_size – Size of the message_4 buffer in bytes.
message_4_length – [out] On success, the number of bytes that make up the message 4.

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.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_EAD_COMPOSE_FAILURE – EAD compose callback failed.

int edhoc_message_4_process(struct edhoc_context *edhoc_context, const uint8_t *message_4, size_t message_4_length)

Process EDHOC message 4.

Parameters:

edhoc_context – EDHOC context.
message_4 – [in] Buffer containing the message 4.
message_4_length – Length of the message_4 in bytes.

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.
EDHOC_ERROR_MSG_4_PROCESS_FAILURE – EDHOC message 4 processing failed.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_EAD_PROCESS_FAILURE – EAD process callback failed.

int edhoc_message_error_compose(uint8_t *message_error, size_t message_error_size, size_t *message_error_length, enum edhoc_error_code error_code, const struct edhoc_error_info *error_info)

Compose EDHOC message error.

Parameters:

message_error – [out] Buffer where the generated message error is to be written.
message_error_size – Size of the message_error buffer in bytes.
message_error_length – [out] On success, the number of bytes that make up the message error.
error_code – EDHOC error code.
error_info – [in] EDHOC error information.

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.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.

int edhoc_message_error_process(const uint8_t *message_error, size_t message_error_length, enum edhoc_error_code *error_code, struct edhoc_error_info *error_info)

Process EDHOC message error.

Parameters:

message_error – [in] Buffer containing the message error.
message_error_length – Length of the message_error in bytes.
error_code – [out] EDHOC error code.
error_info – [out] EDHOC error information.

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.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.

group EDHOC exporters API

Functions

int edhoc_export_prk_exporter(struct edhoc_context *edhoc_context, size_t label, uint8_t *secret, size_t secret_length)

Export derived keying material using the pseudorandom key exporter.

Parameters:

edhoc_context – EDHOC context.
label – PRK exporter label.
secret – [out] Buffer where the generated secret is to be written.
secret_length – Size of the secret buffer in bytes.

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.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

int edhoc_export_key_update(struct edhoc_context *edhoc_context, const uint8_t *entropy, size_t entropy_length)

Perform key update for subsequent OSCORE session exports.

Parameters:

edhoc_context – EDHOC context.
entropy – [in] Buffer containing the entropy for key update.
entropy_length – Size of the entropy buffer in bytes.

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.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

int edhoc_export_oscore_session(struct edhoc_context *edhoc_context, uint8_t *master_secret, size_t master_secret_length, uint8_t *master_salt, size_t master_salt_length, uint8_t *sender_id, size_t sender_id_size, size_t *sender_id_length, uint8_t *recipient_id, size_t recipient_id_size, size_t *recipient_id_length)

Export the OSCORE security session.

Parameters:

edhoc_context – EDHOC context.
master_secret – [out] Buffer where the exported master secret is to be written.
master_secret_length – Size of the master_secret buffer in bytes.
master_salt – [out] Buffer where the exported master salt is to be written.
master_salt_length – Size of the master_salt buffer in bytes.
sender_id – [out] Buffer where the exported sender id is to be written.
sender_id_size – Size of the sender_id buffer in bytes.
sender_id_length – [out] On success, the number of bytes that make up the sender id.
recipient_id – [out] Buffer where the exported recipient id is to be written.
recipient_id_size – Size of the recipient_id buffer in bytes.
recipient_id_length – [out] On success, the number of bytes that make up the recipient id.

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.
EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

group EDHOC errors API

Functions

int edhoc_error_get_code(const struct edhoc_context *edhoc_context, enum edhoc_error_code *error_code)

EDHOC error getter.

Parameters:

edhoc_context – EDHOC context.
error_code – [out] EDHOC error code.

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_error_get_cipher_suites(const struct edhoc_context *edhoc_context, int32_t *cipher_suites, size_t cipher_suites_size, size_t *cipher_suites_length, int32_t *peer_cipher_suites, size_t peer_cipher_suites_size, size_t *peer_cipher_suites_length)

Retrieve own and peer cipher suites after EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE.

Parameters:

edhoc_context – EDHOC context.
cipher_suites – [out] Buffer where the own cipher suite values are written.
cipher_suites_size – Size of the cipher_suites buffer in entries.
cipher_suites_length – [out] On success, the number of entries written to cipher_suites.
peer_cipher_suites – [out] Buffer where the peer cipher suite values are written.
peer_cipher_suites_size – Size of the peer_cipher_suites buffer in entries.
peer_cipher_suites_length – [out] On success, the number of entries written to peer_cipher_suites.

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.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

Authentication credentials

Header file: include/edhoc_credentials.h.

group EDHOC authentication credentials interface

Typedefs

typedef int (*edhoc_credentials_fetch_t)(void *user_context, struct edhoc_auth_creds *credentials)

Fetch local authentication credentials.

Called by the library to obtain the local party’s authentication credentials (keys, certificates) for composing EDHOC messages.

Param user_context:: [in] User context.
Param credentials:: [out] Authentication credentials to populate.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_credentials_verify_t)(void *user_context, struct edhoc_auth_creds *credentials, const uint8_t **public_key_reference, size_t *public_key_length)

Verify peer authentication credentials.

Called by the library to let the application verify the peer’s authentication credentials (e.g., certificate chain validation, revocation checks) and provide the peer’s public key.

Param user_context:: [in] User context.
Param credentials:: [inout] Peer authentication credentials to verify.
Param public_key_reference:: [out] On success, set to point to the peer’s public key.
Param public_key_length:: [out] On success, the number of bytes that make up the public key.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

Enums

enum edhoc_encode_type

CBOR encoding type where we can choose between integer or byte string.

Values:

enumerator EDHOC_ENCODE_TYPE_INTEGER: Encode as CBOR integer.

enumerator EDHOC_ENCODE_TYPE_BYTE_STRING: Encode as CBOR byte string.

enum edhoc_cose_header

Supported IANA COSE header labels.

For fetch callback we need to fill:

any type of credentials: cred and cred_len.
are credentials CBOR-encoded: cred_is_cbor.
encoding type of key identifier: encode_type.
key identifier: key_id_int or key_id_bstr and key_id_bstr_length.

In verify callback we will receive:

encode_type.
key_id_int or key_id_bstr & key_id_bstr_length.

If key id has been found in local storage, reference for cred and cred_len needs to be written for further EDHOC processing.

Public Members

const uint8_t *cred: Credentials buffer.

size_t cred_len: Size of the cred buffer in bytes.

bool cred_is_cbor: Are credentials CBOR-encoded? E.g. CWT, CCS.

enum edhoc_encode_type encode_type: Encoding type of key identifier. It must follow representation of byte string identifiers described in RFC 9528: 3.3.2.

int32_t key_id_int: Key identifier as CBOR integer.

uint8_t key_id_bstr[CONFIG_LIBEDHOC_MAX_LEN_OF_CRED_KEY_ID + 1]: Key identifier as CBOR byte string buffer.

size_t key_id_bstr_length: Size of the key_id_bstr buffer in bytes.

struct edhoc_auth_cred_x509_chain

#include <edhoc_credentials.h>

X.509 chain authentication method.

For fetch callback we need to fill:

number of certificates: nr_of_certs.
certificates: cert.
certificate lengths: cert_len.

For verify callback we will receive:

number of certificates: nr_of_certs.
certificates: cert.
certificate lengths: cert_len.

Public Members

size_t nr_of_certs: Number of certificates in chain.

const uint8_t *cert[CONFIG_LIBEDHOC_MAX_NR_OF_CERTS_IN_X509_CHAIN]: Certificates references.

size_t cert_len[CONFIG_LIBEDHOC_MAX_NR_OF_CERTS_IN_X509_CHAIN]: Sizes of the cert references in bytes.

struct edhoc_auth_cred_x509_hash

#include <edhoc_credentials.h>

X.509 hash authentication method.

For fetch callback we need to fill:

certificate: cert & cert_len.
certificate fingerprint: cert_fp & cert_fp_len.
encoding type of fingerprint algorithm: encode_type.
fingerprint algorithm: alg_int or alg_bstr & alg_bstr_length.

In verify callback we will receive:

cert_fp & cert_fp_len.
encode_type.
alg_int or alg_bstr & alg_bstr_length.

If certificate fingerprint has been found in local storage, reference for cert and cert_len needs to be written for further EDHOC processing.

Public Members

const uint8_t *cert: Certificate buffer.

size_t cert_len: Size of the cert buffer in bytes.

const uint8_t *cert_fp: Certificate fingerprint buffer.

size_t cert_fp_len: Size of the cert_fp buffer in bytes.

enum edhoc_encode_type encode_type: Encoding type of certificate fingerprint algorithm.

int32_t alg_int: Fingerprint algorithm as CBOR integer.

uint8_t alg_bstr[CONFIG_LIBEDHOC_MAX_LEN_OF_HASH_ALG + 1]: Fingerprint algorithm as CBOR byte string buffer.

size_t alg_bstr_length: Size of the alg_bstr buffer in bytes.

struct edhoc_auth_cred_any

#include <edhoc_credentials.h>

Any authentication credentials.

Note

Application developer is responsible for correct CBOR encoding (compact if required) and decoding.

Public Members

const uint8_t *id_cred: Buffer containing identification and optionally transport the credentials. RFC 9528: 2. EDHOC Outline: ID_CRED_I & ID_CRED_R.

size_t id_cred_len: Size of the id_cred buffer in bytes.

bool is_id_cred_comp_enc: Is compact encoding of ID_CRED ? RFC 9528: 3.5.3.2. Compact Encoding of ID_CRED Fields for ‘kid’.

enum edhoc_encode_type encode_type: Encoding type of ID_CRED.

const uint8_t *id_cred_comp_enc: Buffer containing compact encoded identification.

size_t id_cred_comp_enc_length: Size of the id_cred_comp_enc buffer in bytes.

const uint8_t *cred: Buffer containing authentication credentials containing the public authentication keys. RFC 9528: 2. EDHOC Outline: CRED_I & CRED_R.

size_t cred_len: Size of the cred buffer in bytes.

struct edhoc_auth_creds

#include <edhoc_credentials.h>

Common structure for different authentication credentials methods.

Public Members

uint8_t priv_key_id[CONFIG_LIBEDHOC_KEY_ID_LEN]: Private signature or static DH key.

enum edhoc_cose_header label: COSE IANA label.

struct edhoc_auth_cred_key_id key_id: Key identifier authentication structure.

struct edhoc_auth_cred_x509_chain x509_chain: X.509 chain authentication structure.

struct edhoc_auth_cred_x509_hash x509_hash: X.509 hash authentication structure.

struct edhoc_auth_cred_any any: User defined authentication credentials structure.

struct edhoc_credentials

#include <edhoc_credentials.h>

Bind structure for authentication credentials.

Public Members

edhoc_credentials_fetch_t fetch: Authentication credentials fetch callback.

edhoc_credentials_verify_t verify: Authentication credentials verify callback.

Cryptographic operations

Header file: include/edhoc_crypto.h.

group EDHOC interface for cryptographic keys

Typedefs

typedef int (*edhoc_import_key_t)(void *user_context, enum edhoc_key_type key_type, const uint8_t *raw_key, size_t raw_key_length, void *key_id)

Import a cryptographic key and obtain its identifier.

Param user_context:: [in] User context.
Param key_type:: Requested key type.
Param raw_key:: [in] Raw key material.
Param raw_key_length:: Size of the raw_key buffer in bytes.
Param key_id:: [out] Key identifier.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_destroy_key_t)(void *user_context, void *key_id)

Destroy a previously imported cryptographic key.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

Enums

enum edhoc_key_type

EDHOC key types for cryptographic keys interface.

Values:

enumerator EDHOC_KT_MAKE_KEY_PAIR: Key type for generation of ephemeral Diffie-Hellman key pair.

enumerator EDHOC_KT_KEY_AGREEMENT: Key type for Diffie-Hellman keys agreement.

enumerator EDHOC_KT_SIGNATURE: Key type for signing.

enumerator EDHOC_KT_VERIFY: Key type for signature verification.

enumerator EDHOC_KT_EXTRACT: Key type for HKDF extract.

enumerator EDHOC_KT_EXPAND: Key type for HKDF expand.

enumerator EDHOC_KT_ENCRYPT: Key type for symmetric authenticated encryption.

enumerator EDHOC_KT_DECRYPT: Key type for symmetric authenticated decryption.

struct edhoc_keys

#include <edhoc_crypto.h>

Bind structure for cryptographic key identifiers.

Public Members

edhoc_import_key_t import_key: Import cryptographic key callback.

edhoc_destroy_key_t destroy_key: Destroy cryptographic key callback.

group EDHOC interface for cryptographic operations

Typedefs

typedef int (*edhoc_make_key_pair_t)(void *user_context, const void *key_id, uint8_t *private_key, size_t private_key_size, size_t *private_key_length, uint8_t *public_key, size_t public_key_size, size_t *public_key_length)

Generate an ephemeral ECDH key pair.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param private_key:: [out] Private ephemeral ECDH key.
Param private_key_size:: Size of the private_key buffer in bytes.
Param private_key_length:: [out] On success, the number of bytes that make up the ECDH private key.
Param public_key:: [out] Public ephemeral ECDH key.
Param public_key_size:: Size of the public_key buffer in bytes.
Param public_key_length:: [out] On success, the number of bytes that make up the ECDH public key.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_key_agreement_t)(void *user_context, const void *key_id, const uint8_t *peer_public_key, size_t peer_public_key_length, uint8_t *shared_secret, size_t shared_secret_size, size_t *shared_secret_length)

Compute ECDH key agreement (shared secret).

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param peer_public_key:: [in] Peer public ECDH key.
Param peer_public_key_length:: Size of the peer_public_key buffer in bytes.
Param shared_secret:: [out] ECDH shared secret.
Param shared_secret_size:: Size of the shared_secret buffer in bytes.
Param shared_secret_length:: [out] On success, the number of bytes that make up the ECDH shared secret.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_signature_t)(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Generate a digital signature.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param input:: [in] Input message to sign.
Param input_length:: Size of the input buffer in bytes.
Param signature:: [out] Buffer where the signature is to be written.
Param signature_size:: Size of the signature buffer in bytes.
Param signature_length:: [out] On success, the number of bytes that make up the signature.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_verify_t)(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

Verify a digital signature.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param input:: [in] Input message to verify.
Param input_length:: Size of the input buffer in bytes.
Param signature:: [in] Buffer containing the signature to verify.
Param signature_length:: Size of the signature buffer in bytes.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_extract_t)(void *user_context, const void *key_id, const uint8_t *salt, size_t salt_len, uint8_t *pseudo_random_key, size_t pseudo_random_key_size, size_t *pseudo_random_key_length)

Perform HKDF-Extract.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param salt:: [in] Salt for extract.
Param salt_len:: Size of the salt buffer in bytes.
Param pseudo_random_key:: [out] Buffer where the pseudorandom key is to be written.
Param pseudo_random_key_size:: Size of the pseudo_random_key buffer in bytes.
Param pseudo_random_key_length:: [out] On success, the number of bytes that make up the pseudorandom key.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_expand_t)(void *user_context, const void *key_id, const uint8_t *info, size_t info_length, uint8_t *output_keying_material, size_t output_keying_material_length)

Perform HKDF-Expand.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param info:: [in] Context and application-specific information.
Param info_length:: Size of the info buffer in bytes.
Param output_keying_material:: [out] Buffer where the output keying material is to be written.
Param output_keying_material_length:: Size of the output_keying_material buffer in bytes.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_encrypt_t)(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)

Perform AEAD encryption.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param nonce:: [in] Nonce or IV to use.
Param nonce_length:: Size of the nonce buffer in bytes.
Param additional_data:: [in] Additional data that will be authenticated but not encrypted.
Param additional_data_length:: Size of the additional_data buffer in bytes.
Param plaintext:: [in] Data that will be authenticated and encrypted.
Param plaintext_length:: Size of the plaintext buffer in bytes.
Param ciphertext:: [out] Buffer where the authenticated and encrypted data is to be written.
Param ciphertext_size:: Size of the ciphertext buffer in bytes.
Param ciphertext_length:: [out] On success, the number of bytes that make up the ciphertext.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_decrypt_t)(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)

Perform AEAD decryption.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param nonce:: [in] Nonce or IV to use.
Param nonce_length:: Size of the nonce buffer in bytes.
Param additional_data:: [in] Additional data that will be authenticated but not encrypted.
Param additional_data_length:: Size of the additional_data buffer in bytes.
Param ciphertext:: [in] Buffer containing the authenticated and encrypted data.
Param ciphertext_length:: Size of the ciphertext buffer in bytes.
Param plaintext:: [out] Buffer where the decrypted data is to be written.
Param plaintext_size:: Size of the plaintext buffer in bytes.
Param plaintext_length:: [out] On success, the number of bytes that make up the plaintext.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_hash_t)(void *user_context, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)

Compute a cryptographic hash.

Param user_context:: [in] User context.
Param input:: [in] Input message to hash.
Param input_length:: Size of the input buffer in bytes.
Param hash:: [out] Buffer where the hash is to be written.
Param hash_size:: Size of the hash buffer in bytes.
Param hash_length:: [out] On success, the number of bytes that make up the hash.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

struct edhoc_cipher_suite

#include <edhoc_crypto.h>

Structure for cipher suite value and related algorithms lengths in bytes.

Public Members

int32_t value: Cipher suite IANA registry value.

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.

size_t ecc_key_length: EDHOC ECC algorithm: key length in bytes.

size_t ecc_sign_length: EDHOC ECC algorithm: signature length in bytes.

struct edhoc_crypto

#include <edhoc_crypto.h>

Bind structure for cryptographic operations.

Public Members

edhoc_make_key_pair_t make_key_pair: Cryptographic function callback for generate ephemeral Diffie-Hellman key pair.

edhoc_key_agreement_t key_agreement: Cryptographic function callback for Diffie-Hellman key agreement.

edhoc_signature_t signature: Cryptographic function callback for signing.

edhoc_verify_t verify: Cryptographic function callback for signature verification.

edhoc_extract_t extract: Cryptographic function callback for HKDF extract.

edhoc_expand_t expand: Cryptographic function callback for HKDF expand.

edhoc_encrypt_t encrypt: Cryptographic function callback for symmetric authenticated encryption.

edhoc_decrypt_t decrypt: Cryptographic function callback for symmetric authenticated decryption.

edhoc_hash_t hash: Cryptographic function callback for hash computing.

External Authorization Data

Header file: include/edhoc_ead.h.

group EDHOC interface EAD

Typedefs

typedef int (*edhoc_ead_compose_t)(void *user_context, enum edhoc_message message, struct edhoc_ead_token *ead_token, size_t ead_token_size, size_t *ead_token_len)

Compose external authorization data (EAD) tokens.

Called by the library during message composition to let the application attach EAD items to the outgoing EDHOC message.

Param user_context:: [in] User context.
Param message:: EDHOC message number (EAD_1, EAD_2, EAD_3, or EAD_4).
Param ead_token:: [inout] Array where the generated EAD tokens are written.
Param ead_token_size:: Maximum number of entries in the ead_token array.
Param ead_token_len:: [out] On success, the number of EAD tokens written.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_ead_process_t)(void *user_context, enum edhoc_message message, const struct edhoc_ead_token *ead_token, size_t ead_token_size)

Process received external authorization data (EAD) tokens.

Called by the library during message processing to deliver received EAD items to the application for validation.

Param user_context:: [in] User context.
Param message:: EDHOC message number (EAD_1, EAD_2, EAD_3, or EAD_4).
Param ead_token:: [in] Array containing the received EAD tokens.
Param ead_token_size:: Number of entries in the ead_token array.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

Enums

enum edhoc_message

Helper type for recognition of EDHOC message in EAD callback.

Values:

enumerator EDHOC_MSG_1: EDHOC message 1.

enumerator EDHOC_MSG_2: EDHOC message 2.

enumerator EDHOC_MSG_3: EDHOC message 3.

enumerator EDHOC_MSG_4: EDHOC message 4.

struct edhoc_ead_token

#include <edhoc_ead.h>

RFC 9528: 3.8. External Authorization Data (EAD).

Public Members

int32_t label: EAD label value.

const uint8_t *value: EAD buffer.

size_t value_len: Size of the value buffer in bytes.

struct edhoc_ead

#include <edhoc_ead.h>

Bind structure for EAD operations.

Public Members

edhoc_ead_compose_t compose: External authorization data compose callback.

edhoc_ead_process_t process: External authorization data process callback.

EDHOC context

Header file: include/edhoc_context.h.

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.

EDHOC common

Header file: include/edhoc_common.h.

group EDHOC common structures

struct mac_context

#include <edhoc_common.h>

RFC 9528:

5.3.2. Responder Composition of Message 2.
- context_2.
5.4.2. Initiator Composition of Message 3.
- context_3.

Public Members

uint8_t *conn_id: Buffer containing cborised connection identifier.

size_t conn_id_len: Size of the conn_id buffer in bytes.

uint8_t *id_cred: Buffer containing cborised credentials identifier.

size_t id_cred_len: Size of the id_cred buffer in bytes.

bool id_cred_is_comp_enc: Is compact encoding possible?

enum edhoc_encode_type id_cred_enc_type: Credentials identifier encoding type.

int32_t id_cred_int: Buffer containing credentials identifier integer representation.

uint8_t id_cred_bstr[CONFIG_LIBEDHOC_MAX_LEN_OF_CRED_KEY_ID + 1]: Buffer containing credentials identifier byte string representation.

size_t id_cred_bstr_len: Size of the id_cred_bstr buffer in bytes.

uint8_t *th: Buffer containing cborised transcript hash.

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

uint8_t *cred: Buffer containing cborised credentials.

size_t cred_len: Size of the cred buffer in bytes.

bool is_ead: Is EAD attached?

uint8_t *ead: Buffer containing cborised EAD.

size_t ead_len: Size of the ead buffer in bytes.

size_t buf_len: Size of the buf buffer in bytes.

uint8_t buf[]: Flexible array member buffer.

struct plaintext

#include <edhoc_common.h>

RFC 9528:

5.3.2. Responder Composition of Message 2.
- PLAINTEXT_2.
5.4.2. Initiator Composition of Message 3.
- PLAINTEXT_3.

Public Members

struct edhoc_auth_creds auth_cred: Authentication credentials.

const uint8_t *sign_or_mac: Buffer containing cborised Signature_or_MAC (2/3).

size_t sign_or_mac_len: Size of the sign_or_mac buffer in bytes.

const uint8_t *ead: Buffer containing cborised EAD (2/3).

size_t ead_len: Size of the ead buffer in bytes.

group EDHOC common CBOR

Functions

size_t edhoc_cbor_int_mem_req(int32_t value)

Compute CBOR encoding size for an integer.

Parameters:: value – Integer value to encode.
Returns:: Number of bytes required to CBOR-encode value.

size_t edhoc_cbor_tstr_oh(size_t length)

Compute CBOR overhead for a text string.

Parameters:: length – Length of the text string in bytes.
Returns:: Number of CBOR overhead bytes for encoding a tstr of length.

size_t edhoc_cbor_bstr_oh(size_t length)

Compute CBOR overhead for a byte string.

Parameters:: length – Length of the byte string in bytes.
Returns:: Number of CBOR overhead bytes for encoding a bstr of length.

size_t edhoc_cbor_map_oh(size_t items)

Compute CBOR overhead for a map.

Parameters:: items – Number of key-value pairs in the map.
Returns:: Number of CBOR overhead bytes for encoding a map of items pairs.

size_t edhoc_cbor_array_oh(size_t items)

Compute CBOR overhead for an array.

Parameters:: items – Number of elements in the array.
Returns:: Number of CBOR overhead bytes for encoding an array of items elements.

group EDHOC common MAC context

Functions

int edhoc_comp_mac_context_length(const struct edhoc_context *edhoc_context, const struct edhoc_auth_creds *credentials, size_t *mac_context_length)

Compute required buffer length for MAC 2/3 context.

Parameters:

edhoc_context – EDHOC context.
credentials – [in] Authentication credentials.
mac_context_length – [out] On success, number of bytes that make up MAC context.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure.

int edhoc_comp_mac_context(const struct edhoc_context *edhoc_context, const struct edhoc_auth_creds *credentials, struct mac_context *mac_context)

CBOR-encode items required by the MAC 2/3 context.

Parameters:

edhoc_context – EDHOC context.
credentials – [in] Authentication credentials.
mac_context – On success, generated MAC context.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure.

group EDHOC common Signature_or_MAC

Functions

int edhoc_comp_mac_length(const struct edhoc_context *edhoc_context, size_t *mac_length)

Compute required buffer length for MAC 2/3.

Parameters:

edhoc_context – EDHOC context.
mac_length – [out] On success, number of bytes that make up MAC 2/3 length requirements.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure.

int edhoc_comp_mac(const struct edhoc_context *edhoc_context, const struct mac_context *mac_context, uint8_t *mac, size_t mac_length)

Compute MAC 2/3 buffer.

Parameters:

edhoc_context – EDHOC context.
mac_context – MAC context.
mac – [out] Buffer where the generated MAC 2/3 is to be written.
mac_length – Size of the mac buffer in bytes.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure.

int edhoc_comp_sign_or_mac_length(const struct edhoc_context *edhoc_context, size_t *sign_or_mac_length)

Compute required buffer length for Signature_or_MAC 2/3.

Parameters:

edhoc_context – EDHOC context.
sign_or_mac_length – [out] On success, number of bytes that make up Signature_or_MAC 2/3 length requirements.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure.

int edhoc_comp_sign_or_mac(const struct edhoc_context *edhoc_context, const struct edhoc_auth_creds *cred, const struct mac_context *mac_context, const uint8_t *mac, size_t mac_len, uint8_t *signature, size_t signature_size, size_t *signature_length)

Compute Signature_or_MAC 2/3 buffer.

Parameters:

edhoc_context – EDHOC context.
cred – [in] Authentication credentials.
mac_context – MAC context.
mac – [in] Buffer containing the MAC 2/3.
mac_len – [in] Size of the mac buffer in bytes.
signature – [out] Buffer where the generated Signature_or_MAC 2/3 is to be written.
signature_size – Size of the signature buffer in bytes.
signature_length – [out] On success, the number of bytes that make up the Signature_or_MAC 2/3.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure.

int edhoc_verify_sign_or_mac(const struct edhoc_context *edhoc_context, const struct mac_context *mac_context, const uint8_t *public_key, size_t public_key_length, const uint8_t *signature, size_t signature_length, const uint8_t *mac, size_t mac_length)

Verify Signature_or_MAC 2/3 buffer.

Parameters:

edhoc_context – EDHOC context.
mac_context – MAC context.
public_key – [in] Buffer containing authentication public key.
public_key_length – Size of the public_key buffer in bytes.
signature – [in] Buffer containing Signature_or_MAC 2/3.
signature_length – Size of the signature buffer in bytes.
mac – [in] Buffer containing MAC 2/3.
mac_length – Size of the mac buffer in bytes.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure.

EDHOC cipher suite 0

Header file: helpers/include/edhoc_cipher_suite_0.h.

group EDHOC cipher suite 0 API

Functions

const struct edhoc_crypto *edhoc_cipher_suite_0_get_crypto(void)

Get EDHOC crypto structure for cipher suite 0.

Returns a pointer to the cryptographic operations structure implementing cipher suite 0 algorithms (AES-CCM-16-64-128, SHA-256, X25519, EdDSA).

Returns:: Pointer to cipher suite 0 crypto operations structure.

const struct edhoc_keys *edhoc_cipher_suite_0_get_keys(void)

Get EDHOC keys structure for cipher suite 0.

Returns a pointer to the key management operations structure implementing cipher suite 0 key handling.

Returns:: Pointer to cipher suite 0 keys operations structure.

int edhoc_cipher_suite_0_key_import(void *user_context, enum edhoc_key_type key_type, const uint8_t *raw_key, size_t raw_key_len, void *kid)

Import cryptographic key into cipher suite 0.

Imports a raw cryptographic key and associates it with a key identifier. The key type determines the algorithm and usage context.

Parameters:

user_context – [in] User-provided context pointer.
key_type – [in] Type of cryptographic key to import.
raw_key – [in] Buffer containing the raw key material.
raw_key_len – Length of the raw_key buffer in bytes.
kid – [out] Key identifier for the imported key.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_CRYPTO_FAILURE – Key import operation failed.

int edhoc_cipher_suite_0_key_destroy(void *user_context, void *kid)

Destroy cryptographic key.

Securely destroys a previously imported cryptographic key and releases associated resources.

Parameters:

user_context – [in] User-provided context pointer.
kid – [in] Key identifier of the key to destroy.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_CRYPTO_FAILURE – Key destroy operation failed.

int edhoc_cipher_suite_0_make_key_pair(void *user_context, const void *key_id, uint8_t *private_key, size_t private_key_size, size_t *private_key_length, uint8_t *public_key, size_t public_key_size, size_t *public_key_length)

Generate ECDH key pair using X25519.

Generates an ephemeral Diffie-Hellman key pair for X25519 elliptic curve.

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier for the generated key pair.
private_key – [out] Buffer where the private key will be written.
private_key_size – Size of the private_key buffer in bytes.
private_key_length – [out] On success, length of the generated private key.
public_key – [out] Buffer where the public key will be written.
public_key_size – Size of the public_key buffer in bytes.
public_key_length – [out] On success, length of the generated public key.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key pair generation failed.

int edhoc_cipher_suite_0_key_agreement(void *user_context, const void *key_id, const uint8_t *peer_public_key, size_t peer_public_key_length, uint8_t *shared_secret, size_t shared_secret_size, size_t *shared_secret_length)

Perform ECDH key agreement using X25519.

Computes a shared secret using the local private key and the peer’s public key via X25519 elliptic curve Diffie-Hellman.

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the local private key.
peer_public_key – [in] Buffer containing the peer’s public key.
peer_public_key_length – Length of the peer_public_key buffer in bytes.
shared_secret – [out] Buffer where the shared secret will be written.
shared_secret_size – Size of the shared_secret buffer in bytes.
shared_secret_length – [out] On success, length of the computed shared secret.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key agreement computation failed.

int edhoc_cipher_suite_0_signature(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Generate EdDSA signature.

Creates a digital signature over the input data using EdDSA (Ed25519).

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the signing key.
input – [in] Buffer containing data to be signed.
input_length – Length of the input buffer in bytes.
signature – [out] Buffer where the signature will be written.
signature_size – Size of the signature buffer in bytes.
signature_length – [out] On success, length of the generated signature.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Signature generation failed.

int edhoc_cipher_suite_0_verify(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

Verify EdDSA signature.

Verifies a digital signature over the input data using EdDSA (Ed25519).

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the verification key.
input – [in] Buffer containing signed data.
input_length – Length of the input buffer in bytes.
signature – [in] Buffer containing the signature to verify.
signature_length – Length of the signature buffer in bytes.

Return values:

EDHOC_SUCCESS – Signature verification succeeded.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_CRYPTO_FAILURE – Signature verification failed.

int edhoc_cipher_suite_0_extract(void *user_context, const void *key_id, const uint8_t *salt, size_t salt_len, uint8_t *pseudo_random_key, size_t pseudo_random_key_size, size_t *pseudo_random_key_length)

HKDF extract using SHA-256.

Performs the HKDF-Extract operation to derive a pseudorandom key from input keying material using SHA-256 as the hash function.

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the input keying material.
salt – [in] Optional salt value (can be NULL).
salt_len – Length of the salt buffer in bytes.
pseudo_random_key – [out] Buffer where the PRK will be written.
pseudo_random_key_size – Size of the pseudo_random_key buffer in bytes.
pseudo_random_key_length – [out] On success, length of the generated PRK.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Extract operation failed.

int edhoc_cipher_suite_0_expand(void *user_context, const void *key_id, const uint8_t *info, size_t info_length, uint8_t *output_keying_material, size_t output_keying_material_length)

HKDF expand using SHA-256.

Performs the HKDF-Expand operation to derive output keying material from a pseudorandom key using SHA-256 as the hash function.

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the pseudorandom key (PRK).
info – [in] Context and application specific information.
info_length – Length of the info buffer in bytes.
output_keying_material – [out] Buffer where the OKM will be written.
output_keying_material_length – Desired length of output keying material in bytes.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Expand operation failed.

int edhoc_cipher_suite_0_encrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)

AEAD encrypt using AES-CCM-16-64-128.

Encrypts plaintext using AES-CCM with 128-bit key, 64-bit tag, and 13-byte nonce. Provides authenticated encryption with associated data (AEAD).

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the encryption key.
nonce – [in] Nonce (13 bytes for AES-CCM-16-64-128).
nonce_length – Length of the nonce buffer in bytes.
additional_data – [in] Additional authenticated data (can be NULL).
additional_data_length – Length of the additional_data buffer in bytes.
plaintext – [in] Buffer containing plaintext to encrypt.
plaintext_length – Length of the plaintext buffer in bytes.
ciphertext – [out] Buffer where ciphertext and tag will be written.
ciphertext_size – Size of the ciphertext buffer in bytes.
ciphertext_length – [out] On success, length of ciphertext plus tag.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Encryption operation failed.

int edhoc_cipher_suite_0_decrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)

AEAD decrypt using AES-CCM-16-64-128.

Decrypts ciphertext using AES-CCM with 128-bit key, 64-bit tag, and 13-byte nonce. Provides authenticated decryption with associated data (AEAD).

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the decryption key.
nonce – [in] Nonce (13 bytes for AES-CCM-16-64-128).
nonce_length – Length of the nonce buffer in bytes.
additional_data – [in] Additional authenticated data (can be NULL).
additional_data_length – Length of the additional_data buffer in bytes.
ciphertext – [in] Buffer containing ciphertext and tag to decrypt.
ciphertext_length – Length of the ciphertext buffer in bytes (including tag).
plaintext – [out] Buffer where decrypted plaintext will be written.
plaintext_size – Size of the plaintext buffer in bytes.
plaintext_length – [out] On success, length of the decrypted plaintext.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Decryption or authentication failed.

int edhoc_cipher_suite_0_hash(void *user_context, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)

Compute SHA-256 hash.

Computes the SHA-256 cryptographic hash of the input data.

Parameters:

user_context – [in] User-provided context pointer.
input – [in] Buffer containing data to hash.
input_length – Length of the input buffer in bytes.
hash – [out] Buffer where the hash will be written.
hash_size – Size of the hash buffer in bytes (must be ≥ 32).
hash_length – [out] On success, length of the computed hash (32 bytes).

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Hash computation failed.

EDHOC cipher suite 2

Header file: helpers/include/edhoc_cipher_suite_2.h.

Note

In the bundled reference (helpers/src/edhoc_cipher_suite_2.c), what would be a single psa_sign_message-style operation is split into two steps—hash, then sign—so you can map each step to the crypto setup you have. That is useful when sending a large blob for signing is expensive, for example with some secure elements; the library still passes the full COSE Sign1 bytes into the signature / verify callbacks.

group EDHOC cipher suite 2 API

For ES256, edhoc_cipher_suite_2_signature and edhoc_cipher_suite_2_verify split a psa_sign_message-style operation into hash, then sign (edhoc_cipher_suite_2_hash, then psa_sign_hash / psa_verify_hash with PSA_ALG_ECDSA(PSA_ALG_SHA_256)), so each step can follow your platform configuration. That helps when moving a large message through the signing path is costly (e.g. some secure elements). The input to those callbacks is still the full COSE Sign1 payload from the library, not an application-supplied digest.

Functions

const struct edhoc_crypto *edhoc_cipher_suite_2_get_crypto(void)

Get EDHOC crypto structure for cipher suite 2.

Returns a pointer to the cryptographic operations structure implementing cipher suite 2 algorithms (AES-CCM-16-64-128, SHA-256, P-256, ES256).

Returns:: Pointer to cipher suite 2 crypto operations structure.

const struct edhoc_keys *edhoc_cipher_suite_2_get_keys(void)

Get EDHOC keys structure for cipher suite 2.

Returns a pointer to the key management operations structure implementing cipher suite 2 key handling.

Returns:: Pointer to cipher suite 2 keys operations structure.

int edhoc_cipher_suite_2_key_import(void *user_context, enum edhoc_key_type key_type, const uint8_t *raw_key, size_t raw_key_len, void *kid)

Import cryptographic key into cipher suite 2.

Imports a raw cryptographic key and associates it with a key identifier. The key type determines the algorithm and usage context.

Parameters:

user_context – [in] User-provided context pointer.
key_type – [in] Type of cryptographic key to import.
raw_key – [in] Buffer containing the raw key material.
raw_key_len – Length of the raw_key buffer in bytes.
kid – [out] Key identifier for the imported key.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_CRYPTO_FAILURE – Key import operation failed.

int edhoc_cipher_suite_2_key_destroy(void *user_context, void *kid)

Destroy cryptographic key.

Securely destroys a previously imported cryptographic key and releases associated resources.

Parameters:

user_context – [in] User-provided context pointer.
kid – [in] Key identifier of the key to destroy.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_CRYPTO_FAILURE – Key destroy operation failed.

int edhoc_cipher_suite_2_make_key_pair(void *user_context, const void *key_id, uint8_t *private_key, size_t private_key_size, size_t *private_key_length, uint8_t *public_key, size_t public_key_size, size_t *public_key_length)

Generate ECDH key pair using P-256.

Generates an ephemeral Diffie-Hellman key pair for P-256 (secp256r1) elliptic curve.

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier for the generated key pair.
private_key – [out] Buffer where the private key will be written.
private_key_size – Size of the private_key buffer in bytes.
private_key_length – [out] On success, length of the generated private key.
public_key – [out] Buffer where the public key will be written.
public_key_size – Size of the public_key buffer in bytes.
public_key_length – [out] On success, length of the generated public key.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key pair generation failed.

int edhoc_cipher_suite_2_key_agreement(void *user_context, const void *key_id, const uint8_t *peer_public_key, size_t peer_public_key_length, uint8_t *shared_secret, size_t shared_secret_size, size_t *shared_secret_length)

Perform ECDH key agreement using P-256.

Computes a shared secret using the local private key and the peer’s public key via P-256 (secp256r1) elliptic curve Diffie-Hellman.

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the local private key.
peer_public_key – [in] Buffer containing the peer’s public key.
peer_public_key_length – Length of the peer_public_key buffer in bytes.
shared_secret – [out] Buffer where the shared secret will be written.
shared_secret_size – Size of the shared_secret buffer in bytes.
shared_secret_length – [out] On success, length of the computed shared secret.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key agreement computation failed.

int edhoc_cipher_suite_2_signature(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Generate ES256 signature.

Creates a digital signature over the input data using ES256 (ECDSA with P-256 and SHA-256). Uses edhoc_cipher_suite_2_hash for SHA-256, then psa_sign_hash (same outcome as psa_sign_message with PSA_ALG_ECDSA(PSA_ALG_SHA_256); see module

for rationale).

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the signing key.
input – [in] Buffer containing the full message to be signed (not a digest).
input_length – Length of the input buffer in bytes.
signature – [out] Buffer where the signature will be written.
signature_size – Size of the signature buffer in bytes.
signature_length – [out] On success, length of the generated signature.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Signature generation failed.

int edhoc_cipher_suite_2_verify(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

Verify ES256 signature.

Verifies a digital signature over the input data using ES256 (ECDSA with P-256 and SHA-256). Uses edhoc_cipher_suite_2_hash for SHA-256, then psa_verify_hash (see module

).

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the verification key.
input – [in] Buffer containing the full signed message (not a digest).
input_length – Length of the input buffer in bytes.
signature – [in] Buffer containing the signature to verify.
signature_length – Length of the signature buffer in bytes.

Return values:

EDHOC_SUCCESS – Signature verification succeeded.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_CRYPTO_FAILURE – Signature verification failed.

int edhoc_cipher_suite_2_extract(void *user_context, const void *key_id, const uint8_t *salt, size_t salt_len, uint8_t *pseudo_random_key, size_t pseudo_random_key_size, size_t *pseudo_random_key_length)

HKDF extract using SHA-256.

Performs the HKDF-Extract operation to derive a pseudorandom key from input keying material using SHA-256 as the hash function.

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the input keying material.
salt – [in] Optional salt value (can be NULL).
salt_len – Length of the salt buffer in bytes.
pseudo_random_key – [out] Buffer where the PRK will be written.
pseudo_random_key_size – Size of the pseudo_random_key buffer in bytes.
pseudo_random_key_length – [out] On success, length of the generated PRK.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Extract operation failed.

int edhoc_cipher_suite_2_expand(void *user_context, const void *key_id, const uint8_t *info, size_t info_length, uint8_t *output_keying_material, size_t output_keying_material_length)

HKDF expand using SHA-256.

Performs the HKDF-Expand operation to derive output keying material from a pseudorandom key using SHA-256 as the hash function.

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the pseudorandom key (PRK).
info – [in] Context and application specific information.
info_length – Length of the info buffer in bytes.
output_keying_material – [out] Buffer where the OKM will be written.
output_keying_material_length – Desired length of output keying material in bytes.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Expand operation failed.

int edhoc_cipher_suite_2_encrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)

AEAD encrypt using AES-CCM-16-64-128.

Encrypts plaintext using AES-CCM with 128-bit key, 64-bit tag, and 13-byte nonce. Provides authenticated encryption with associated data (AEAD).

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the encryption key.
nonce – [in] Nonce (13 bytes for AES-CCM-16-64-128).
nonce_length – Length of the nonce buffer in bytes.
additional_data – [in] Additional authenticated data (can be NULL).
additional_data_length – Length of the additional_data buffer in bytes.
plaintext – [in] Buffer containing plaintext to encrypt.
plaintext_length – Length of the plaintext buffer in bytes.
ciphertext – [out] Buffer where ciphertext and tag will be written.
ciphertext_size – Size of the ciphertext buffer in bytes.
ciphertext_length – [out] On success, length of ciphertext plus tag.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Encryption operation failed.

int edhoc_cipher_suite_2_decrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)

AEAD decrypt using AES-CCM-16-64-128.

Decrypts ciphertext using AES-CCM with 128-bit key, 64-bit tag, and 13-byte nonce. Provides authenticated decryption with associated data (AEAD).

Parameters:

user_context – [in] User-provided context pointer.
key_id – [in] Key identifier of the decryption key.
nonce – [in] Nonce (13 bytes for AES-CCM-16-64-128).
nonce_length – Length of the nonce buffer in bytes.
additional_data – [in] Additional authenticated data (can be NULL).
additional_data_length – Length of the additional_data buffer in bytes.
ciphertext – [in] Buffer containing ciphertext and tag to decrypt.
ciphertext_length – Length of the ciphertext buffer in bytes (including tag).
plaintext – [out] Buffer where decrypted plaintext will be written.
plaintext_size – Size of the plaintext buffer in bytes.
plaintext_length – [out] On success, length of the decrypted plaintext.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Decryption or authentication failed.

int edhoc_cipher_suite_2_hash(void *user_context, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)

Compute SHA-256 hash.

Computes the SHA-256 cryptographic hash of the input data.

Parameters:

user_context – [in] User-provided context pointer.
input – [in] Buffer containing data to hash.
input_length – Length of the input buffer in bytes.
hash – [out] Buffer where the hash will be written.
hash_size – Size of the hash buffer in bytes (must be ≥ 32).
hash_length – [out] On success, length of the computed hash (32 bytes).

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.
EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.
EDHOC_ERROR_CRYPTO_FAILURE – Hash computation failed.

EDHOC macros

Header file: include/edhoc_macros.h.

group EDHOC utility macros

Defines

VLA_ALLOC(type, name, size)

Allocate a variable-length array on the stack.

On GCC and Clang this uses C99 VLA. On MSVC it falls back to _alloca.

Parameters:

type – Element type.
name – Variable name for the allocated array.
size – Number of elements to allocate.

VLA_SIZEOF(name)

VLA_SIZE(x)

Return the number of elements in a VLA allocated with VLA_ALLOC.

Parameters:

x – Variable name used in VLA_ALLOC.

ARRAY_SIZE(x)

Compute the number of elements in a statically allocated array.

Parameters:

x – Array variable (must not be a pointer).

EDHOC_PRIVATE(member)

Access control macro for context structure members.

When EDHOC_ALLOW_PRIVATE_ACCESS is not defined, each member is prefixed with private_ to discourage direct access. Defining EDHOC_ALLOW_PRIVATE_ACCESS removes the prefix, granting direct access.

Parameters:

member – Structure member name.

EDHOC logging

Header file: include/edhoc_log.h.

Backend header: port/log/linux/edhoc_log_backend.h (Linux) or port/log/zephyr/edhoc_log_backend.h (Zephyr).

The logging module provides compile-time configurable log levels via CONFIG_LIBEDHOC_LOG_LEVEL:

Level	Macro	Value
None	`EDHOC_LOG_LEVEL_NONE`	0
Error	`EDHOC_LOG_LEVEL_ERR`	1
Warning	`EDHOC_LOG_LEVEL_WRN`	2
Info	`EDHOC_LOG_LEVEL_INF`	3
Debug	`EDHOC_LOG_LEVEL_DBG`	4

Set CONFIG_LIBEDHOC_LOG_LEVEL to the desired level during compilation. Each level enables all levels below it. The Linux backend outputs timestamped, color-coded messages to stdout/stderr. The Zephyr backend delegates to the Zephyr logging subsystem.

EDHOC helpers

Header file: helpers/include/edhoc_helpers.h.

group EDHOC Connection ID Utilities API

Functions

bool edhoc_connection_id_equal(const struct edhoc_connection_id *conn_id_1, const struct edhoc_connection_id *conn_id_2)

Compare two connection identifiers for equality.

Parameters:

conn_id_1 – [in] First connection identifier.
conn_id_2 – [in] Second connection identifier.

Returns:

true if connection IDs are equal, false otherwise.

group EDHOC Buffer Utilities API

Functions

int edhoc_prepend_flow(struct edhoc_prepended_fields *prepended_fields)

Prepend flow indicator (CBOR true) to buffer before EDHOC message.

Prepends EDHOC_CBOR_TRUE to indicate forward flow. The prepend buffer must be initialized with buffer and buffer_size before calling this function.

Note

Initialize prepend buffer directly using struct initialization:

struct edhoc_prepended_fields prepended_fields = {
    .buffer = buffer,
    .buffer_size = buffer_size,
    .edhoc_message_ptr = buffer,
    .edhoc_message_size = buffer_size
};

Note

After calling edhoc_prepend_recalculate_size(), buffer_size contains the actual used size (prepended + EDHOC message).

Parameters:

prepended_fields – [inout] Prepend buffer structure (must have buffer and buffer_size set).

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.
EDHOC_ERROR_BUFFER_TOO_SMALL – Not enough space.

int edhoc_prepend_connection_id(struct edhoc_prepended_fields *prepended_fields, const struct edhoc_connection_id *conn_id)

Prepend connection identifier to buffer before EDHOC message.

Encodes and prepends the connection identifier.

Parameters:

prepended_fields – [inout] Prepend buffer structure.
conn_id – [in] Connection identifier to prepend.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.
EDHOC_ERROR_BUFFER_TOO_SMALL – Not enough space.
EDHOC_ERROR_CBOR_FAILURE – Encoding failure.

int edhoc_prepend_recalculate_size(struct edhoc_prepended_fields *prepended_fields)

Recalculate total size after EDHOC message composition.

Recalculates total size after EDHOC message composition and updates buffer_size to reflect the actual used size (prepended + EDHOC message). The EDHOC message length is taken from edhoc_message_size after composition.

Parameters:

prepended_fields – [inout] Prepend buffer structure. On success, buffer_size is updated to the actual used size.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.
EDHOC_ERROR_BUFFER_TOO_SMALL – Total size exceeds buffer capacity.

int edhoc_extract_flow_info(struct edhoc_extracted_fields *extracted_fields)

Extract flow information from buffer.

Checks the beginning of the buffer for flow indicators:

Empty buffer indicates reverse flow
CBOR true (EDHOC_CBOR_TRUE) indicates forward flow
Otherwise, no flow indicator present

If a flow indicator is found, it is extracted and the extract buffer is updated to point to the EDHOC message after the indicator. Flow information is stored in the is_forward_flow and is_reverse_flow fields.

Note

Initialize extract buffer directly using struct initialization:

struct edhoc_extracted_fields extracted_fields = {
    .buffer = buffer,
    .buffer_size = buffer_size,
    .edhoc_message_ptr = buffer,
    .edhoc_message_size = buffer_size
};

Parameters:

extracted_fields – [inout] Extract buffer structure.

Return values:

EDHOC_SUCCESS – Success (flow info extracted or buffer is empty).
EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.

int edhoc_extract_connection_id(struct edhoc_extracted_fields *extracted_fields)

Extract connection identifier from buffer.

Extracts and decodes a connection identifier from the beginning of the buffer. The connection identifier is stored in the extracted_conn_id field on success. The buffer is advanced to point past the connection ID.

Parameters:

extracted_fields – [inout] Extract buffer structure.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.
EDHOC_ERROR_CBOR_FAILURE – Decoding failure.

struct edhoc_prepended_fields

#include <edhoc_helpers.h>

Helper structure for prepending data before EDHOC messages.

Public Members

uint8_t *buffer: Complete buffer including prepended data and EDHOC message.

size_t buffer_size: Total size of the buffer.

uint8_t *edhoc_message_ptr: Pointer to where EDHOC message should be written (after prepended data).

size_t edhoc_message_size: Available size for EDHOC message (after composition, contains actual message length).

struct edhoc_extracted_fields

#include <edhoc_helpers.h>

Helper structure for extracting data from received messages.

Public Members

const uint8_t *buffer: Complete received buffer.

size_t buffer_size: Size of received buffer.

const uint8_t *edhoc_message_ptr: Pointer to EDHOC message (after extracted data).

size_t edhoc_message_size: Size of EDHOC message.

bool is_forward_flow: True if forward flow detected (CBOR true found, set by edhoc_extract_flow_info).

bool is_reverse_flow: True if reverse flow detected (empty buffer, set by edhoc_extract_flow_info).

struct edhoc_connection_id extracted_conn_id: Extracted connection identifier (set by edhoc_extract_connection_id).