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

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

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

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

### 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`.
```

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

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

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

### 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,
};
```

```

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

### 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
```

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

### 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
```

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

### 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).
```

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

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

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

### 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).

```

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

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

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

### Initialize edhoc_coap_extracted_fields buffer

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

Initializes the extract buffer with designated initializers before using edhoc_coap_extract_flow_info or edhoc_coap_extract_connection_id. The buffer must be initialized with the payload and its length.

```c
struct edhoc_coap_extracted_fields extracted_fields = {
    .buffer = payload,
    .length = payload_length,
};
```

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

### expand

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

EDHOC_Expand producing a key handle (handle space). The usage selects the policy of the created key, since a PSA / secure-element key must receive its policy at creation.

```APIDOC
## expand

### Description
EDHOC_Expand producing a key handle (handle space).

### 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.
- **usage** (enum edhoc_key_usage) - Required - Policy of the produced key.
- **output_key_id** (void*) - Required - Output key handle.

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

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

### verify

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

Verifies a digital signature against a raw peer public key.

```APIDOC
## int (*verify)(void *user_context, const uint8_t *public_key, size_t public_key_length, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

### Description
Verify a digital signature against a raw peer public key.

### Parameters
- **user_context** (void*) - [in] User context.
- **public_key** (const uint8_t*) - [in] Peer public key (raw bytes).
- **public_key_length** (size_t) - Size of the `public_key` buffer in bytes.
- **input** (const uint8_t*) - [in] Full message that was signed.
- **input_length** (size_t) - Size of the `input` buffer in bytes.
- **signature** (const uint8_t*) - [in] Signature to verify.
- **signature_length** (size_t) - Size of the `signature` buffer in bytes.

### Return
- **EDHOC_SUCCESS** - Success.
- Negative error code on failure ([EDHOC error codes](https://kamil-kielbasa.github.io/libedhoc/api/errors.html#group__edhoc-error-codes)).
```

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

### edhoc_bind_platform

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

Binds the platform services interface to the EDHOC context. This is mandatory and provides the platform services the library uses, with every entry of the platform structure being mandatory.

```APIDOC
## edhoc_bind_platform

### Description
Bind the platform services interface (mandatory). Provides the platform services the library uses. Every entry of `platform` is mandatory.

### Function Signature
```c
int edhoc_bind_platform(struct edhoc_context *edhoc_context, const struct edhoc_platform *platform)
```

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.
- **platform** (const struct edhoc_platform*) - [in] EDHOC platform structure with callbacks.

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

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

### edhoc_export

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

Exports application keying material as a key handle. The derived key is returned as an opaque handle, and the length is determined by the usage parameter.

```APIDOC
## edhoc_export

### Description
Exports application keying material as a key handle. The derived key is returned as an opaque handle, and the length is determined by the usage parameter.

### Function Signature
```c
int edhoc_export(struct edhoc_context *edhoc_context, size_t label, const uint8_t *context, size_t context_length, enum edhoc_key_usage usage, void *key_id)
```

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.
- **label** (size_t) - EDHOC exporter label (RFC 9528: 10.1).
- **context** (const uint8_t*) - [in] Exporter context byte string (may be NULL when context_length is 0).
- **context_length** (size_t) - Size of the context buffer in bytes.
- **usage** (enum edhoc_key_usage) - Intended usage of the derived key; governs its type and length.
- **key_id** (void*) - [out] Buffer holding a key handle (CONFIG_LIBEDHOC_KEY_ID_LEN bytes) that receives the derived key.

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

### Notes
The returned handle is owned by the caller: the library neither tracks it nor releases it in edhoc_context_deinit(). Destroy it through the destroy_key entry of the bound edhoc_crypto vtable.

### Permitted Exporter Labels
- 0: OSCORE Master Secret
- 1: OSCORE Master Salt
- 2: Resumption PSK (draft-ietf-lake-edhoc-psk: 10.2)
- 3: Resumption 'kid' (draft-ietf-lake-edhoc-psk: 10.2)
- Private-use range: EDHOC_PRK_EXPORTER_PRIVATE_LABEL_MINIMUM to EDHOC_PRK_EXPORTER_PRIVATE_LABEL_MAXIMUM

