Helpers, Macros and Utilities

This page collects the optional, ready-made helpers shipped under helpers/ together with small utility groups from the core headers.

Cipher suite 0

Header file: helpers/include/edhoc_cipher_suite_0.h
group EDHOC cipher suite 0 API

Functions

const struct edhoc_crypto *edhoc_cipher_suite_0_get_crypto(void)

Get EDHOC crypto structure for cipher suite 0.

Returns a pointer to the cryptographic operations structure implementing cipher suite 0 algorithms (AES-CCM-16-64-128, SHA-256, X25519, EdDSA).

Returns:

Pointer to cipher suite 0 crypto operations structure.

const struct edhoc_keys *edhoc_cipher_suite_0_get_keys(void)

Get EDHOC keys structure for cipher suite 0.

Returns a pointer to the key management operations structure implementing cipher suite 0 key handling.

Returns:

Pointer to cipher suite 0 keys operations structure.

const struct edhoc_cipher_suite *edhoc_cipher_suite_0_get_suite(void)

Get EDHOC cipher suite descriptor for cipher suite 0.

Returns a pointer to a pre-initialized struct edhoc_cipher_suite holding the canonical algorithm parameters of cipher suite 0 (value 0, AES-CCM-16-64-128, SHA-256, X25519, EdDSA).

Returns:

Pointer to cipher suite 0 descriptor.

int edhoc_cipher_suite_0_key_import(void *user_context, enum edhoc_key_type key_type, const uint8_t *raw_key, size_t raw_key_len, void *kid)

Import cryptographic key into cipher suite 0.

Imports a raw cryptographic key and associates it with a key identifier. The key type determines the algorithm and usage context.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_type – [in] Type of cryptographic key to import.

  • raw_key – [in] Buffer containing the raw key material.

  • raw_key_len – Length of the raw_key buffer in bytes.

  • kid – [out] Key identifier for the imported key.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Key import operation failed.

int edhoc_cipher_suite_0_key_destroy(void *user_context, void *kid)

Destroy cryptographic key.

Securely destroys a previously imported cryptographic key and releases associated resources.

Parameters:

  • user_context – [in] User-provided context pointer.

  • kid – [in] Key identifier of the key to destroy.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Key destroy operation failed.

int edhoc_cipher_suite_0_make_key_pair(void *user_context, const void *key_id, uint8_t *private_key, size_t private_key_size, size_t *private_key_length, uint8_t *public_key, size_t public_key_size, size_t *public_key_length)

Generate ECDH key pair using X25519.

Generates an ephemeral Diffie-Hellman key pair for X25519 elliptic curve.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier for the generated key pair.

  • private_key – [out] Buffer where the private key will be written.

  • private_key_size – Size of the private_key buffer in bytes.

  • private_key_length – [out] On success, length of the generated private key.

  • public_key – [out] Buffer where the public key will be written.

  • public_key_size – Size of the public_key buffer in bytes.

  • public_key_length – [out] On success, length of the generated public key.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key pair generation failed.

int edhoc_cipher_suite_0_key_agreement(void *user_context, const void *key_id, const uint8_t *peer_public_key, size_t peer_public_key_length, uint8_t *shared_secret, size_t shared_secret_size, size_t *shared_secret_length)

Perform ECDH key agreement using X25519.

Computes a shared secret using the local private key and the peer’s public key via X25519 elliptic curve Diffie-Hellman.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the local private key.

  • peer_public_key – [in] Buffer containing the peer’s public key.

  • peer_public_key_length – Length of the peer_public_key buffer in bytes.

  • shared_secret – [out] Buffer where the shared secret will be written.

  • shared_secret_size – Size of the shared_secret buffer in bytes.

  • shared_secret_length – [out] On success, length of the computed shared secret.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key agreement computation failed.

