Authentication Credentials¶

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

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

Two callbacks¶

select_local presents the local credential. The library zeroes struct edhoc_credential_selected before every call, so the callback only sets what its label selects; leaving label unset is rejected. CRED belongs to the variant: kid names it in kid.credential, x5t in x509_hash.certificate, and for x5chain the library takes x509_chain.certificate[0], which RFC 9528 fixes as CRED.

authenticate_peer decides whether to trust what the peer sent. It reads struct edhoc_credential_received and, on success, fills struct edhoc_credential_trusted with the credential, its format and the public key to authenticate with. Every buffer in received is a view into the message being processed: valid until the processing call returns, and safe to hand straight back in trusted.

A kid is a byte string on both callbacks. Its compact CBOR integer form (RFC 9528: 3.3.2) is a transport encoding that the library applies and undoes on its own.

Header file: include/edhoc/credentials.h

group EDHOC authentication credentials interface

Enums

enum edhoc_encode_type¶

Encoding of a CBOR item that is either a number or a string.

Values:

enumerator EDHOC_ENCODE_TYPE_INTEGER¶: CBOR integer.

enumerator EDHOC_ENCODE_TYPE_STRING¶: CBOR byte string or text string, depending on the field.

enum edhoc_cose_header¶

COSE header parameter that identifies the credential in ID_CRED (RFC 9528: 3.5.3). Selects the active union member.

Values:

enumerator EDHOC_COSE_HEADER_NONE¶: Not set. A zeroed structure holds this value and is rejected.

enumerator EDHOC_COSE_HEADER_KID¶: ‘kid’ (4): credential referenced by a key identifier, not sent.

enumerator EDHOC_COSE_HEADER_X509_CHAIN¶: ‘x5chain’ (33): X.509 certificate chain sent by value.

enumerator EDHOC_COSE_HEADER_X509_HASH¶: ‘x5t’ (34): X.509 certificate referenced by a fingerprint.

enum edhoc_credential_format¶

How CRED_I / CRED_R is serialized.

Values:

enumerator EDHOC_CREDENTIAL_FORMAT_NONE¶: Not set. A zeroed structure holds this value and is rejected.

enumerator EDHOC_CREDENTIAL_FORMAT_RAW¶: Opaque bytes, wrapped in a CBOR byte string.

enumerator EDHOC_CREDENTIAL_FORMAT_CBOR_ENCODED¶: A ready CBOR item, embedded as it is. Admissible only for ‘kid’.

struct edhoc_cbor_int_or_string¶

#include <credentials.h>

A CBOR item that is either a number or a string.

Public Members

enum edhoc_encode_type encode_type¶: Which member of the union is valid.

int32_t integer¶: Valid for EDHOC_ENCODE_TYPE_INTEGER.

struct edhoc_buffer string¶: Valid for EDHOC_ENCODE_TYPE_STRING.

struct edhoc_credential_selected_kid¶

#include <credentials.h>

Local credential referenced by a key identifier (EDHOC_COSE_HEADER_KID).

Public Members

struct edhoc_buffer identifier¶: Key identifier, at most EDHOC_CREDENTIAL_KID_MAX_LEN bytes.

struct edhoc_buffer credential¶: CRED_I / CRED_R, held out of band by both parties.

enum edhoc_credential_format format¶: Serialization of credential.

struct edhoc_credential_selected_x509_chain¶

#include <credentials.h>

Local credential sent as a certificate chain (EDHOC_COSE_HEADER_X509_CHAIN).

CRED_I / CRED_R is certificate[0], so the library takes it itself.

Public Members

size_t count¶: Number of certificates, 1 to EDHOC_CREDENTIAL_X5CHAIN_CAPACITY.

struct edhoc_buffer certificate[EDHOC_CREDENTIAL_X5CHAIN_CAPACITY]¶: Certificates, in DER, end-entity first.

struct edhoc_credential_selected_x509_hash¶

#include <credentials.h>

Local credential referenced by a certificate fingerprint (EDHOC_COSE_HEADER_X509_HASH).

Public Members

struct edhoc_cbor_int_or_string algorithm¶: Fingerprint algorithm; a name is at most EDHOC_CREDENTIAL_X5T_ALGORITHM_MAX_LEN bytes.

struct edhoc_buffer fingerprint¶: Fingerprint, at most EDHOC_CREDENTIAL_X5T_FINGERPRINT_MAX_LEN bytes.

struct edhoc_buffer certificate¶: CRED_I / CRED_R: the certificate in DER, not sent.

struct edhoc_credential_selected¶

#include <credentials.h>

The local party’s authentication credential, filled in by select_local.

