Internal Building Blocks

Note

The groups on this page document internal building blocks that the public API is built on. They are exposed here for advanced users and library contributors. Application code should normally use the higher-level APIs from EDHOC Messages, Exporters and friends instead.

Header file: include/edhoc_common.h

Common structures

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.

CBOR encode/decode

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.

MAC context

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.

Sign-or-MAC

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.