int edhoc_cipher_suite_0_signature(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Generate EdDSA signature.

Creates a digital signature over the input data using EdDSA (Ed25519).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the signing key.

  • input – [in] Buffer containing data to be signed.

  • input_length – Length of the input buffer in bytes.

  • signature – [out] Buffer where the signature will be written.

  • signature_size – Size of the signature buffer in bytes.

  • signature_length – [out] On success, length of the generated signature.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Signature generation failed.

int edhoc_cipher_suite_0_verify(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

Verify EdDSA signature.

Verifies a digital signature over the input data using EdDSA (Ed25519).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the verification key.

  • input – [in] Buffer containing signed data.

  • input_length – Length of the input buffer in bytes.

  • signature – [in] Buffer containing the signature to verify.

  • signature_length – Length of the signature buffer in bytes.

Return values:

  • EDHOC_SUCCESS – Signature verification succeeded.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Signature verification failed.

int edhoc_cipher_suite_0_extract(void *user_context, const void *key_id, const uint8_t *salt, size_t salt_len, uint8_t *pseudo_random_key, size_t pseudo_random_key_size, size_t *pseudo_random_key_length)

HKDF extract using SHA-256.

Performs the HKDF-Extract operation to derive a pseudorandom key from input keying material using SHA-256 as the hash function.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the input keying material.

  • salt – [in] Optional salt value (can be NULL).

  • salt_len – Length of the salt buffer in bytes.

  • pseudo_random_key – [out] Buffer where the PRK will be written.

  • pseudo_random_key_size – Size of the pseudo_random_key buffer in bytes.

  • pseudo_random_key_length – [out] On success, length of the generated PRK.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Extract operation failed.

int edhoc_cipher_suite_0_expand(void *user_context, const void *key_id, const uint8_t *info, size_t info_length, uint8_t *output_keying_material, size_t output_keying_material_length)

HKDF expand using SHA-256.

Performs the HKDF-Expand operation to derive output keying material from a pseudorandom key using SHA-256 as the hash function.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the pseudorandom key (PRK).

  • info – [in] Context and application specific information.

  • info_length – Length of the info buffer in bytes.

  • output_keying_material – [out] Buffer where the OKM will be written.

  • output_keying_material_length – Desired length of output keying material in bytes.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Expand operation failed.

int edhoc_cipher_suite_0_encrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)

AEAD encrypt using AES-CCM-16-64-128.

Encrypts plaintext using AES-CCM with 128-bit key, 64-bit tag, and 13-byte nonce. Provides authenticated encryption with associated data (AEAD).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the encryption key.

  • nonce – [in] Nonce (13 bytes for AES-CCM-16-64-128).

  • nonce_length – Length of the nonce buffer in bytes.

  • additional_data – [in] Additional authenticated data (can be NULL).

  • additional_data_length – Length of the additional_data buffer in bytes.

  • plaintext – [in] Buffer containing plaintext to encrypt.

  • plaintext_length – Length of the plaintext buffer in bytes.

  • ciphertext – [out] Buffer where ciphertext and tag will be written.

  • ciphertext_size – Size of the ciphertext buffer in bytes.

  • ciphertext_length – [out] On success, length of ciphertext plus tag.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Encryption operation failed.

int edhoc_cipher_suite_0_decrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)

AEAD decrypt using AES-CCM-16-64-128.

Decrypts ciphertext using AES-CCM with 128-bit key, 64-bit tag, and 13-byte nonce. Provides authenticated decryption with associated data (AEAD).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the decryption key.

  • nonce – [in] Nonce (13 bytes for AES-CCM-16-64-128).

  • nonce_length – Length of the nonce buffer in bytes.

  • additional_data – [in] Additional authenticated data (can be NULL).

  • additional_data_length – Length of the additional_data buffer in bytes.

  • ciphertext – [in] Buffer containing ciphertext and tag to decrypt.

  • ciphertext_length – Length of the ciphertext buffer in bytes (including tag).

  • plaintext – [out] Buffer where decrypted plaintext will be written.

  • plaintext_size – Size of the plaintext buffer in bytes.

  • plaintext_length – [out] On success, length of the decrypted plaintext.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Decryption or authentication failed.

int edhoc_cipher_suite_0_hash(void *user_context, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)

Compute SHA-256 hash.

Computes the SHA-256 cryptographic hash of the input data.

Parameters:

  • user_context – [in] User-provided context pointer.

  • input – [in] Buffer containing data to hash.

  • input_length – Length of the input buffer in bytes.

  • hash – [out] Buffer where the hash will be written.

  • hash_size – Size of the hash buffer in bytes (must be ≥ 32).

  • hash_length – [out] On success, length of the computed hash (32 bytes).

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Hash computation failed.

Cipher suite 2

Header file: helpers/include/edhoc_cipher_suite_2.h
group EDHOC cipher suite 2 API