Fill in private_key_id, label and every field of the union member label names.

Warning

The buffers must stay readable until the composing call returns.

Public Members

uint8_t private_key_id[CONFIG_LIBEDHOC_KEY_ID_LEN]¶: Key-store handle of the private signature or static-DH key.

enum edhoc_cose_header label¶: Identification method; selects the active union member.

struct edhoc_credential_selected_kid kid¶: Valid for EDHOC_COSE_HEADER_KID.

struct edhoc_credential_selected_x509_chain x509_chain¶: Valid for EDHOC_COSE_HEADER_X509_CHAIN.

struct edhoc_credential_selected_x509_hash x509_hash¶: Valid for EDHOC_COSE_HEADER_X509_HASH.

struct edhoc_credential_received_kid¶

#include <credentials.h>

Key identifier received from the peer (EDHOC_COSE_HEADER_KID).

Public Members

struct edhoc_buffer identifier¶: Key identifier, the same byte string select_local presented on the other side.

struct edhoc_credential_received_x509_chain¶

#include <credentials.h>

Certificate chain received from the peer (EDHOC_COSE_HEADER_X509_CHAIN).

Public Members

size_t count¶: Number of certificates, end-entity first.

struct edhoc_buffer certificate[EDHOC_CREDENTIAL_X5CHAIN_CAPACITY]¶: Certificates, in DER.

struct edhoc_credential_received_x509_hash¶

#include <credentials.h>

Certificate fingerprint received from the peer (EDHOC_COSE_HEADER_X509_HASH).

Public Members

struct edhoc_cbor_int_or_string algorithm¶: Fingerprint algorithm.

struct edhoc_buffer fingerprint¶: Certificate fingerprint.

struct edhoc_credential_received¶

#include <credentials.h>

ID_CRED_I / ID_CRED_R as received from the peer, passed to authenticate_peer.

Warning

Every buffer points into the message being processed. It may be handed straight back in edhoc_credential_trusted, but stops being valid once the processing call returns.

Public Members

enum edhoc_cose_header label¶: Identification method; selects the active union member. Never EDHOC_COSE_HEADER_NONE.

struct edhoc_credential_received_kid kid¶: Valid for EDHOC_COSE_HEADER_KID.

struct edhoc_credential_received_x509_chain x509_chain¶: Valid for EDHOC_COSE_HEADER_X509_CHAIN.

struct edhoc_credential_received_x509_hash x509_hash¶: Valid for EDHOC_COSE_HEADER_X509_HASH.

struct edhoc_credential_trusted¶

#include <credentials.h>

The peer credential the application vouches for, returned from authenticate_peer.

Filling this in asserts that the application resolved the identifier and validated the credential against its own trust policy (RFC 9528: Appendix D). Fill in all three fields; for EDHOC_COSE_HEADER_X509_CHAIN, CRED is the received end-entity certificate handed back.

Warning

The buffers must stay readable until the processing call returns, so never the callback’s stack. A view from edhoc_credential_received satisfies this.

Public Members

struct edhoc_buffer credential¶: CRED_I / CRED_R.

enum edhoc_credential_format format¶: Serialization of credential.

struct edhoc_buffer public_key¶: Peer authentication key, in the form the cipher suite expects.

struct edhoc_credentials¶

#include <credentials.h>

Authentication credentials interface, bound with edhoc_bind_credentials.

EDHOC delegates credential handling to the application (RFC 9528: 3.5). Both entries are mandatory. The library never takes ownership of a buffer and never frees one.

Public Members

int (*select_local)(void *user_context, const struct edhoc_call_context *call_context, struct edhoc_credential_selected *selected)¶

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.

Param user_context:: [in] User context.
Param call_context:: [in] Parameters of the ongoing session.
Param selected:: [out] Credential to populate.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure (EDHOC error codes).

int (*authenticate_peer)(void *user_context, const struct edhoc_call_context *call_context, const struct edhoc_credential_received *received, struct edhoc_credential_trusted *trusted)¶

Authenticate the peer’s authentication credential.

Called once the peer’s ID_CRED has been decoded:

the Initiator, processing message 2 (ID_CRED_R);
the Responder, processing message 3 (ID_CRED_I).

Look up what received points at, validate it against your trust policy — path building, trust anchors, revocation — and fill in trusted. EDHOC itself only proves possession of the private key (RFC 9528: 3.5, Appendix D).

Param user_context:: [in] User context.
Param call_context:: [in] Parameters of the ongoing session.
Param received:: [in] Peer identification, as received.
Param trusted:: [out] Credential to authenticate with.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure (EDHOC error codes).