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

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 – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman operation failed.

  • EDHOC_ERROR_EAD_COMPOSE_FAILURE – EAD compose callback failed.

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

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_MSG_1_PROCESS_FAILURE – EDHOC message processing failed.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_EAD_PROCESS_FAILURE – EAD process callback failed.

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 – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Transcript hash computation failed.

  • EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman operation failed.

  • EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials operation failed.

  • EDHOC_ERROR_EAD_COMPOSE_FAILURE – EAD compose callback failed.

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

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.

  • EDHOC_ERROR_MSG_2_PROCESS_FAILURE – EDHOC message processing failed.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Transcript hash computation failed.

  • EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Ephemeral Diffie-Hellman operation failed.

  • EDHOC_ERROR_INVALID_MAC_2 – MAC_2 verification failed.

  • EDHOC_ERROR_INVALID_SIGN_OR_MAC_2 – Signature_or_MAC_2 verification failed.

  • EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials operation failed.

  • EDHOC_ERROR_EAD_PROCESS_FAILURE – EAD process callback failed.

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 – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Transcript hash computation failed.

  • EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

  • EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials operation failed.

  • EDHOC_ERROR_EAD_COMPOSE_FAILURE – EAD compose callback failed.

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

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_MSG_3_PROCESS_FAILURE – EDHOC message processing failed.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_TRANSCRIPT_HASH_FAILURE – Transcript hash computation failed.

  • EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

  • EDHOC_ERROR_INVALID_MAC_3 – MAC_3 verification failed.

  • EDHOC_ERROR_INVALID_SIGN_OR_MAC_3 – Signature_or_MAC_3 verification failed.

  • EDHOC_ERROR_CREDENTIALS_FAILURE – Authentication credentials operation failed.

  • EDHOC_ERROR_EAD_PROCESS_FAILURE – EAD process callback failed.

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 – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR encoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_EAD_COMPOSE_FAILURE – EAD compose callback failed.

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

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_MSG_4_PROCESS_FAILURE – EDHOC message 4 processing failed.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_EAD_PROCESS_FAILURE – EAD process callback failed.

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 – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.

  • 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 – Length of the message_error in bytes.

  • error_code – [out] EDHOC error code.

  • error_info – [out] EDHOC error information.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – One or more input parameters are invalid.

  • EDHOC_ERROR_BAD_STATE – Internal context state is incorrect.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_NOT_PERMITTED – Operation not permitted in the current configuration.

  • EDHOC_ERROR_CBOR_FAILURE – CBOR decoding failure.