For ES256, edhoc_cipher_suite_2_signature and edhoc_cipher_suite_2_verify split a psa_sign_message-style operation into hash, then sign (edhoc_cipher_suite_2_hash, then psa_sign_hash / psa_verify_hash with PSA_ALG_ECDSA(PSA_ALG_SHA_256)), so each step can follow your platform configuration. That helps when moving a large message through the signing path is costly (e.g. some secure elements). The input to those callbacks is still the full COSE Sign1 payload from the library, not an application-supplied digest.

Functions

const struct edhoc_crypto *edhoc_cipher_suite_2_get_crypto(void)

Get EDHOC crypto structure for cipher suite 2.

Returns a pointer to the cryptographic operations structure implementing cipher suite 2 algorithms (AES-CCM-16-64-128, SHA-256, P-256, ES256).

Returns:

Pointer to cipher suite 2 crypto operations structure.

const struct edhoc_keys *edhoc_cipher_suite_2_get_keys(void)

Get EDHOC keys structure for cipher suite 2.

Returns a pointer to the key management operations structure implementing cipher suite 2 key handling.

Returns:

Pointer to cipher suite 2 keys operations structure.

const struct edhoc_cipher_suite *edhoc_cipher_suite_2_get_suite(void)

Get EDHOC cipher suite descriptor for cipher suite 2.

Returns a pointer to a pre-initialized struct edhoc_cipher_suite holding the canonical algorithm parameters of cipher suite 2 (value 2, AES-CCM-16-64-128, SHA-256, P-256, ES256).

Returns:

Pointer to cipher suite 2 descriptor.

int edhoc_cipher_suite_2_key_import(void *user_context, enum edhoc_key_type key_type, const uint8_t *raw_key, size_t raw_key_len, void *kid)

Import cryptographic key into cipher suite 2.

Imports a raw cryptographic key and associates it with a key identifier. The key type determines the algorithm and usage context.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_type – [in] Type of cryptographic key to import.

  • raw_key – [in] Buffer containing the raw key material.

  • raw_key_len – Length of the raw_key buffer in bytes.

  • kid – [out] Key identifier for the imported key.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Key import operation failed.

int edhoc_cipher_suite_2_key_destroy(void *user_context, void *kid)

Destroy cryptographic key.

Securely destroys a previously imported cryptographic key and releases associated resources.

Parameters:

  • user_context – [in] User-provided context pointer.

  • kid – [in] Key identifier of the key to destroy.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Key destroy operation failed.

int edhoc_cipher_suite_2_make_key_pair(void *user_context, const void *key_id, uint8_t *private_key, size_t private_key_size, size_t *private_key_length, uint8_t *public_key, size_t public_key_size, size_t *public_key_length)

Generate ECDH key pair using P-256.

Generates an ephemeral Diffie-Hellman key pair for P-256 (secp256r1) elliptic curve.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier for the generated key pair.

  • private_key – [out] Buffer where the private key will be written.

  • private_key_size – Size of the private_key buffer in bytes.

  • private_key_length – [out] On success, length of the generated private key.

  • public_key – [out] Buffer where the public key will be written.

  • public_key_size – Size of the public_key buffer in bytes.

  • public_key_length – [out] On success, length of the generated public key.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key pair generation failed.

int edhoc_cipher_suite_2_key_agreement(void *user_context, const void *key_id, const uint8_t *peer_public_key, size_t peer_public_key_length, uint8_t *shared_secret, size_t shared_secret_size, size_t *shared_secret_length)

Perform ECDH key agreement using P-256.

Computes a shared secret using the local private key and the peer’s public key via P-256 (secp256r1) elliptic curve Diffie-Hellman.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the local private key.

  • peer_public_key – [in] Buffer containing the peer’s public key.

  • peer_public_key_length – Length of the peer_public_key buffer in bytes.

  • shared_secret – [out] Buffer where the shared secret will be written.

  • shared_secret_size – Size of the shared_secret buffer in bytes.

  • shared_secret_length – [out] On success, length of the computed shared secret.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key agreement computation failed.

