Exporters

After a successful handshake the EDHOC key schedule yields PRK_out, from which application keys are derived using the PRK exporter. The most common consumer is OSCORE — edhoc_export_oscore_session() returns the Master Secret, Master Salt and the two Sender/Recipient IDs required to bootstrap an OSCORE security context.

A key update (KEY_UPDATE) can be performed on an established context to re-derive PRK_out from fresh entropy without running a new handshake; the OSCORE export must then be re-run to obtain refreshed keys.

Header file: include/edhoc.h
group EDHOC exporters API

Functions

int edhoc_export_prk_exporter(struct edhoc_context *edhoc_context, size_t label, uint8_t *secret, size_t secret_length)

Export derived keying material using the pseudorandom key exporter.

Parameters:

  • edhoc_context – EDHOC context.

  • label – PRK exporter label.

  • secret – [out] Buffer where the generated secret is to be written.

  • secret_length – Size of the secret buffer 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_CBOR_FAILURE – CBOR encoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

int edhoc_export_key_update(struct edhoc_context *edhoc_context, const uint8_t *entropy, size_t entropy_length)

Perform key update for subsequent OSCORE session exports.

Parameters:

  • edhoc_context – EDHOC context.

  • entropy – [in] Buffer containing the entropy for key update.

  • entropy_length – Size of the entropy buffer 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_CBOR_FAILURE – CBOR encoding failure.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.

int edhoc_export_oscore_session(struct edhoc_context *edhoc_context, uint8_t *master_secret, size_t master_secret_length, uint8_t *master_salt, size_t master_salt_length, uint8_t *sender_id, size_t sender_id_size, size_t *sender_id_length, uint8_t *recipient_id, size_t recipient_id_size, size_t *recipient_id_length)

Export the OSCORE security session.

Parameters:

  • edhoc_context – EDHOC context.

  • master_secret – [out] Buffer where the exported master secret is to be written.

  • master_secret_length – Size of the master_secret buffer in bytes.

  • master_salt – [out] Buffer where the exported master salt is to be written.

  • master_salt_length – Size of the master_salt buffer in bytes.

  • sender_id – [out] Buffer where the exported sender id is to be written.

  • sender_id_size – Size of the sender_id buffer in bytes.

  • sender_id_length – [out] On success, the number of bytes that make up the sender id.

  • recipient_id – [out] Buffer where the exported recipient id is to be written.

  • recipient_id_size – Size of the recipient_id buffer in bytes.

  • recipient_id_length – [out] On success, the number of bytes that make up the recipient id.

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_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Cryptographic operation failure.

  • EDHOC_ERROR_PSEUDORANDOM_KEY_FAILURE – Pseudorandom key derivation failed.