Any other label is rejected with EDHOC_ERROR_NOT_PERMITTED. Labels 2 and 3 are open to every method.
```

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

### edhoc_message_2_process

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

Processes EDHOC message 2. The Initiator completes the ephemeral key exchange and verifies the Responder's authentication.

```APIDOC
## edhoc_message_2_process

### Description
Processes EDHOC message 2. The Initiator completes the ephemeral key exchange from G_Y and verifies the Responder's authentication (ID_CRED_R, Signature_or_MAC_2, optional EAD_2) as per RFC 9528 section 5.3.3.

### Function Signature
int edhoc_message_2_process(struct edhoc_context *edhoc_context, const uint8_t *message_2, size_t message_2_length)

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.
- **message_2** (const uint8_t*) - [in] Buffer containing the message 2.
- **message_2_length** (size_t) - Length of the message_2 in bytes.

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

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

### edhoc_crypto::generate_key_pair

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

Generate an ephemeral key pair (Initiator, message_1). The decapsulation (private) key stays in the key store as a handle; only the encapsulation (public) key leaves, to be sent in G_X.

```APIDOC
## edhoc_crypto::generate_key_pair

### Description
Generate an ephemeral key pair (Initiator, message_1). The decapsulation (private) key stays in the key store as a handle; only the encapsulation (public) key leaves, to be sent in G_X. The handle is retained for decapsulate and, on a NIKE suite, for the static-DH G_RX agreement in message_2 (methods 1 and 3).

### Method
Function pointer

### Signature
int (*generate_key_pair)(void *user_context, void *decapsulation_key_id, uint8_t *encapsulation_key, size_t encapsulation_key_size, size_t *encapsulation_key_length)

### Parameters
- **user_context** (void*) - [in] User context.
- **decapsulation_key_id** (void*) - [out] Handle of the generated private key.
- **encapsulation_key** (uint8_t*) - [out] Public key, sent in G_X.
- **encapsulation_key_size** (size_t) - Size of the encapsulation_key buffer in bytes.
- **encapsulation_key_length** (size_t*) - [out] On success, the number of bytes that make up the encapsulation key.

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

```

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

### edhoc_context_size

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

Returns the size in bytes of an EDHOC context for the current build. This size depends on build-time configuration and is a run-time value.

```APIDOC
## edhoc_context_size

### Description
Returns the size in bytes of an EDHOC context for the current build. This size depends on build-time configuration and is a run-time value.

### Function Signature
size_t edhoc_context_size(void)

### Parameters
None.

### Return Values
- Size in bytes of edhoc_context.

```

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

### edhoc_export_resumption_psk_raw

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

Exports the resumption PSK as raw bytes. Derives rPSK (draft-ietf-lake-edhoc-psk: 6) with an empty exporter context. The length is left to the caller.

```APIDOC
## edhoc_export_resumption_psk_raw

### Description
Exports the resumption PSK as raw bytes. Derives rPSK (draft-ietf-lake-edhoc-psk: 6) with an empty exporter context. That section names the cipher suite hash length, while its Appendix B.6 vector is 16 bytes long, so the length is left to the caller.

### Function Signature
```c
int edhoc_export_resumption_psk_raw(struct edhoc_context *edhoc_context, uint8_t *psk, size_t psk_length)
```

### Parameters
- **edhoc_context** (struct edhoc_context *) - [inout] EDHOC context.
- **psk** (uint8_t *) - [out] Buffer where the resumption PSK is to be written.
- **psk_length** (size_t) - Size of the `psk` buffer in bytes.

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

```

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

### edhoc_message_1_process

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

Processes EDHOC message 1. The Responder reads and verifies the proposed method and cipher suites, then reads the Initiator's ephemeral public key, connection identifier, and optional EAD_1.