int edhoc_cipher_suite_2_signature(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Generate ES256 signature.

Creates a digital signature over the input data using ES256 (ECDSA with P-256 and SHA-256). Uses edhoc_cipher_suite_2_hash for SHA-256, then psa_sign_hash (same outcome as psa_sign_message with PSA_ALG_ECDSA(PSA_ALG_SHA_256); see module

for rationale).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the signing key.

  • input – [in] Buffer containing the full message to be signed (not a digest).

  • input_length – Length of the input buffer in bytes.

  • signature – [out] Buffer where the signature will be written.

  • signature_size – Size of the signature buffer in bytes.

  • signature_length – [out] On success, length of the generated signature.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Signature generation failed.

int edhoc_cipher_suite_2_verify(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

Verify ES256 signature.

Verifies a digital signature over the input data using ES256 (ECDSA with P-256 and SHA-256). Uses edhoc_cipher_suite_2_hash for SHA-256, then psa_verify_hash (see module

).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the verification key.

  • input – [in] Buffer containing the full signed message (not a digest).

  • input_length – Length of the input buffer in bytes.

  • signature – [in] Buffer containing the signature to verify.

  • signature_length – Length of the signature buffer in bytes.

Return values:

  • EDHOC_SUCCESS – Signature verification succeeded.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Signature verification failed.

int edhoc_cipher_suite_2_extract(void *user_context, const void *key_id, const uint8_t *salt, size_t salt_len, uint8_t *pseudo_random_key, size_t pseudo_random_key_size, size_t *pseudo_random_key_length)

HKDF extract using SHA-256.

Performs the HKDF-Extract operation to derive a pseudorandom key from input keying material using SHA-256 as the hash function.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the input keying material.

  • salt – [in] Optional salt value (can be NULL).

  • salt_len – Length of the salt buffer in bytes.

  • pseudo_random_key – [out] Buffer where the PRK will be written.

  • pseudo_random_key_size – Size of the pseudo_random_key buffer in bytes.

  • pseudo_random_key_length – [out] On success, length of the generated PRK.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Extract operation failed.

int edhoc_cipher_suite_2_expand(void *user_context, const void *key_id, const uint8_t *info, size_t info_length, uint8_t *output_keying_material, size_t output_keying_material_length)

HKDF expand using SHA-256.

Performs the HKDF-Expand operation to derive output keying material from a pseudorandom key using SHA-256 as the hash function.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the pseudorandom key (PRK).

  • info – [in] Context and application specific information.

  • info_length – Length of the info buffer in bytes.

  • output_keying_material – [out] Buffer where the OKM will be written.

  • output_keying_material_length – Desired length of output keying material in bytes.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Expand operation failed.

int edhoc_cipher_suite_2_encrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)

AEAD encrypt using AES-CCM-16-64-128.

Encrypts plaintext using AES-CCM with 128-bit key, 64-bit tag, and 13-byte nonce. Provides authenticated encryption with associated data (AEAD).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the encryption key.

  • nonce – [in] Nonce (13 bytes for AES-CCM-16-64-128).

  • nonce_length – Length of the nonce buffer in bytes.

  • additional_data – [in] Additional authenticated data (can be NULL).

  • additional_data_length – Length of the additional_data buffer in bytes.

  • plaintext – [in] Buffer containing plaintext to encrypt.

  • plaintext_length – Length of the plaintext buffer in bytes.

  • ciphertext – [out] Buffer where ciphertext and tag will be written.

  • ciphertext_size – Size of the ciphertext buffer in bytes.

  • ciphertext_length – [out] On success, length of ciphertext plus tag.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Encryption operation failed.

int edhoc_cipher_suite_2_decrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)

AEAD decrypt using AES-CCM-16-64-128.

Decrypts ciphertext using AES-CCM with 128-bit key, 64-bit tag, and 13-byte nonce. Provides authenticated decryption with associated data (AEAD).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the decryption key.

  • nonce – [in] Nonce (13 bytes for AES-CCM-16-64-128).

  • nonce_length – Length of the nonce buffer in bytes.

  • additional_data – [in] Additional authenticated data (can be NULL).

  • additional_data_length – Length of the additional_data buffer in bytes.

  • ciphertext – [in] Buffer containing ciphertext and tag to decrypt.

  • ciphertext_length – Length of the ciphertext buffer in bytes (including tag).

  • plaintext – [out] Buffer where decrypted plaintext will be written.

  • plaintext_size – Size of the plaintext buffer in bytes.

  • plaintext_length – [out] On success, length of the decrypted plaintext.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Decryption or authentication failed.

int edhoc_cipher_suite_2_hash(void *user_context, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)

Compute SHA-256 hash.

Computes the SHA-256 cryptographic hash of the input data.

