EDHOC Error Codes¶

All API functions return EDHOC_SUCCESS (0) on success or a negative C error code on failure. After a message compose or process failure, call edhoc_error_get_code() to retrieve the EDHOC-level error code carried in (or to be carried in) the on-the-wire error message defined in RFC 9528, Section 6.

Header file: include/edhoc/values.h

Cipher suite negotiation¶

Both roles reach edhoc_error_get_cipher_suites() once EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE is recorded for the session. The own list is always the one given to edhoc_set_cipher_suites(); the peer list is the SUITES_I received in message 1 on the Responder, and the SUITES_R received in the error message on the Initiator.

The Responder reaches it when edhoc_message_1_process() rejects the selected suite, and builds SUITES_R out of the two lists. The Initiator reaches it after decoding that error message:

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

Retrying is a new EDHOC session: reinitialize the context, so that message 1 is composed with a fresh ephemeral key pair (RFC 9528, Section 6.3.1).

Aborted and completed sessions¶

edhoc_message_error_compose() and edhoc_message_error_process() abort the session, so any following message call returns EDHOC_ERROR_BAD_STATE. A completed session is the exception: both return EDHOC_ERROR_BAD_STATE and leave the context untouched, so the exporters keep working. An error message is not authenticated, and the session output may be maintained even if one is received (RFC 9528, Section 5.1).

Error code enumeration¶

group EDHOC error codes

Defines

EDHOC_SUCCESS¶: The action was completed successfully.

EDHOC_ERROR_GENERIC_ERROR¶: No specific error code was assigned. Every internal result starts from this value, so it surfaces only if a failing path forgot to set its own.

EDHOC_ERROR_NOT_SUPPORTED¶: The build or the selected cipher suite cannot perform the requested operation.

EDHOC_ERROR_NOT_PERMITTED¶: The protocol or the current configuration forbids the requested action.

EDHOC_ERROR_BUFFER_TOO_SMALL¶: An output buffer is too small; retry with a larger buffer.

EDHOC_ERROR_BAD_STATE¶: The context is not in a state where the call is valid: a mandatory input is missing, or messages were composed/processed out of order.

EDHOC_ERROR_INVALID_ARGUMENT¶: A function argument is invalid, e.g. a NULL pointer or a zero length.

EDHOC_ERROR_NOT_ENOUGH_MEMORY¶: A working-buffer allocation failed in the configured memory backend.

EDHOC_ERROR_CBOR_FAILURE¶: The bytes are not the CBOR that EDHOC requires, in either direction.

EDHOC_ERROR_CRYPTO_FAILURE¶: The bound crypto backend reported a failure.

EDHOC_ERROR_CREDENTIALS_FAILURE¶: An authentication credentials callback returned an error, or what it produced failed the library’s validation.

EDHOC_ERROR_EAD_COMPOSE_FAILURE¶: The EAD compose callback returned an error, or produced items the library rejects.

EDHOC_ERROR_EAD_PROCESS_FAILURE¶: The EAD process callback returned an error.

EDHOC_ERROR_MSG_1_PROCESS_FAILURE¶: A received EDHOC message 1 decoded, but its content was rejected.

EDHOC_ERROR_MSG_2_PROCESS_FAILURE¶: A received EDHOC message 2 decoded, but its content was rejected.

EDHOC_ERROR_MSG_3_PROCESS_FAILURE¶: A received EDHOC message 3 decoded, but its content was rejected.

EDHOC_ERROR_MSG_4_PROCESS_FAILURE¶: A received EDHOC message 4 decoded, but its content was rejected.

EDHOC_ERROR_EPHEMERAL_KEY_EXCHANGE_FAILURE¶: The ephemeral key exchange failed: key generation, or KEM encapsulation or decapsulation.

EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE¶: Computation of an EDHOC transcript hash (TH_2, TH_3, or TH_4) failed.

EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE¶: Derivation of an EDHOC pseudorandom key (PRK) in the key schedule failed.

EDHOC_ERROR_INVALID_SIGN_OR_MAC_2¶: Signature_or_MAC_2 did not verify: the Responder is not authenticated.

EDHOC_ERROR_INVALID_SIGN_OR_MAC_3¶: Signature_or_MAC_3 did not verify: the Initiator is not authenticated.

Runtime error API¶

group EDHOC errors API

Functions

int edhoc_error_get_code(const struct edhoc_context *edhoc_context, enum edhoc_error_code *error_code)¶

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

Parameters:

edhoc_context – [in] EDHOC context.
error_code – [out] EDHOC error code.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

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_count, int32_t *peer_cipher_suites, size_t peer_cipher_suites_size, size_t *peer_cipher_suites_count)¶

Retrieve the own and peer cipher suites after a cipher suite negotiation error.

Available in either role once EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE is recorded for the session (RFC 9528: 6.3). The own suites are always the ones given to edhoc_set_cipher_suites(); the peer suites are:

the SUITES_I received in message 1, for a Responder that rejected it in edhoc_message_1_process();
the SUITES_R of the error message, for an Initiator that decoded it in edhoc_message_error_process().

The Responder builds SUITES_R for the error message out of the two lists. The Initiator reselects a mutually supported suite (RFC 9528: 6.3.1); the retry is a new EDHOC session, so it needs a reinitialized context and yields a fresh ephemeral key pair.

Parameters:

edhoc_context – [in] EDHOC context.
cipher_suites – [out] Buffer where the own cipher suite values are written.
cipher_suites_size – Size of the cipher_suites buffer in entries.
cipher_suites_count – [out] On success, the number of entries written to cipher_suites.
peer_cipher_suites – [out] Buffer where the peer cipher suite values are written.
peer_cipher_suites_size – Size of the peer_cipher_suites buffer in entries.
peer_cipher_suites_count – [out] On success, the number of entries written to peer_cipher_suites.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).