EDHOC API & interfaces

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 recognized as 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 recognized as 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. It is required to set at least one method but no more than EDHOC_METHOD_MAX.

Depends on processing side:

Initiator will always read first value (method[0]) in message 1 compose.
Responder will iterator over all method and try to match in message 1 process.

Parameters:

edhoc_context – EDHOC context.
method – [in] EDHOC method.
method_length – Number of the method.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Combination of input parameters are recognized as 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 the cipher_suite.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Combination of input parameters are recognized as 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 – Combination of input parameters are recognized as 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 – Combination of input parameters are recognized as 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 – Combination of input parameters are recognized as 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 – Combination of input parameters are recognized as 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 – Combination of input parameters are recognized as 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 – Combination of input parameters are recognized as 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 – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman key pair or agreement failure.
EDHOC_ERROR_EAD_COMPOSE_FAILURE – External authorization data compose failure.

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 – Size of the message_1 buffer in bytes.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_BUFFER_TOO_SMALL – Used buffer is too small.
EDHOC_ERROR_MSG_1_PROCESS_FAILURE – Error on EDHOC layer during processing.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_EAD_PROCESS_FAILURE – External authorization data process failure.

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 – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_BUFFER_TOO_SMALL – Used buffer is too small.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Computation of transcript hash failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Computation of pseudorandom key failure.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman key pair or agreement failure.
EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials fetch/verify failure.
EDHOC_ERROR_EAD_COMPOSE_FAILURE – External authorization data compose failure.

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 – Size of the message_2 buffer in bytes.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_BUFFER_TOO_SMALL – Used buffer is too small.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_MSG_2_PROCESS_FAILURE – Error on EDHOC layer during processing.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Computation of transcript hash failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Computation of pseudorandom key failure.
EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman key pair or agreement failure.
EDHOC_ERROR_INVALID_MAC_2 – Invalid MAC_2.
EDHOC_ERROR_INVALID_SIGN_OR_MAC_2 – Invalid Signature_or_MAC_2.
EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials fetch/verify failure.
EDHOC_ERROR_EAD_PROCESS_FAILURE – External authorization data process failure.

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 – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_BUFFER_TOO_SMALL – Used buffer is too small.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Computation of transcript hash failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Computation of pseudorandom key failure.
EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials fetch/verify failure.
EDHOC_ERROR_EAD_COMPOSE_FAILURE – External authorization data compose failure.

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 – Size of the message_3 buffer in bytes.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_BUFFER_TOO_SMALL – Used buffer is too small.
EDHOC_ERROR_MSG_3_PROCESS_FAILURE – Error on EDHOC layer during processing.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Computation of transcript hash failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Computation of pseudorandom key failure.
EDHOC_ERROR_INVALID_MAC_3 – Invalid EDHOC MAC_3.
EDHOC_ERROR_INVALID_SIGN_OR_MAC_3 – Invalid EDHOC Signature_or_MAC_3.
EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials fetch/verify failure.
EDHOC_ERROR_EAD_PROCESS_FAILURE – External authorization data process failure.

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 – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_EAD_COMPOSE_FAILURE – External authorization data compose failure.

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 – Size of the message_4 buffer in bytes.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
#EDHOC_ERROR_MSG4_PROCESS_FAILURE – Error on EDHOC layer during processing.
EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_MSG_4_PROCESS_FAILURE – External authorization data process failure.
EDHOC_ERROR_EAD_PROCESS_FAILURE – External authorization data process failure.

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 – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_BUFFER_TOO_SMALL – Used buffer is too small.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
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 – Size of the message_error buffer in bytes.
error_code – [out] EDHOC error code.
error_info – [out] EDHOC error information.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_BUFFER_TOO_SMALL – Used buffer is too small.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
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)

Psuedorandom key exporter for derivation keying material.

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 – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Computation of pseudorandom key failure.

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