```APIDOC
## edhoc_message_1_process

### Description
Process EDHOC message 1. The Responder processes message 1: it reads and verifies that it supports the proposed method (METHOD) and cipher suites (SUITES_I), then reads the Initiator's ephemeral public key G_X, the connection identifier C_I and optional EAD_1 (RFC 9528: 5.2.3).

### Function Signature
```c
int edhoc_message_1_process(struct edhoc_context *edhoc_context, const uint8_t *message_1, size_t message_1_length)
```

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.
- **message_1** (const uint8_t*) - [in] Buffer containing the message 1.
- **message_1_length** (size_t) - Length of the `message_1` in bytes.

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

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

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

### edhoc_export_resumption_kid_raw

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

Exports the resumption 'kid' as raw bytes. Derives rKID (draft-ietf-lake-edhoc-psk: 6) with an empty exporter context. rKID identifies the resumption PSK rather than keying it, so it has no key-handle form. Its default length is #EDHOC_EXPORTER_RESUMPTION_KID_DEFAULT_LEN.

```APIDOC
## edhoc_export_resumption_kid_raw

### Description
Exports the resumption 'kid' as raw bytes. Derives rKID (draft-ietf-lake-edhoc-psk: 6) with an empty exporter context. rKID identifies the resumption PSK rather than keying it, so it has no key-handle form. Its default length is #EDHOC_EXPORTER_RESUMPTION_KID_DEFAULT_LEN.

### Function Signature
```c
int edhoc_export_resumption_kid_raw(struct edhoc_context *edhoc_context, uint8_t *kid, size_t kid_length)
```

### Parameters
- **edhoc_context** (struct edhoc_context *) - [inout] EDHOC context.
- **kid** (uint8_t *) - [out] Buffer where the resumption KID is to be written.
- **kid_length** (size_t) - Size of the `kid` buffer in bytes.

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

```

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

### edhoc_export_oscore_context_raw

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

Exports the OSCORE security context as raw bytes, deriving the Master Secret and Master Salt and copying out the Sender and Recipient IDs. Returns EDHOC_SUCCESS on success or a negative error code on failure.

```APIDOC
## edhoc_export_oscore_context_raw

### Description
Exports the OSCORE security context as raw bytes. Derives the OSCORE Master Secret and Master Salt (exporter labels 0 and 1) as raw bytes and copies out the OSCORE Sender and Recipient IDs.

### Function Signature
```c
int edhoc_export_oscore_context_raw(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)
```

### Parameters
- **edhoc_context** (struct edhoc_context *) - [inout] EDHOC context.
- **master_secret** (uint8_t *) - [out] Buffer where the exported master secret is to be written.
- **master_secret_length** (size_t) - Size of the `master_secret` buffer in bytes.
- **master_salt** (uint8_t *) - [out] Buffer where the exported master salt is to be written.
- **master_salt_length** (size_t) - Size of the `master_salt` buffer in bytes.
- **sender_id** (uint8_t *) - [out] Buffer where the exported sender id is to be written.
- **sender_id_size** (size_t) - Size of the `sender_id` buffer in bytes.
- **sender_id_length** (size_t *) - [out] On success, the number of bytes that make up the sender id.
- **recipient_id** (uint8_t *) - [out] Buffer where the exported recipient id is to be written.
- **recipient_id_size** (size_t) - Size of the `recipient_id` buffer in bytes.
- **recipient_id_length** (size_t *) - [out] On success, the number of bytes that make up the recipient id.

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

### Notes
- C_I and C_R become the OSCORE Recipient IDs, so RFC 9528: 3.3.3 forbids them being equal. Such a session is rejected with EDHOC_ERROR_NOT_PERMITTED; only re-running EDHOC with distinct identifiers helps.
- A session yields one security context. A further export returns EDHOC_ERROR_BAD_STATE until edhoc_export_key_update() rotates PRK_out.
```

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

### edhoc_export_raw

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

Exports application keying material as raw bytes. Derives the specified number of bytes (RFC 9528: 4.2.1) and writes them to the provided secret buffer.

```APIDOC
## edhoc_export_raw

### Description
Exports application keying material as raw bytes. Derives `secret_length` bytes (RFC 9528: 4.2.1) and writes them to `secret`.

### Function Signature
```c
int edhoc_export_raw(struct edhoc_context *edhoc_context, size_t label, const uint8_t *context, size_t context_length, uint8_t *secret, size_t secret_length)
```

