Cryptographic Interface¶

libedhoc never touches raw key material directly: all cryptographic primitives are reached through two user-supplied callback interfaces — the keys interface for key import/generation/destruction by identifier, and the operations interface for ECDH, AEAD, hash, HKDF, signing and verification. Private signature keys and static DH keys are referenced by identifier only.

A pair of ready-made bindings for cipher suite 0 and 2 against mbed TLS / PSA Crypto lives under helpers/ and is documented on Helpers, Macros and Utilities.

Header file: include/edhoc_crypto.h

Keys¶

group EDHOC interface for cryptographic keys

Typedefs

typedef int (*edhoc_import_key_t)(void *user_context, enum edhoc_key_type key_type, const uint8_t *raw_key, size_t raw_key_length, void *key_id)¶

Import a cryptographic key and obtain its identifier.

Param user_context:: [in] User context.
Param key_type:: Requested key type.
Param raw_key:: [in] Raw key material.
Param raw_key_length:: Size of the raw_key buffer in bytes.
Param key_id:: [out] Key identifier.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_destroy_key_t)(void *user_context, void *key_id)¶

Destroy a previously imported cryptographic key.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

Enums

enum edhoc_key_type¶

EDHOC key types for cryptographic keys interface.

Values:

enumerator EDHOC_KT_MAKE_KEY_PAIR¶: Key type for generation of ephemeral Diffie-Hellman key pair.

enumerator EDHOC_KT_KEY_AGREEMENT¶: Key type for Diffie-Hellman keys agreement.

enumerator EDHOC_KT_SIGNATURE¶: Key type for signing.

enumerator EDHOC_KT_VERIFY¶: Key type for signature verification.

enumerator EDHOC_KT_EXTRACT¶: Key type for HKDF extract.

enumerator EDHOC_KT_EXPAND¶: Key type for HKDF expand.

enumerator EDHOC_KT_ENCRYPT¶: Key type for symmetric authenticated encryption.

enumerator EDHOC_KT_DECRYPT¶: Key type for symmetric authenticated decryption.

struct edhoc_keys¶

#include <edhoc_crypto.h>

Bind structure for cryptographic key identifiers.

Public Members

edhoc_import_key_t import_key¶: Import cryptographic key callback.

edhoc_destroy_key_t destroy_key¶: Destroy cryptographic key callback.

Operations¶

group EDHOC interface for cryptographic operations

Typedefs

typedef int (*edhoc_make_key_pair_t)(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 an ephemeral ECDH key pair.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param private_key:: [out] Private ephemeral ECDH key.
Param private_key_size:: Size of the private_key buffer in bytes.
Param private_key_length:: [out] On success, the number of bytes that make up the ECDH private key.
Param public_key:: [out] Public ephemeral ECDH key.
Param public_key_size:: Size of the public_key buffer in bytes.
Param public_key_length:: [out] On success, the number of bytes that make up the ECDH public key.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_key_agreement_t)(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)¶

Compute ECDH key agreement (shared secret).

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param peer_public_key:: [in] Peer public ECDH key.
Param peer_public_key_length:: Size of the peer_public_key buffer in bytes.
Param shared_secret:: [out] ECDH shared secret.
Param shared_secret_size:: Size of the shared_secret buffer in bytes.
Param shared_secret_length:: [out] On success, the number of bytes that make up the ECDH shared secret.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_signature_t)(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 a digital signature.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param input:: [in] Input message to sign.
Param input_length:: Size of the input buffer in bytes.
Param signature:: [out] Buffer where the signature is to be written.
Param signature_size:: Size of the signature buffer in bytes.
Param signature_length:: [out] On success, the number of bytes that make up the signature.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_verify_t)(void *user_context, const void *key_id, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)¶

Verify a digital signature.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param input:: [in] Input message to verify.
Param input_length:: Size of the input buffer in bytes.
Param signature:: [in] Buffer containing the signature to verify.
Param signature_length:: Size of the signature buffer in bytes.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_extract_t)(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)¶

Perform HKDF-Extract.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param salt:: [in] Salt for extract.
Param salt_len:: Size of the salt buffer in bytes.
Param pseudo_random_key:: [out] Buffer where the pseudorandom key is to be written.
Param pseudo_random_key_size:: Size of the pseudo_random_key buffer in bytes.
Param pseudo_random_key_length:: [out] On success, the number of bytes that make up the pseudorandom key.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_expand_t)(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)¶