Export key update for the new OSCORE security session.

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 – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Computation of pseudorandom key failure.

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 – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_NOT_PERMITTED – Processing code branch is not permitted by implementation.
EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.
EDHOC_ERROR_CRYPTO_FAILURE – Cryptographics operation failure.
EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Computation of pseudorandom key failure.

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 – Combination of input parameters are recognized as 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)

EDHOC own and peer cipher suites getter in case of EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE.

Parameters:

edhoc_context – EDHOC context.
cipher_suites – [out] Buffer where the cipher suites values is to be written.
cipher_suites_size – Size of the cipher_suites buffer in entries.
cipher_suites_length – [out] On success, the number of entires that make up the cipher suites.
peer_cipher_suites – [out] Buffer where the peer cipher suites values is to be written.
peer_cipher_suites_size – Size of the peer_cipher_suites buffer in entries.
peer_cipher_suites_length – [out] On success, the number of entires that make up the peer cipher suites.

Return values:

EDHOC_SUCCESS – Success.
EDHOC_ERROR_INVALID_ARGUMENT – Combination of input parameters are recognized as invalid.
EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.
EDHOC_ERROR_BUFFER_TOO_SMALL – Used buffer is too small.

Authentication credentials

Header file: include/edhoc_credentials.h.

group EDHOC interface credentials

Typedefs

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

Authentication credentials fetch callback.

Param user_context:: [in] User context.
Param credentials:: [out] Authentication credentials handle.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Authentication credentials verify callback.

Param user_context:: [in] User context.
Param credentials:: [inout] Peer authentication credentials handle.
Param public_key_reference:: [out] Pointer address where the public key address is to be written.
Param public_key_length:: [out] On success, the number of bytes that make up the public key.
Return:: EDHOC_SUCCESS on success, otherwise 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.

https://www.iana.org/assignments/cose/cose.xhtml

Values:

enumerator EDHOC_COSE_ANY: Any authentication credentials.

enumerator EDHOC_COSE_HEADER_KID: Authentication credentials identified by key identifier.

enumerator EDHOC_COSE_HEADER_X509_CHAIN: Authentication credentials identified by an ordered chain of X.509 certificates.

enumerator EDHOC_COSE_HEADER_X509_HASH: Authentication credentials identified by hash of an X.509 certificate.

struct edhoc_auth_cred_key_id

#include <edhoc_credentials.h>

Key identifier authentication method.

For fetch callback we need to fill:

any type of credentials: cred and cred_len.
is credentials cborised: cred_is_cbor.
encoding type of key identifer: 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 written for further EDHOC processing.

Public Members

const uint8_t *cred: Credentials buffor.

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

bool cred_is_cbor: Is credentials cborised? 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 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 cryptographics 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)

Cryptographic function for import of key identifier.

Param user_context:: [in] User context.
Param key_type:: Requested key type.
Param raw_key:: [in] Key material in binary format.
Param raw_key_length:: Size of the raw_key buffer in bytes.
Param key_id:: [out] Key identifier.
Return:: EDHOC_SUCCESS on success, otherwise failure.

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

Cryptographic function for destroy of key identifier.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Return:: EDHOC_SUCCESS on success, otherwise 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 cryptographics 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)

Cryptographic function for generating 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 private key.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Cryptographic function for computing ECDH key agreement.

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.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Cryptographic function for generating ECDSA sign.

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.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Cryptographic function for ECDSA signature verification.

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 where the signature is to be written.
Param signature_length:: Size of the signature buffer in bytes.
Return:: EDHOC_SUCCESS on success, otherwise failure.

typedef int (*edhoc_extract_t)(void *user_context, const void *key_id, const uint8_t *salt, size_t salt_len, uint8_t *psuedo_random_key, size_t psuedo_random_key_size, size_t *psuedo_random_key_length)

Cryptographic function for HKDF extracting.

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 psuedo_random_key:: [out] Buffer where the psuedo random key is to be written.
Param psuedo_random_key_size:: Size of the psuedo_random_key buffer in bytes.
Param psuedo_random_key_length:: [out] On success, the number of bytes that make up the psuedo random key.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Cryptographic function for HKDF expanding.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param info:: [in] Information context.
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.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Cryptographic function for 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.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Cryptographic function for 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 where the data that has been authenticated and encrypted.
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.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Cryptographic function for hash computing.

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:: [in] 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.
Return:: EDHOC_SUCCESS on success, otherwise 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 registery 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 cryptographics 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-Helmann key agreement callback.

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)

