Authentication Credentials

The credentials interface lets the application supply its own credential (CRED_I or CRED_R) and verify the peer’s credential. libedhoc does not embed credential storage or validation logic: the user controls how credentials are looked up, verified (including CRL checks) and persisted in the application context.

Supported credential identifications (from the COSE IANA registry) are kid, x5chain and x5t.

Header file: include/edhoc_credentials.h
group EDHOC authentication credentials interface

Typedefs

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

Fetch local authentication credentials.

Called by the library to obtain the local party’s authentication credentials (keys, certificates) for composing EDHOC messages.

Param user_context:

[in] User context.

Param credentials:

[out] Authentication credentials to populate.

Retval EDHOC_SUCCESS:

Success.

Return:

Negative error code on 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)

Verify peer authentication credentials.

Called by the library to let the application verify the peer’s authentication credentials (e.g., certificate chain validation, revocation checks) and provide the peer’s public key.

Param user_context:

[in] User context.

Param credentials:

[inout] Peer authentication credentials to verify.

Param public_key_reference:

[out] On success, set to point to the peer’s public key.

Param public_key_length:

[out] On success, the number of bytes that make up the public key.

Retval EDHOC_SUCCESS:

Success.

Return:

Negative error code on 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.

See also

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.

  • are credentials CBOR-encoded: cred_is_cbor.

  • encoding type of key identifier: 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 be written for further EDHOC processing.

Public Members

const uint8_t *cred

Credentials buffer.

size_t cred_len

Size of the cred buffer in bytes.

bool cred_is_cbor

Are credentials CBOR-encoded? 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 be 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.