Parameters:

  • user_context – [in] User-provided context pointer.

  • input – [in] Buffer containing data to hash.

  • input_length – Length of the input buffer in bytes.

  • hash – [out] Buffer where the hash will be written.

  • hash_size – Size of the hash buffer in bytes (must be ≥ 32).

  • hash_length – [out] On success, length of the computed hash (32 bytes).

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Hash computation failed.

Cipher suite 24

Header file: helpers/include/edhoc_cipher_suite_24.h
group EDHOC cipher suite 24 API

For ES384, edhoc_cipher_suite_24_signature and edhoc_cipher_suite_24_verify split a psa_sign_message-style operation into hash, then sign (edhoc_cipher_suite_24_hash, then psa_sign_hash / psa_verify_hash with PSA_ALG_ECDSA(PSA_ALG_SHA_384)), so each step can follow your platform configuration. That helps when moving a large message through the signing path is costly (e.g. some secure elements). The input to those callbacks is still the full COSE Sign1 payload from the library, not an application-supplied digest.

Functions

const struct edhoc_crypto *edhoc_cipher_suite_24_get_crypto(void)

Get EDHOC crypto structure for cipher suite 24.

Returns a pointer to the cryptographic operations structure implementing cipher suite 24 algorithms (A256GCM, SHA-384, P-384, ES384).

Returns:

Pointer to cipher suite 24 crypto operations structure.

const struct edhoc_keys *edhoc_cipher_suite_24_get_keys(void)

Get EDHOC keys structure for cipher suite 24.

Returns a pointer to the key management operations structure implementing cipher suite 24 key handling.

Returns:

Pointer to cipher suite 24 keys operations structure.

const struct edhoc_cipher_suite *edhoc_cipher_suite_24_get_suite(void)

Get EDHOC cipher suite descriptor for cipher suite 24.

Returns a pointer to a pre-initialized struct edhoc_cipher_suite holding the canonical algorithm parameters of cipher suite 24 (value 24, A256GCM, SHA-384, P-384, ES384).

Returns:

Pointer to cipher suite 24 descriptor.

int edhoc_cipher_suite_24_key_import(void *user_context, enum edhoc_key_type key_type, const uint8_t *raw_key, size_t raw_key_len, void *kid)

Import cryptographic key into cipher suite 24.

Imports a raw cryptographic key and associates it with a key identifier. The key type determines the algorithm and usage context.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_type – [in] Type of cryptographic key to import.

  • raw_key – [in] Buffer containing the raw key material.

  • raw_key_len – Length of the raw_key buffer in bytes.

  • kid – [out] Key identifier for the imported key.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Key import operation failed.

int edhoc_cipher_suite_24_key_destroy(void *user_context, void *kid)

Destroy cryptographic key.

Securely destroys a previously imported cryptographic key and releases associated resources.

Parameters:

  • user_context – [in] User-provided context pointer.

  • kid – [in] Key identifier of the key to destroy.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Key destroy operation failed.

int edhoc_cipher_suite_24_make_key_pair(void *user_context, const void *key_id, uint8_t *private_key, size_t private_key_size, size_t *private_key_length, uint8_t *public_key, size_t public_key_size, size_t *public_key_length)

Generate ECDH key pair using P-384.

Generates an ephemeral Diffie-Hellman key pair for P-384 (secp384r1) elliptic curve.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier for the generated key pair.

  • private_key – [out] Buffer where the private key will be written.

  • private_key_size – Size of the private_key buffer in bytes.

  • private_key_length – [out] On success, length of the generated private key.

  • public_key – [out] Buffer where the public key will be written.

  • public_key_size – Size of the public_key buffer in bytes.

  • public_key_length – [out] On success, length of the generated public key.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key pair generation failed.

int edhoc_cipher_suite_24_key_agreement(void *user_context, const void *key_id, const uint8_t *peer_public_key, size_t peer_public_key_length, uint8_t *shared_secret, size_t shared_secret_size, size_t *shared_secret_length)

Perform ECDH key agreement using P-384.

Computes a shared secret using the local private key and the peer’s public key via P-384 (secp384r1) elliptic curve Diffie-Hellman.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the local private key.

  • peer_public_key – [in] Buffer containing the peer’s public key.

  • peer_public_key_length – Length of the peer_public_key buffer in bytes.

  • shared_secret – [out] Buffer where the shared secret will be written.

  • shared_secret_size – Size of the shared_secret buffer in bytes.

  • shared_secret_length – [out] On success, length of the computed shared secret.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_EPHEMERAL_DIFFIE_HELLMAN_FAILURE – Key agreement computation failed.

