EDHOC Messages

The EDHOC handshake consists of four messages — message_1 through message_4 — plus an out-of-band error message. The Initiator composes the odd-numbered messages and the Responder composes the even-numbered ones; the matching process call consumes a message received from the peer.

Header file: include/edhoc/edhoc.h
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. 

  The Initiator composes message 1: it proposes the method (METHOD) and
  cipher suites (SUITES_I) and carries the ephemeral public key G_X, the
  connection identifier C_I and optional EAD_1 (RFC 9528: 5.2.1).
Parameters:

  • edhoc_context – [inout] 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.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_message_1_process(struct edhoc_context *edhoc_context, const uint8_t *message_1, size_t message_1_length)

Process EDHOC message 1. 

  The Responder processes message 1: it reads and verifies that it
  supports the proposed method (METHOD) and cipher suites (SUITES_I),
  then reads the Initiator's ephemeral public key G_X, the connection
  identifier C_I and optional EAD_1 (RFC 9528: 5.2.3).
Parameters:

  • edhoc_context – [inout] EDHOC context.

  • message_1 – [in] Buffer containing the message 1.

  • message_1_length – Length of the message_1 in bytes.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

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. 

  The Responder composes message 2: it carries G_Y (completing the
  ephemeral key exchange) and, encrypted, authenticates the Responder to
  the Initiator with ID_CRED_R and Signature_or_MAC_2 (plus C_R and
  optional EAD_2) (RFC 9528: 5.3.1).
Parameters:

  • edhoc_context – [inout] 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.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_message_2_process(struct edhoc_context *edhoc_context, const uint8_t *message_2, size_t message_2_length)

Process EDHOC message 2. 

  The Initiator processes message 2: it completes the ephemeral key
  exchange from G_Y and verifies the Responder's authentication
  (ID_CRED_R, Signature_or_MAC_2, optional EAD_2) (RFC 9528: 5.3.3).
Parameters:

  • edhoc_context – [inout] EDHOC context.

  • message_2 – [in] Buffer containing the message 2.

  • message_2_length – Length of the message_2 in bytes.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

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. 

  The Initiator composes message 3: it authenticates the Initiator to
  the Responder with the AEAD-encrypted ID_CRED_I and Signature_or_MAC_3
  (plus optional EAD_3), completing mutual authentication
  (RFC 9528: 5.4.1).
Parameters:

  • edhoc_context – [inout] 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.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_message_3_process(struct edhoc_context *edhoc_context, const uint8_t *message_3, size_t message_3_length)

Process EDHOC message 3. 

  The Responder processes message 3: it verifies the Initiator's
  authentication (ID_CRED_I, Signature_or_MAC_3, optional EAD_3),
  completing mutual authentication (RFC 9528: 5.4.3).
Parameters:

  • edhoc_context – [inout] EDHOC context.

  • message_3 – [in] Buffer containing the message 3.

  • message_3_length – Length of the message_3 in bytes.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

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. 

  The Responder composes the optional message 4, giving the Initiator
  explicit key confirmation; it may carry optional EAD_4
  (RFC 9528: 5.5.1).
Parameters:

  • edhoc_context – [inout] 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.

Returns:

Negative error code on failure (EDHOC error codes).

int edhoc_message_4_process(struct edhoc_context *edhoc_context, const uint8_t *message_4, size_t message_4_length)

Process EDHOC message 4. 

  The Initiator processes the optional message 4, obtaining explicit key
  confirmation from the Responder; it may carry optional EAD_4
  (RFC 9528: 5.5.3).
Parameters:

  • edhoc_context – [inout] EDHOC context.

  • message_4 – [in] Buffer containing the message 4.

  • message_4_length – Length of the message_4 in bytes.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).

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 an EDHOC error message. 

  Either party may reply to any EDHOC message with an error message; it
  is fatal and aborts the session (RFC 9528: 6). It carries an error
  code and matching error information.
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.

Returns:

Negative error code on failure (EDHOC error codes).

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 a received EDHOC error message. 

  Decodes a received error message into its error code and error
  information; receiving one indicates the peer aborted the session
  (RFC 9528: 6).
Parameters:

  • message_error – [in] Buffer containing the message error.

  • message_error_length – Length of the message_error in bytes.

  • error_code – [out] EDHOC error code.

  • error_info – [out] EDHOC error information.

Return values:

EDHOC_SUCCESS – Success.

Returns:

Negative error code on failure (EDHOC error codes).