Perform HKDF-Expand.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param info:: [in] Context and application-specific information.
Param info_length:: Size of the info buffer in bytes.
Param output_keying_material:: [out] Buffer where the output keying material is to be written.
Param output_keying_material_length:: Size of the output_keying_material buffer in bytes.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_encrypt_t)(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)¶

Perform AEAD encryption.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param nonce:: [in] Nonce or IV to use.
Param nonce_length:: Size of the nonce buffer in bytes.
Param additional_data:: [in] Additional data that will be authenticated but not encrypted.
Param additional_data_length:: Size of the additional_data buffer in bytes.
Param plaintext:: [in] Data that will be authenticated and encrypted.
Param plaintext_length:: Size of the plaintext buffer in bytes.
Param ciphertext:: [out] Buffer where the authenticated and encrypted data is to be written.
Param ciphertext_size:: Size of the ciphertext buffer in bytes.
Param ciphertext_length:: [out] On success, the number of bytes that make up the ciphertext.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_decrypt_t)(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)¶

Perform AEAD decryption.

Param user_context:: [in] User context.
Param key_id:: [in] Key identifier.
Param nonce:: [in] Nonce or IV to use.
Param nonce_length:: Size of the nonce buffer in bytes.
Param additional_data:: [in] Additional data that will be authenticated but not encrypted.
Param additional_data_length:: Size of the additional_data buffer in bytes.
Param ciphertext:: [in] Buffer containing the authenticated and encrypted data.
Param ciphertext_length:: Size of the ciphertext buffer in bytes.
Param plaintext:: [out] Buffer where the decrypted data is to be written.
Param plaintext_size:: Size of the plaintext buffer in bytes.
Param plaintext_length:: [out] On success, the number of bytes that make up the plaintext.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

typedef int (*edhoc_hash_t)(void *user_context, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)¶

Compute a cryptographic hash.

Param user_context:: [in] User context.
Param input:: [in] Input message to hash.
Param input_length:: Size of the input buffer in bytes.
Param hash:: [out] Buffer where the hash is to be written.
Param hash_size:: Size of the hash buffer in bytes.
Param hash_length:: [out] On success, the number of bytes that make up the hash.
Retval EDHOC_SUCCESS:: Success.
Return:: Negative error code on failure.

struct edhoc_cipher_suite¶

#include <edhoc_crypto.h>

Structure for cipher suite value and related algorithms lengths in bytes.

Public Members

int32_t value¶: Cipher suite IANA registry value.

size_t aead_key_length¶: EDHOC AEAD algorithm key length in bytes.

size_t aead_tag_length¶: EDHOC AEAD algorithm tag length in bytes.

size_t aead_iv_length¶: EDHOC AEAD algorithm iv length in bytes.

size_t hash_length¶: EDHOC hash algorithm: hash length in bytes.

size_t mac_length¶: EDHOC MAC length in bytes.

size_t ecc_key_length¶: EDHOC ECC algorithm: key length in bytes.

size_t ecc_sign_length¶: EDHOC ECC algorithm: signature length in bytes.

struct edhoc_crypto¶

#include <edhoc_crypto.h>

Bind structure for cryptographic operations.

Public Members

edhoc_make_key_pair_t make_key_pair¶: Cryptographic function callback for generate ephemeral Diffie-Hellman key pair.

edhoc_key_agreement_t key_agreement¶: Cryptographic function callback for Diffie-Hellman key agreement.

edhoc_signature_t signature¶: Cryptographic function callback for signing.

edhoc_verify_t verify¶: Cryptographic function callback for signature verification.

edhoc_extract_t extract¶: Cryptographic function callback for HKDF extract.

edhoc_expand_t expand¶: Cryptographic function callback for HKDF expand.

edhoc_encrypt_t encrypt¶: Cryptographic function callback for symmetric authenticated encryption.

edhoc_decrypt_t decrypt¶: Cryptographic function callback for symmetric authenticated decryption.

edhoc_hash_t hash¶: Cryptographic function callback for hash computing.