Callback for external authorization data (EAD) composing.

Param user_context:: [in] User context.
Param message:: Message number for context information. (EAD_1, EAD_2, EAD_3 or EAD_4)
Param ead_token:: [inout] Buffer where the generated EAD tokens is to be written.
Param ead_token_size:: Number of the ead_token.
Param ead_token_len:: [out] On success, the number of written EAD tokens.
Return:: EDHOC_SUCCESS on success, otherwise 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)

Callback for external authorization data (EAD) processing.

Param user_context:: [in] User context.
Param message:: Message number for context information. (EAD_1, EAD_2, EAD_3 or EAD_4)
Param ead_token:: [in] Buffer containing the EAD tokens.
Param ead_token_size:: Number of the received EAD tokens in ead_token.
Return:: EDHOC_SUCCESS on success, otherwise 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

Typedefs

typedef void (*edhoc_logger_t)(void *user_context, const char *name, const uint8_t *buffer, size_t buffer_length): EDHOC logger callback.

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_RECEVIED_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 psuedorandom keys states.

Values:

enumerator EDHOC_PRK_STATE_INVALID: Psuedorandom key invalid.

enumerator EDHOC_PRK_STATE_2E: Psuedorandom key RFC 9528: 4.1.1.1. PRK_2e.

enumerator EDHOC_PRK_STATE_3E2M: Psuedorandom key RFC 9528: 4.1.1.2. PRK_3e2m.

enumerator EDHOC_PRK_STATE_4E3M: Psuedorandom key RFC 9528: 4.1.1.3. PRK_4e3m.

enumerator EDHOC_PRK_STATE_OUT: Psuedorandom key RFC 9528: 4.1.3. PRK_out.

enumerator EDHOC_PRK_STATE_EXPORTER: Psuedorandom 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 Functions

enum edhoc_method EDHOC_PRIVATE(chosen_method): EDHOC chosen method.

enum edhoc_method EDHOC_PRIVATE(method[EDHOC_METHOD_MAX]): EDHOC supported methods.

size_t EDHOC_PRIVATE(method_len): Length of the method buffer.

size_t EDHOC_PRIVATE(chosen_csuite_idx): EDHOC cipher suite chosen index.

struct edhoc_cipher_suite EDHOC_PRIVATE (csuite)[CONFIG_LIBEDHOC_MAX_NR_OF_CIPHER_SUITES]: EDHOC cipher suite buffer.

size_t EDHOC_PRIVATE(csuite_len): Length of the csuite buffer.

struct edhoc_cipher_suite EDHOC_PRIVATE (peer_csuite)[CONFIG_LIBEDHOC_MAX_NR_OF_CIPHER_SUITES]: EDHOC peer cipher suite buffer.

size_t EDHOC_PRIVATE(peer_csuite_len): Length of the peer_csuite buffer.

struct edhoc_connection_id EDHOC_PRIVATE(cid): EDHOC connection identifier.

struct edhoc_connection_id EDHOC_PRIVATE(peer_cid): EDHOC peer connection identifier.

uint8_t EDHOC_PRIVATE (dh_pub_key)[CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY]: EDHOC ephemeral Diffie-Hellman public key.

size_t EDHOC_PRIVATE(dh_pub_key_len): Size of the dh_pub_key buffer in bytes.

uint8_t EDHOC_PRIVATE (dh_priv_key)[CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY]: EDHOC ephemeral Diffie-Hellman private key.

size_t EDHOC_PRIVATE(dh_priv_key_len): Size of the dh_priv_key buffer in bytes.

uint8_t EDHOC_PRIVATE (dh_peer_pub_key)[CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY]: EDHOC ephemeral Diffie-Hellman peer public key.