### Parameters
- **edhoc_context** (struct edhoc_context *) - [inout] EDHOC context.
- **label** (size_t) - EDHOC exporter label (RFC 9528: 10.1).
- **context** (const uint8_t *) - [in] Exporter context byte string (may be NULL when `context_length` is 0).
- **context_length** (size_t) - Size of the `context` buffer in bytes.
- **secret** (uint8_t *) - [out] Buffer where the generated secret is to be written.
- **secret_length** (size_t) - Size of the `secret` buffer in bytes.

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

```

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

### edhoc_bind_credentials

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

Binds the authentication credentials interface to the EDHOC context. This is mandatory and provides the select_local and authenticate_peer callbacks used to obtain local credentials and authenticate the peer.

```APIDOC
## edhoc_bind_credentials

### Description
Bind the authentication credentials interface (mandatory). Provides the `select_local` / `authenticate_peer` callbacks the library uses to obtain the local authentication credential and to authenticate the peer's (RFC 9528: 3.5). Both are mandatory.

### Function Signature
```c
int edhoc_bind_credentials(struct edhoc_context *edhoc_context, const struct edhoc_credentials *credentials)
```

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.
- **credentials** (const struct edhoc_credentials*) - [in] EDHOC authentication credentials structure with callbacks.

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

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

### verify

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

Verifies a signature over a full signed message. Takes the public key, input message, and signature, and returns EDHOC_SUCCESS on success or a negative error code on failure.

```APIDOC
## verify

### Description
Verifies a signature over a full signed message.

### Parameters
- **public_key** (buffer) - Required - Size of the `public_key` buffer in bytes.
- **input** (buffer) - Required - Full signed message (not a digest).
- **input_length** (size_t) - Required - Size of the `input` buffer in bytes.
- **signature** (buffer) - Required - Buffer containing the signature to verify.
- **signature_length** (size_t) - Required - Size of the `signature` buffer in bytes.

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

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

### edhoc_message_4_process

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

Processes the optional EDHOC message 4. The Initiator obtains explicit key confirmation from the Responder.

```APIDOC
## edhoc_message_4_process

### Description
Processes the optional EDHOC message 4. The Initiator processes message 4, obtaining explicit key confirmation from the Responder; it may carry optional EAD_4 as per RFC 9528 section 5.5.3.

### Function Signature
int edhoc_message_4_process(struct edhoc_context *edhoc_context, const uint8_t *message_4, size_t message_4_length)

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.
- **message_4** (const uint8_t*) - [in] Buffer containing the message 4.
- **message_4_length** (size_t) - Length of the message_4 in bytes.

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

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

### edhoc_credentials.select_local

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

Select the local party's authentication credential. Called while composing the message that carries it: the Responder composing message 2, or the Initiator composing message 3. The library builds ID_CRED and CRED from the selected credential and computes Signature_or_MAC with the referenced key.

```APIDOC
## select_local

### Description
Select the local party's authentication credential. Called while composing the message that carries it: the Responder composing message 2 (RFC 9528: 5.3.2); the Initiator composing message 3 (RFC 9528: 5.4.2). The library then builds ID_CRED and CRED from `selected` and computes Signature_or_MAC with the referenced key. For EDHOC_METHOD_4 only the Initiator is called, on message 3.

### Callback Signature
```c
int (*select_local)(void *user_context, const struct edhoc_call_context *call_context, struct edhoc_credential_selected *selected)
```

### Parameters
- **user_context** (void*) - [in] User context.
- **call_context** (const struct edhoc_call_context*) - [in] Parameters of the ongoing session.
- **selected** (struct edhoc_credential_selected*) - [out] Credential to populate.

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

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

### edhoc_platform.zeroize

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

Securely wipe a memory region. This callback is mandatory and must not be optimized away by the compiler. It is used to erase sensitive data from buffers.

```APIDOC
## zeroize

### Description
Securely wipe a memory region. This callback is mandatory and must not be optimized away by the compiler. It is used to erase sensitive data from buffers.

### Method
Callback function pointer

### Signature
void (*zeroize)(void *buffer, size_t length)

### Parameters
- **buffer** (void*) - [out] Memory region to wipe.
- **length** (size_t) - Length of `buffer` in bytes.

### Requirements
- Implementation MUST NOT be eliminated by the compiler (e.g., use `explicit_bzero` or C11 `memset_s`).

