libedhoc

https://kamil-kielbasa.github.io/libedhoc/
Admin
libedhoc is a C implementation of the Ephemeral Diffie-Hellman Over COSE (EDHOC) protocol, a...
Tokens:81,661
Snippets:401
Trust Score:9.7
Update:6 hours ago
Show doc for...
Tokens:
Raw
### Minimal EDHOC handshake in C

Source: https://kamil-kielbasa.github.io/libedhoc/getting_started/quick_start.html

Complete minimal handshake example: allocate context, configure methods and cipher suites, bind interfaces, run handshake messages, and export OSCORE context.

```c
#include <edhoc/edhoc.h>

/* 1. Allocate the opaque context (stack VLA shown; malloc() also works). */
_Alignas(max_align_t) uint8_t storage[edhoc_context_size()];
struct edhoc_context *ctx = (struct edhoc_context *)storage;
edhoc_context_init(ctx);

/* 2. Configure. */
edhoc_set_methods(ctx, methods, method_count);
edhoc_set_cipher_suites(ctx, suites, cipher_suite_count);
edhoc_set_connection_id(ctx, &connection_id);
edhoc_set_user_context(ctx, user_context);   /* optional */

/* 3. Bind interfaces. */
edhoc_bind_crypto(ctx, &crypto);
edhoc_bind_platform(ctx, &platform);
edhoc_bind_credentials(ctx, &credentials);
/* edhoc_bind_ead(ctx, &ead);  -- optional */

/* 4. Run the handshake (Initiator side shown). */
edhoc_message_1_compose(ctx, msg1, sizeof(msg1), &msg1_len);
/* send msg1, receive msg2 */
edhoc_message_2_process(ctx, msg2, msg2_len);
edhoc_message_3_compose(ctx, msg3, sizeof(msg3), &msg3_len);
/* optionally exchange message_4 */

/* 5. Export the OSCORE Security Context and tear down. */
edhoc_export_oscore_context_raw(ctx, /* ... */);
edhoc_context_deinit(ctx);
```

--------------------------------

### Build with CI script

Source: https://kamil-kielbasa.github.io/libedhoc/getting_started/quick_start.html

Commands to list available build presets and to configure, build, and test a preset using the unified CI script.

```bash
scripts/ci.sh list          # available build presets
scripts/ci.sh ci legacy     # configure, build and test one preset
```

--------------------------------

### struct edhoc_buffer

Source: https://kamil-kielbasa.github.io/libedhoc/api/types.html

Immutable view of a byte sequence. Contains a pointer to the start of the byte sequence and its length.

```APIDOC
## struct edhoc_buffer

### Description
Immutable view of a byte sequence.

### Members
- **value** (const uint8_t *) - Start of the byte sequence.
- **length** (size_t) - Number of bytes in `value`.
```

--------------------------------

### Run CI for a preset (p256_stack)

Source: https://kamil-kielbasa.github.io/libedhoc/guide/building.html

Runs the full CI pipeline for the p256_stack preset using scripts/ci.sh, equivalent to cmake --preset, cmake --build --preset, and ctest --preset.

```bash
$ scripts/ci.sh ci p256_stack
# equivalent to:
$ cmake --preset p256_stack
$ cmake --build --preset p256_stack
$ ctest --preset p256_stack
```

--------------------------------

### edhoc_error_get_code

Source: https://kamil-kielbasa.github.io/libedhoc/api/errors.html

Get the EDHOC error code recorded for the session. Returns the EDHOC error code (RFC 9528: 6) recorded in the context, either by a message compose or process, or by edhoc_message_error_compose() and edhoc_message_error_process().

```APIDOC
## edhoc_error_get_code

### Description
Get the EDHOC error code recorded for the session. Returns the EDHOC error code (RFC 9528: 6) recorded in the context, either by a message compose or process, or by edhoc_message_error_compose() and edhoc_message_error_process().

### Function Signature
int edhoc_error_get_code(const struct edhoc_context *edhoc_context, enum edhoc_error_code *error_code)

### Parameters
- **edhoc_context** (const struct edhoc_context *) - [in] EDHOC context.
- **error_code** (enum edhoc_error_code *) - [out] EDHOC error code.

### Return Values
- **EDHOC_SUCCESS** - Success.

### Returns
Negative error code on failure (EDHOC error codes).
```

--------------------------------

### Run CI for legacy preset on macOS

Source: https://kamil-kielbasa.github.io/libedhoc/guide/building.html

Builds and tests all suites on macOS using the legacy preset with Apple Clang.

```bash
$ scripts/ci.sh ci legacy
```

--------------------------------

### Run full matrix and instrumentation

Source: https://kamil-kielbasa.github.io/libedhoc/guide/building.html

Commands to run the full functional matrix, coverage, sanitizers, valgrind, fuzzing, and format checks.

```bash
$ scripts/ci.sh matrix        # build + test every functional preset
$ scripts/ci.sh coverage      # gcov + gcovr report
$ scripts/ci.sh sanitizers    # ASan + UBSan
$ scripts/ci.sh valgrind      # memcheck + DRD (all suites incl. PQC)
$ scripts/ci.sh fuzz 60       # libFuzzer targets, 60 s each
$ scripts/ci.sh format --check
```

--------------------------------

### Compose EDHOC error message to peer

Source: https://kamil-kielbasa.github.io/libedhoc/api/index.html

Sends an EDHOC error message to the peer using edhoc_message_error_compose(). The call aborts the session, so no further message can be composed or processed with that context. The example initializes an edhoc_error_info struct with a text string and its length.

```c
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);
```

--------------------------------

### Retrieve EDHOC error code after message processing failure

Source: https://kamil-kielbasa.github.io/libedhoc/api/index.html