int edhoc_cipher_suite_24_signature(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Generate ES384 signature.

Creates a digital signature over the input data using ES384 (ECDSA with P-384 and SHA-384). Uses edhoc_cipher_suite_24_hash for SHA-384, then psa_sign_hash (same outcome as psa_sign_message with PSA_ALG_ECDSA(PSA_ALG_SHA_384); see module

for rationale).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the signing key.

  • input – [in] Buffer containing the full message to be signed (not a digest).

  • input_length – Length of the input buffer in bytes.

  • signature – [out] Buffer where the signature will be written.

  • signature_size – Size of the signature buffer in bytes.

  • signature_length – [out] On success, length of the generated signature.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Signature generation failed.

int edhoc_cipher_suite_24_verify(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

Verify ES384 signature.

Verifies a digital signature over the input data using ES384 (ECDSA with P-384 and SHA-384). Uses edhoc_cipher_suite_24_hash for SHA-384, then psa_verify_hash (see module

).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the verification key.

  • input – [in] Buffer containing the full signed message (not a digest).

  • input_length – Length of the input buffer in bytes.

  • signature – [in] Buffer containing the signature to verify.

  • signature_length – Length of the signature buffer in bytes.

Return values:

  • EDHOC_SUCCESS – Signature verification succeeded.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – Signature verification failed.

int edhoc_cipher_suite_24_extract(void *user_context, const void *key_id, const uint8_t *salt, size_t salt_len, uint8_t *pseudo_random_key, size_t pseudo_random_key_size, size_t *pseudo_random_key_length)

HKDF extract using SHA-384.

Performs the HKDF-Extract operation to derive a pseudorandom key from input keying material using SHA-384 as the hash function.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the input keying material.

  • salt – [in] Optional salt value (can be NULL).

  • salt_len – Length of the salt buffer in bytes.

  • pseudo_random_key – [out] Buffer where the PRK will be written.

  • pseudo_random_key_size – Size of the pseudo_random_key buffer in bytes.

  • pseudo_random_key_length – [out] On success, length of the generated PRK.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Extract operation failed.

int edhoc_cipher_suite_24_expand(void *user_context, const void *key_id, const uint8_t *info, size_t info_length, uint8_t *output_keying_material, size_t output_keying_material_length)

HKDF expand using SHA-384.

Performs the HKDF-Expand operation to derive output keying material from a pseudorandom key using SHA-384 as the hash function.

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the pseudorandom key (PRK).

  • info – [in] Context and application specific information.

  • info_length – Length of the info buffer in bytes.

  • output_keying_material – [out] Buffer where the OKM will be written.

  • output_keying_material_length – Desired length of output keying material in bytes.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_CRYPTO_FAILURE – HKDF-Expand operation failed.

int edhoc_cipher_suite_24_encrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)

AEAD encrypt using A256GCM.

Encrypts plaintext using AES-GCM with a 256-bit key, 128-bit tag, and 12-byte nonce. Provides authenticated encryption with associated data (AEAD).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the encryption key.

  • nonce – [in] Nonce (12 bytes for A256GCM).

  • nonce_length – Length of the nonce buffer in bytes.

  • additional_data – [in] Additional authenticated data (can be NULL).

  • additional_data_length – Length of the additional_data buffer in bytes.

  • plaintext – [in] Buffer containing plaintext to encrypt.

  • plaintext_length – Length of the plaintext buffer in bytes.

  • ciphertext – [out] Buffer where ciphertext and tag will be written.

  • ciphertext_size – Size of the ciphertext buffer in bytes.

  • ciphertext_length – [out] On success, length of ciphertext plus tag.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Encryption operation failed.

int edhoc_cipher_suite_24_decrypt(void *user_context, const void *key_id, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)

AEAD decrypt using A256GCM.

Decrypts ciphertext using AES-GCM with a 256-bit key, 128-bit tag, and 12-byte nonce. Provides authenticated decryption with associated data (AEAD).

Parameters:

  • user_context – [in] User-provided context pointer.

  • key_id – [in] Key identifier of the decryption key.

  • nonce – [in] Nonce (12 bytes for A256GCM).

  • nonce_length – Length of the nonce buffer in bytes.

  • additional_data – [in] Additional authenticated data (can be NULL).

  • additional_data_length – Length of the additional_data buffer in bytes.

  • ciphertext – [in] Buffer containing ciphertext and tag to decrypt.

  • ciphertext_length – Length of the ciphertext buffer in bytes (including tag).

  • plaintext – [out] Buffer where decrypted plaintext will be written.

  • plaintext_size – Size of the plaintext buffer in bytes.

  • plaintext_length – [out] On success, length of the decrypted plaintext.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Decryption or authentication failed.

int edhoc_cipher_suite_24_hash(void *user_context, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)

Compute SHA-384 hash.

Computes the SHA-384 cryptographic hash of the input data.

Parameters:

  • user_context – [in] User-provided context pointer.

  • input – [in] Buffer containing data to hash.

  • input_length – Length of the input buffer in bytes.

  • hash – [out] Buffer where the hash will be written.

  • hash_size – Size of the hash buffer in bytes (must be ≥ 48).

  • hash_length – [out] On success, length of the computed hash (48 bytes).

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid input parameter.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Output buffer is too small.

  • EDHOC_ERROR_CRYPTO_FAILURE – Hash computation failed.

Connection identifier helpers

Header file: helpers/include/edhoc_helpers.h
group EDHOC Connection ID Utilities API

Functions

bool edhoc_connection_id_equal(const struct edhoc_connection_id *conn_id_1, const struct edhoc_connection_id *conn_id_2)

Compare two connection identifiers for equality.

Parameters:

  • conn_id_1 – [in] First connection identifier.

  • conn_id_2 – [in] Second connection identifier.

Returns:

true if connection IDs are equal, false otherwise.

Buffer utilities

group EDHOC Buffer Utilities API

Functions

int edhoc_prepend_flow(struct edhoc_prepended_fields *prepended_fields)

Prepend flow indicator (CBOR true) to buffer before EDHOC message.

Prepends EDHOC_CBOR_TRUE to indicate forward flow. The prepend buffer must be initialized with buffer and buffer_size before calling this function.

Note

Initialize prepend buffer directly using struct initialization: 

struct edhoc_prepended_fields prepended_fields = {
    .buffer = buffer,
    .buffer_size = buffer_size,
    .edhoc_message_ptr = buffer,
    .edhoc_message_size = buffer_size
};

Note

After calling edhoc_prepend_recalculate_size(), buffer_size contains the actual used size (prepended + EDHOC message).

Parameters:

prepended_fields – [inout] Prepend buffer structure (must have buffer and buffer_size set).

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Not enough space.

int edhoc_prepend_connection_id(struct edhoc_prepended_fields *prepended_fields, const struct edhoc_connection_id *conn_id)

Prepend connection identifier to buffer before EDHOC message.

Encodes and prepends the connection identifier.

Parameters:

  • prepended_fields – [inout] Prepend buffer structure.

  • conn_id – [in] Connection identifier to prepend.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Not enough space.

  • EDHOC_ERROR_CBOR_FAILURE – Encoding failure.

int edhoc_prepend_recalculate_size(struct edhoc_prepended_fields *prepended_fields)

Recalculate total size after EDHOC message composition.

Recalculates total size after EDHOC message composition and updates buffer_size to reflect the actual used size (prepended + EDHOC message). The EDHOC message length is taken from edhoc_message_size after composition.

Parameters:

prepended_fields – [inout] Prepend buffer structure. On success, buffer_size is updated to the actual used size.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.

  • EDHOC_ERROR_BUFFER_TOO_SMALL – Total size exceeds buffer capacity.

int edhoc_extract_flow_info(struct edhoc_extracted_fields *extracted_fields)

Extract flow information from buffer.

Checks the beginning of the buffer for flow indicators:

  • Empty buffer indicates reverse flow

  • CBOR true (EDHOC_CBOR_TRUE) indicates forward flow

  • Otherwise, no flow indicator present

If a flow indicator is found, it is extracted and the extract buffer is updated to point to the EDHOC message after the indicator. Flow information is stored in the is_forward_flow and is_reverse_flow fields.

Note

Initialize extract buffer directly using struct initialization: 

struct edhoc_extracted_fields extracted_fields = {
    .buffer = buffer,
    .buffer_size = buffer_size,
    .edhoc_message_ptr = buffer,
    .edhoc_message_size = buffer_size
};

Parameters:

extracted_fields – [inout] Extract buffer structure.

Return values:

  • EDHOC_SUCCESS – Success (flow info extracted or buffer is empty).

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.

int edhoc_extract_connection_id(struct edhoc_extracted_fields *extracted_fields)

Extract connection identifier from buffer.

Extracts and decodes a connection identifier from the beginning of the buffer. The connection identifier is stored in the extracted_conn_id field on success. The buffer is advanced to point past the connection ID.

Parameters:

extracted_fields – [inout] Extract buffer structure.

Return values:

  • EDHOC_SUCCESS – Success.

  • EDHOC_ERROR_INVALID_ARGUMENT – Invalid parameters.

  • EDHOC_ERROR_CBOR_FAILURE – Decoding failure.

struct edhoc_prepended_fields
#include <edhoc_helpers.h>

Helper structure for prepending data before EDHOC messages.

Public Members

uint8_t *buffer

Complete buffer including prepended data and EDHOC message.

size_t buffer_size

Total size of the buffer.

uint8_t *edhoc_message_ptr

Pointer to where EDHOC message should be written (after prepended data).

size_t edhoc_message_size

Available size for EDHOC message (after composition, contains actual message length).

struct edhoc_extracted_fields
#include <edhoc_helpers.h>

Helper structure for extracting data from received messages.

Public Members

const uint8_t *buffer

Complete received buffer.

size_t buffer_size

Size of received buffer.

const uint8_t *edhoc_message_ptr

Pointer to EDHOC message (after extracted data).

size_t edhoc_message_size

Size of EDHOC message.

bool is_forward_flow

True if forward flow detected (CBOR true found, set by edhoc_extract_flow_info).

bool is_reverse_flow

True if reverse flow detected (empty buffer, set by edhoc_extract_flow_info).

struct edhoc_connection_id extracted_conn_id

Extracted connection identifier (set by edhoc_extract_connection_id).

Macros

Header file: include/edhoc_macros.h
group EDHOC utility macros

Defines

ARRAY_SIZE(x)

Compute the number of elements in a statically allocated array.

Parameters:

  • x – Array variable (must not be a pointer).

EDHOC_PRIVATE(member)

Access control macro for context structure members.

When EDHOC_ALLOW_PRIVATE_ACCESS is not defined, each member is prefixed with private_ to discourage direct access. Defining EDHOC_ALLOW_PRIVATE_ACCESS removes the prefix, granting direct access.

Parameters:

  • member – Structure member name.

Memory backend

Header file: backends/memory/include/edhoc_backend_memory.h
group EDHOC memory backend

Defines

EDHOC_MEM_BACKEND_STACK
EDHOC_MEM_BACKEND_HEAP
EDHOC_MEM_BACKEND_CUSTOM
CONFIG_LIBEDHOC_MEM_BACKEND
EDHOC_ASSERT_FREE_STACK_SIZE(required_bytes)

Assert that the current thread has at least the requested amount of free stack space.

On Zephyr expands to a runtime check using k_thread_stack_space_get and __ASSERT (only when both CONFIG_THREAD_STACK_INFO and CONFIG_ASSERT are enabled). On every other platform it compiles to a no-op. Only the stack backend evaluates this macro.

Parameters:

  • required_bytes – Minimum number of free stack bytes required.

EDHOC_MEM_ALLOC(type, name, size)

Allocate a working buffer of size elements of type named name.

Depending on the selected backend this expands to a C99 VLA (stack), a calloc/k_calloc call (heap) or a call to the user supplied allocator (custom). The returned buffer is always zero-initialised. For every backend name is usable as a pointer and may be compared against NULL:

  • on the stack backend the allocation cannot fail, so the NULL check is a compile-time-false branch that the optimiser removes,

  • on the heap and custom backends NULL signals an out-of-memory condition and the caller must bail out.

Every successful allocation must be released with EDHOC_MEM_FREE (a no-op on the stack backend).

Parameters:

  • type – Element type.

  • name – Variable name bound to the allocated buffer.

  • size – Number of elements to allocate.

EDHOC_MEM_ALLOC_SIZEOF(name)

Total size in bytes of a buffer allocated with EDHOC_MEM_ALLOC.

Parameters:
EDHOC_MEM_ALLOC_SIZE(x)

Number of elements in a buffer allocated with EDHOC_MEM_ALLOC.

Parameters:
EDHOC_MEM_FREE(name)

Release a buffer allocated with EDHOC_MEM_ALLOC.

No-op on the stack backend. On the heap and custom backends frees the buffer and sets name to NULL so a double free is harmless.

Parameters: