API Reference

This section is the complete reference for the libedhoc C API.

Lifecycle

The EDHOC context follows a strict call order. A runnable example is in the Quick Start.

  1. Allocate and initialize — size the opaque context with edhoc_context_size(), then edhoc_context_init().

  2. Configure — edhoc_set_methods(), edhoc_set_cipher_suites(), edhoc_set_connection_id() and, optionally, edhoc_set_user_context().

  3. Bind interfaces — edhoc_bind_crypto(), edhoc_bind_credentials(), edhoc_bind_platform() and the optional edhoc_bind_ead(); their callbacks receive the context set with edhoc_set_user_context().

  4. Exchange messages (strict order) — edhoc_message_1_compose / _process through edhoc_message_4 (message 4 optional); the role decides which side composes or processes each message.

  5. Export and tear down — export the OSCORE Security Context, then edhoc_context_deinit().

Steps 2 and 3 may be interleaved in any order; all must complete before the first message-exchange call.

Error model

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 and listed on the EDHOC Error Codes page.

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_CODE_SUCCESS;

    edhoc_error_get_code(ctx, &err);
}

To send an EDHOC error message to the peer; the call aborts the session, so no further message can be composed or processed with that context:

char text[] = "details";
const struct edhoc_error_info info = {
    .text_string    = text,
    .entries_size   = strlen(text),
    .entries_length = strlen(text),
};
edhoc_message_error_compose(ctx, buf, buf_size, &buf_len,
                            EDHOC_ERROR_CODE_UNSPECIFIED_ERROR, &info);

Processing a received error message aborts the session the same way. Cipher suite negotiation and the one state that is not aborted are described on the EDHOC Error Codes page.

API pages