### Notes
- This callback is part of the `edhoc_platform` struct and must be bound via `edhoc_bind_platform()`.
```

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

### extract

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

Derives a pseudorandom key handle from a salt using the EDHOC_Extract operation. Takes user context, input keying material handle, salt, and outputs a pseudorandom key handle.

```APIDOC
## extract

### Description
EDHOC_Extract: derive a pseudorandom key handle from a salt.

### Parameters
- **user_context** (void*) - Required - User context.
- **ikm_key_id** (const void*) - Required - Input keying material handle.
- **salt** (const uint8_t*) - Required - Raw salt.
- **salt_length** (size_t) - Required - Size of the `salt` buffer in bytes.
- **prk_key_id** (void*) - Required - Output pseudorandom key handle.

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

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

### edhoc_export_resumption_psk

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

Exports the resumption PSK as a key handle. Derives rPSK (draft-ietf-lake-edhoc-psk: 6) with an empty exporter context. The derived length is set by the usage parameter. The returned handle is owned by the caller.

```APIDOC
## edhoc_export_resumption_psk

### Description
Exports the resumption PSK as a key handle. Derives rPSK (draft-ietf-lake-edhoc-psk: 6) with an empty exporter context. The derived length is set by `usage`, as in `edhoc_export()`. The returned handle is owned by the caller: the library neither tracks it nor releases it in `edhoc_context_deinit()`. Destroy it through the `destroy_key` entry of the bound `edhoc_crypto` vtable.

### Function Signature
```c
int edhoc_export_resumption_psk(struct edhoc_context *edhoc_context, enum edhoc_key_usage usage, void *key_id)
```

### Parameters
- **edhoc_context** (struct edhoc_context *) - [inout] EDHOC context.
- **usage** (enum edhoc_key_usage) - Intended usage of the derived key; governs its type and length.
- **key_id** (void *) - [out] Buffer holding a key handle (`CONFIG_LIBEDHOC_KEY_ID_LEN` bytes) that receives the resumption PSK.

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

```

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

### hash_finish

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

Finishes a multipart hash operation and releases it.

```APIDOC
## hash_finish

### Description
Finish a multipart hash operation and release it.

### Function Pointer
int (*hash_finish)(void *user_context, void *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)

### Parameters
- **user_context** (void *) - [in] User context.
- **operation** (void *) - [in] Backend hash operation.
- **hash** (uint8_t *) - [out] Buffer where the hash is to be written.
- **hash_size** (size_t) - Size of the `hash` buffer in bytes.
- **hash_length** (size_t *) - [out] On success, the number of bytes that make up the hash.

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

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

### aead_encrypt

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

Encrypts data with an AEAD. Takes user context, key handle, nonce, additional data, and plaintext, and outputs ciphertext.

```APIDOC
## aead_encrypt

### Description
Encrypt with an AEAD.

### Parameters
- **user_context** (void*) - Required - User context.
- **key_id** (const void*) - Required - AEAD key handle.
- **nonce** (const uint8_t*) - Required - Nonce or IV to use.
- **nonce_length** (size_t) - Required - Size of the `nonce` buffer in bytes.
- **additional_data** (const uint8_t*) - Required - Additional data that will be authenticated but not encrypted.
- **additional_data_length** (size_t) - Required - Size of the `additional_data` buffer in bytes.
- **plaintext** (const uint8_t*) - Required - Data that will be authenticated and encrypted.
- **plaintext_length** (size_t) - Required - Size of the `plaintext` buffer in bytes.
- **ciphertext** (uint8_t*) - Required - Buffer where the authenticated and encrypted data is to be written.
- **ciphertext_size** (size_t) - Required - Size of the `ciphertext` buffer in bytes.
- **ciphertext_length** (size_t*) - Required - On success, the number of bytes that make up the ciphertext.

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

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

### key_agreement

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

Computes a static Diffie-Hellman shared secret (methods 1/2/3).