After a message-processing function fails, use edhoc_error_get_code() to retrieve the EDHOC-level error code (RFC 9528, Section 6). The example checks the return value of edhoc_message_1_process() and retrieves the error code into an edhoc_error_code enum variable.

```c
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);
}
```

--------------------------------

### hash_init

Source: https://kamil-kielbasa.github.io/libedhoc/api/crypto.html

Begins a multipart hash operation. The operation object is owned by the backend and released by hash_finish or hash_abort.

```APIDOC
## hash_init

### Description
Begin a multipart hash operation.

### Function Pointer
int (*hash_init)(void *user_context, void **operation)

### Parameters
- **user_context** (void *) - [in] User context.
- **operation** (void **) - [out] On success, backend hash operation.

### Return Value
- **EDHOC_SUCCESS** - Success.
- **Negative error code** - On failure (EDHOC error codes).
```

--------------------------------

### edhoc_coap_extract_flow_info

Source: https://kamil-kielbasa.github.io/libedhoc/api/coap.html

Detect and strip the flow indicator at the start of the payload. Inspects the first unconsumed byte (RFC 9528: A.2): an empty payload indicates the reverse flow; a leading CBOR true (0xf5) indicates the forward flow, which is then consumed; otherwise no indicator is present and nothing is consumed.

```APIDOC
## edhoc_coap_extract_flow_info

### Description
Detect and strip the flow indicator at the start of the payload. Inspects the first unconsumed byte (RFC 9528: A.2): an empty payload indicates the reverse flow (`is_reverse_flow`); a leading CBOR `true` (0xf5) indicates the forward flow (`is_forward_flow`), which is then consumed; otherwise no indicator is present and nothing is consumed.

### Function Signature
```c
int edhoc_coap_extract_flow_info(struct edhoc_coap_extracted_fields *extracted_fields)
```

### Parameters
- **extracted_fields** (struct edhoc_coap_extracted_fields *) - [inout] Extract buffer; the flow flags are set and the indicator consumed.

### Return Values
- **EDHOC_SUCCESS** - Success (indicator stripped, or none present / empty payload).
- Negative error code on failure (EDHOC error codes).

### Usage Notes
Initialise the extract buffer with designated initialisers before use:
```c
struct edhoc_coap_extracted_fields extracted_fields = {
    .buffer = payload,
    .length = payload_length,
};
```

```

--------------------------------

### edhoc_context_init

Source: https://kamil-kielbasa.github.io/libedhoc/api/context.html

Initializes an EDHOC context. The context must be allocated with edhoc_context_size() before calling this function.

```APIDOC
## edhoc_context_init

### Description
Initializes an EDHOC context. The context must be allocated with edhoc_context_size() before calling this function.

### Function Signature
int edhoc_context_init(struct edhoc_context *edhoc_context)

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.

### Return Values
- **EDHOC_SUCCESS** - Success.
- Negative error code on failure (EDHOC error codes).

```

--------------------------------

### Retrieve cipher suites after wrong selected cipher suite error

Source: https://kamil-kielbasa.github.io/libedhoc/api/errors.html

Example for the Initiator after decoding an error message with EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE. It initializes a buffer for SUITES_R, processes the error message, and calls edhoc_error_get_cipher_suites() to obtain the own and peer cipher suite lists. Retrying requires reinitializing the context for a new EDHOC session.

```c
int32_t suites_r[8] = { 0 };
enum edhoc_error_code err = EDHOC_ERROR_CODE_SUCCESS;
struct edhoc_error_info info = {
    .cipher_suites  = suites_r,
    .entries_size   = sizeof(suites_r) / sizeof(*suites_r),
    .entries_length = 0,
};

edhoc_message_error_process(ctx, buf, buf_len, &err, &info);

if (err == EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE) {
    edhoc_error_get_cipher_suites(ctx, own, own_size, &own_len,
                                  peer, peer_size, &peer_len);
}
```

--------------------------------

### Run Zephyr benchmark with west twister

Source: https://kamil-kielbasa.github.io/libedhoc/guide/building.html

Runs the ZTEST benchmark under tests/zephyr on native_sim with inline logs.

```bash
$ west twister -T tests/zephyr -p native_sim -W --inline-logs
```

--------------------------------

### expand_raw

Source: https://kamil-kielbasa.github.io/libedhoc/api/crypto.html

EDHOC_Expand producing raw output (keystream, IV, MAC, exporter). Takes user context, pseudorandom key handle, info, and outputs raw keying material.

```APIDOC
## expand_raw

### Description
EDHOC_Expand producing raw output (keystream, IV, MAC, exporter).

### Parameters
- **user_context** (void*) - Required - User context.
- **prk_key_id** (const void*) - Required - Pseudorandom key handle.
- **info** (const uint8_t*) - Required - CBOR-encoded info.
- **info_length** (size_t) - Required - Size of the `info` buffer in bytes.
- **output** (uint8_t*) - Required - Raw output keying material.
- **output_length** (size_t) - Required - Requested output length in bytes.

### Return
- **EDHOC_SUCCESS** - Success.
- **Negative error code** - On failure (EDHOC error codes).
```

--------------------------------

### Initialize edhoc_coap_prepended_fields buffer

Source: https://kamil-kielbasa.github.io/libedhoc/api/coap.html

Initializes the prepend buffer with designated initializers before using edhoc_coap_prepend_flow or edhoc_coap_prepend_connection_id. The buffer must be initialized with a buffer and its capacity.

```c
struct edhoc_coap_prepended_fields prepended_fields = {
    .buffer = buffer,
    .capacity = ARRAY_SIZE(buffer),
};
```
Tokens:
Raw