size_t EDHOC_PRIVATE(dh_peer_pub_key_len): Size of the dh_peer_pub_key buffer in bytes.

uint8_t EDHOC_PRIVATE (dh_secret)[CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY]: EDHOC ephemeral Diffie-Hellman key agreement.

size_t EDHOC_PRIVATE(dh_secret_len): Size of the dh_secret buffer in bytes.

bool EDHOC_PRIVATE(is_init): Is context initialized?

bool EDHOC_PRIVATE(is_oscore_export_allowed): Is OSCORE security session export allowed?

enum edhoc_state_machine EDHOC_PRIVATE(status): EDHOC context state machine.

enum edhoc_message EDHOC_PRIVATE(message): Current processing EDHOC message.

enum edhoc_role EDHOC_PRIVATE(role): EDHOC role.

enum edhoc_th_state EDHOC_PRIVATE(th_state): EDHOC context transcript hash state.

uint8_t EDHOC_PRIVATE (th)[CONFIG_LIBEDHOC_MAX_LEN_OF_MAC]: EDHOC context transcript hash buffer.

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

enum edhoc_prk_state EDHOC_PRIVATE(prk_state): EDHOC context pseudorandom key state.

uint8_t EDHOC_PRIVATE (prk)[CONFIG_LIBEDHOC_MAX_LEN_OF_MAC]: EDHOC context pseudorandom key buffer.

size_t EDHOC_PRIVATE(prk_len): Size of the prk buffer in bytes.

struct edhoc_ead EDHOC_PRIVATE(ead): EDHOC interface for external authorization data.

struct edhoc_keys EDHOC_PRIVATE(keys): EDHOC interface for crypographics key operations.

struct edhoc_crypto EDHOC_PRIVATE(crypto): EDHOC interface for crypographics function operations.

struct edhoc_credentials EDHOC_PRIVATE(cred): EDHOC interface for authentication credentials.

struct edhoc_ead_token EDHOC_PRIVATE (ead_token)[CONFIG_LIBEDHOC_MAX_NR_OF_EAD_TOKENS+1]: EDHOC EAD tokens buffer.

size_t EDHOC_PRIVATE(nr_of_ead_tokens): Length of the ead_token buffer.

void *EDHOC_PRIVATE(user_ctx): User context.

enum edhoc_error_code EDHOC_PRIVATE(error_code): EDHOC error code.

Public Members

edhoc_logger_t logger: User logger callback.

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 identifer encoding type.

int32_t id_cred_int: Buffer containing credentials identifer integer representation.

uint8_t id_cred_bstr[CONFIG_LIBEDHOC_MAX_LEN_OF_CRED_KEY_ID + 1]: Buffer containing credentials identifer 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)

CBOR integer memory requirements.

Parameters:: value – Raw integer value.
Returns:: Number of bytes.

size_t edhoc_cbor_tstr_oh(size_t length)

CBOR text stream overhead.

Parameters:: length – Length of buffer to CBOR as tstr.
Returns:: Number of overhead bytes.

size_t edhoc_cbor_bstr_oh(size_t length)

CBOR byte stream overhead.

Parameters:: length – Length of buffer to CBOR as bstr.
Returns:: Number of overhead bytes.

size_t edhoc_cbor_map_oh(size_t items)

CBOR map overhead.

Parameters:: items – Number of items for map.
Returns:: Number of overhead bytes.

size_t edhoc_cbor_array_oh(size_t items)

CBOR array overhead.

Parameters:: items – Number of items for array.
Returns:: Number of overhead bytes.

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.

Returns:

EDHOC_SUCCESS on success, otherwise failure.

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

Cborise items required by MAC 2/3 context.

Parameters:

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

Returns:

EDHOC_SUCCESS on success, otherwise 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.

Returns:

EDHOC_SUCCESS on success, otherwise 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.

Returns:

EDHOC_SUCCESS on success, otherwise 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.

Returns:

EDHOC_SUCCESS on success, otherwise 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.

Returns:

EDHOC_SUCCESS on success, otherwise 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.

Returns:

EDHOC_SUCCESS on success, otherwise failure.