```APIDOC
## int (*key_agreement)(void *user_context, const void *private_key_id, const uint8_t *peer_public_key, size_t peer_public_key_length, void *shared_secret_key_id)

### Description
Compute a static Diffie-Hellman shared secret (methods 1/2/3).

Used only for static-DH authentication: `G_RX` in message_2 and `G_IY` in message_3. Each agreement pairs one party's static authentication key with the other's ephemeral key, so which of the two arguments is the static one depends on the local role. A suite without static-DH support fails with #EDHOC_ERROR_NOT_SUPPORTED.

### Parameters
- **user_context** (void*) - [in] User context.
- **private_key_id** (const void*) - [in] Handle of the local private key, static or ephemeral.
- **peer_public_key** (const uint8_t*) - [in] Peer public key (raw bytes), ephemeral or static.
- **peer_public_key_length** (size_t) - Size of the `peer_public_key` buffer in bytes.
- **shared_secret_key_id** (void*) - [out] Handle of the shared secret.

### Return
- **EDHOC_SUCCESS** - Success.
- Negative error code on failure ([EDHOC error codes](https://kamil-kielbasa.github.io/libedhoc/api/errors.html#group__edhoc-error-codes)).
```

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

### sign

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

Generates a digital signature.

```APIDOC
## int (*sign)(void *user_context, const void *private_key_id, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

### Description
Generate a digital signature.

### Parameters
- **user_context** (void*) - [in] User context.
- **private_key_id** (const void*) - [in] Handle of the signing key.
- **input** (const uint8_t*) - [in] Full message to sign (not a digest).
- **input_length** (size_t) - Size of the `input` buffer in bytes.
- **signature** (uint8_t*) - [out] Buffer where the signature is to be written.
- **signature_size** (size_t) - Size of the `signature` buffer in bytes.
- **signature_length** (size_t*) - [out] On success, the number of bytes that make up the signature.

### Return
- **EDHOC_SUCCESS** - Success.
- Negative error code on failure ([EDHOC error codes](https://kamil-kielbasa.github.io/libedhoc/api/errors.html#group__edhoc-error-codes)).
```

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

### edhoc_crypto::destroy_key

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

Destroy a key handle and free its key-store slot. Destroying a zeroed / no-key handle is a successful no-op.

```APIDOC
## edhoc_crypto::destroy_key

### Description
Destroy a key handle and free its key-store slot. Destroying a zeroed / no-key handle is a successful no-op, so edhoc_context_deinit may re-destroy already-freed slots.

### Method
Function pointer

### Signature
int (*destroy_key)(void *user_context, void *key_id)

### Parameters
- **user_context** (void*) - [in] User context.
- **key_id** (void*) - [inout] Key identifier to destroy.

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

```

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

### edhoc_export_key_update

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

Performs a key update for subsequent OSCORE Security Context exports. It rotates PRK_out so that later OSCORE exports derive fresh keying material bound to the application-supplied context byte string. It also re-arms the one-shot OSCORE export, allowing a second security context from the same session.

```APIDOC
## edhoc_export_key_update

### Description
Performs a key update for subsequent OSCORE Security Context exports. It rotates PRK_out so that later OSCORE exports derive fresh keying material bound to the application-supplied context byte string. It also re-arms the one-shot OSCORE export, allowing a second security context from the same session.

### Function Signature
int edhoc_export_key_update(struct edhoc_context *edhoc_context, const uint8_t *context, size_t context_length)

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.
- **context** (const uint8_t*) - [in] Buffer containing the key-update context.
- **context_length** (size_t) - Size of the `context` buffer in bytes.

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

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

### edhoc_set_cipher_suites

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

Sets the EDHOC cipher suite(s) supported by the context. This is mandatory and configures the cipher suites used for the EDHOC session.

```APIDOC
## edhoc_set_cipher_suites

### Description
Sets the EDHOC cipher suite(s) supported by the context. This is mandatory and configures the cipher suites used for the EDHOC session.

### Function Signature
int edhoc_set_cipher_suites(struct edhoc_context *edhoc_context, const struct edhoc_cipher_suite *cipher_suite, size_t cipher_suite_count)

### Parameters
- **edhoc_context** (struct edhoc_context*) - [inout] EDHOC context.
- **cipher_suite** (const struct edhoc_cipher_suite*) - [in] EDHOC cipher suites.
- **cipher_suite_count** (size_t) - Number of entries in the cipher_suite array.

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

```