edhoc 1.0.1 → 1.0.2

package/external/libedhoc/include/edhoc_context.h

@@ -0,0 +1,318 @@
+/**
+ * \file    edhoc_context.h
+ * \author  Kamil Kielbasa
+ * \brief   EDHOC context.
+ * \version 0.4
+ * \date    2024-01-01
+ * 
+ * \copyright Copyright (c) 2024
+ * 
+ */
+
+/* Header guard ------------------------------------------------------------ */
+#ifndef EDHOC_CONTEXT_H
+#define EDHOC_CONTEXT_H
+
+/* Include files ----------------------------------------------------------- */
+
+/* Standard library headers: */
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+/* EDHOC headers: */
+#include "edhoc_credentials.h"
+#include "edhoc_crypto.h"
+#include "edhoc_ead.h"
+#include "edhoc_macros.h"
+#include "edhoc_values.h"
+
+/* Defines ----------------------------------------------------------------- */
+
+/* Maximum length in bytes of key identifier used for cryptographics keys. */
+#ifndef EDHOC_KID_LEN
+#error "Lack of defined key ID length"
+#endif
+
+/* Maximum number of cipher suites available to store in context. */
+#ifndef EDHOC_MAX_CSUITES_LEN
+#error "Lack of defined cipher suites length"
+#endif
+
+/* Maximum length in bytes of connection identifier encoded as byte string. */
+#ifndef EDHOC_MAX_CID_LEN
+#error "Lack of defined connection ID length"
+#endif
+
+/* Maximum length in bytes of ECC point. */
+#ifndef EDHOC_MAX_ECC_KEY_LEN
+#error "Lack of defined length for ellipic curve point X coordinate"
+#endif
+
+/* Maximum length in bytes of PRK and TH buffer. */
+#ifndef EDHOC_MAX_MAC_LEN
+#error "Lack of defined hash length"
+#endif
+
+/* Maximum number of EAD tokens available to store in context. */
+#ifndef EDHOC_MAX_NR_OF_EAD_TOKENS
+#error "Lack of defined external authorization data"
+#endif
+
+/* Maximum number of certifices in COSE X.509 chain. */
+#ifndef EDHOC_MAX_NR_OF_CERTS_IN_X509_CHAIN
+#error "Lack of defined maximum number of certificates in COSE X.509 chain"
+#endif
+
+/* Types and type definitions ---------------------------------------------- */
+
+/** \defgroup edhoc-context EDHOC context
+ * @{
+ */
+
+/**
+ * \brief RFC 9528: Appendix I. Example Protocol State Machine.
+ */
+enum edhoc_state_machine {
+	/** State machine - start. */
+	EDHOC_SM_START,
+	/** State machine - aborted. */
+	EDHOC_SM_ABORTED,
+
+	/* Responder: */
+
+	/** State machine - received message 1. */
+	EDHOC_SM_RECEIVED_M1,
+	/** State machine - verified message 1. */
+	EDHOC_SM_VERIFIED_M1,
+
+	/* Initiator: */
+
+	/** State machine - waiting for message 2. */
+	EDHOC_SM_WAIT_M2,
+	/** State machine - received message 2. */
+	EDHOC_SM_RECEIVED_M2,
+	/** State machine - verified message 2. */
+	EDHOC_SM_VERIFIED_M2,
+
+	/* Responder: */
+
+	/** State machine - waiting for message 3. */
+	EDHOC_SM_WAIT_M3,
+	/** State machine - received message 3. */
+	EDHOC_SM_RECEIVED_M3,
+
+	/* Initiator: */
+
+	/** State machine - received message 4. */
+	EDHOC_SM_RECEVIED_M4,
+
+	/** State machine - completed. */
+	EDHOC_SM_COMPLETED,
+	/** State machine - persisted. */
+	EDHOC_SM_PERSISTED,
+};
+
+/**
+ * \brief RFC 9528: 3.2. Method.
+ */
+enum edhoc_method {
+	/** Initiator signature Key to responder signature Key. */
+	EDHOC_METHOD_0 = 0,
+	/** Initiator signature Key to responder static DH Key. */
+	EDHOC_METHOD_1 = 1,
+	/** Initiator static DH Key to responder signature Key. */
+	EDHOC_METHOD_2 = 2,
+	/** Initiator static DH Key to responder static DH Key. */
+	EDHOC_METHOD_3 = 3,
+};
+
+/**
+ * \brief EDHOC transcript hashes states.
+ */
+enum edhoc_th_state {
+	/** Transcript hash invalid. */
+	EDHOC_TH_STATE_INVALID,
+	/** Transcript hash 1. */
+	EDHOC_TH_STATE_1,
+	/** Transcript hash 2. */
+	EDHOC_TH_STATE_2,
+	/** Transcript hash 3. */
+	EDHOC_TH_STATE_3,
+	/** Transcript hash 4. */
+	EDHOC_TH_STATE_4,
+};
+
+/**
+ * \brief EDHOC psuedorandom keys states.
+ */
+enum edhoc_prk_state {
+	/** Psuedorandom key invalid. */
+	EDHOC_PRK_STATE_INVALID,
+	/** Psuedorandom key RFC 9528: 4.1.1.1. PRK_2e. */
+	EDHOC_PRK_STATE_2E,
+	/** Psuedorandom key RFC 9528: 4.1.1.2. PRK_3e2m. */
+	EDHOC_PRK_STATE_3E2M,
+	/** Psuedorandom key RFC 9528: 4.1.1.3. PRK_4e3m. */
+	EDHOC_PRK_STATE_4E3M,
+	/** Psuedorandom key RFC 9528: 4.1.3. PRK_out. */
+	EDHOC_PRK_STATE_OUT,
+	/** Psuedorandom key RFC 9528: 4.2.1. EDHOC_Exporter. */
+	EDHOC_PRK_STATE_EXPORTER,
+};
+
+/**
+ * \brief EDHOC logger callback.
+ */
+typedef void (*edhoc_logger_t)(void *user_context, const char *name,
+			       const uint8_t *buffer, size_t buffer_length);
+
+/**
+ * \brief EDHOC connection identifier encoding type.
+ */
+enum edhoc_connection_id_type {
+	/** Encode connection identifier as CBOR integer. */
+	EDHOC_CID_TYPE_ONE_BYTE_INTEGER,
+	/** Encode connection identifier as CBOR byte string. */
+	EDHOC_CID_TYPE_BYTE_STRING,
+};
+
+/**
+ * \brief RFC 9528: 3.3.2. Representation of Byte String Identifiers.
+ */
+struct edhoc_connection_id {
+	/** Encoding type of connection identifier. 
+         *
+         * It must follow representation of byte string identifiers described in RFC 9528: 3.3.2. */
+	enum edhoc_connection_id_type encode_type;
+
+	/** Connection identifier as cbor integer. */
+	int8_t int_value;
+
+	/** Connection identifier as cbor byte string buffer. */
+	uint8_t bstr_value[EDHOC_MAX_CID_LEN + 1];
+	/** Size of the \p bstr_value buffer in bytes. */
+	size_t bstr_length;
+};
+
+/**
+ * \brief EDHOC error code. RFC 9528: 6. Error Handling.
+ */
+enum edhoc_error_code {
+	/** RFC 9528: 6.1. Success. */
+	EDHOC_ERROR_CODE_SUCCESS = 0,
+	/** RFC 9528: 6.2. Unspecified Error. */
+	EDHOC_ERROR_CODE_UNSPECIFIED_ERROR = 1,
+	/** RFC 9528: 6.3. Wrong Selected Cipher Suite. */
+	EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE = 2,
+	/** RFC 9528: 6.4. Unknown Credential Referenced. */
+	EDHOC_ERROR_CODE_UNKNOWN_CREDENTIAL_REFERENCED = 3,
+};
+
+/**
+ * \brief EDHOC error information. RFC 9528: 6. Error Handling.
+ */
+struct edhoc_error_info {
+	union {
+		/** Pointer used only for error code: \ref EDHOC_ERROR_CODE_UNSPECIFIED_ERROR. */
+		char *text_string;
+		/** Pointer used only for error code: \ref EDHOC_ERROR_CODE_WRONG_SELECTED_CIPHER_SUITE. */
+		int32_t *cipher_suites;
+	};
+
+	/** Total number of entries from: \p text_string or \p cipher_suites. */
+	size_t total_entries;
+	/** Number of written entries to: \p text_string or \p cipher_suites. */
+	size_t written_entries;
+};
+
+/**
+ * \brief EDHOC context.
+ */
+struct edhoc_context {
+	/** EDHOC method. */
+	enum edhoc_method EDHOC_PRIVATE(method);
+
+	/** EDHOC cipher suite chosen index. */
+	size_t EDHOC_PRIVATE(chosen_csuite_idx);
+	/** EDHOC cipher suite buffer. */
+	struct edhoc_cipher_suite EDHOC_PRIVATE(csuite)[EDHOC_MAX_CSUITES_LEN];
+	/** Length of the \p csuite buffer. */
+	size_t EDHOC_PRIVATE(csuite_len);
+
+	/** EDHOC connection identifier. */
+	struct edhoc_connection_id EDHOC_PRIVATE(cid);
+	/** EDHOC peer connection identifier. */
+	struct edhoc_connection_id EDHOC_PRIVATE(peer_cid);
+
+	/** EDHOC ephemeral Diffie-Hellman public key. */
+	uint8_t EDHOC_PRIVATE(dh_pub_key)[EDHOC_MAX_ECC_KEY_LEN];
+	/** Size of the \p dh_pub_key buffer in bytes. */
+	size_t EDHOC_PRIVATE(dh_pub_key_len);
+	/** EDHOC ephemeral Diffie-Hellman private key. */
+	uint8_t EDHOC_PRIVATE(dh_priv_key)[EDHOC_MAX_ECC_KEY_LEN];
+	/** Size of the \p dh_priv_key buffer in bytes. */
+	size_t EDHOC_PRIVATE(dh_priv_key_len);
+
+	/** EDHOC ephemeral Diffie-Hellman peer public key. */
+	uint8_t EDHOC_PRIVATE(dh_peer_pub_key)[EDHOC_MAX_ECC_KEY_LEN];
+	/** Size of the \p dh_peer_pub_key buffer in bytes. */
+	size_t EDHOC_PRIVATE(dh_peer_pub_key_len);
+	/** EDHOC ephemeral Diffie-Hellman key agreement. */
+	uint8_t EDHOC_PRIVATE(dh_secret)[EDHOC_MAX_ECC_KEY_LEN];
+	/** Size of the \p dh_secret buffer in bytes. */
+	size_t EDHOC_PRIVATE(dh_secret_len);
+
+	/** Is context initialized? */
+	bool EDHOC_PRIVATE(is_init);
+	/** Is OSCORE security session export allowed? */
+	bool EDHOC_PRIVATE(is_oscore_export_allowed);
+	/** EDHOC context state machine. */
+	enum edhoc_state_machine EDHOC_PRIVATE(status);
+
+	/** EDHOC context transcript hash state. */
+	enum edhoc_th_state EDHOC_PRIVATE(th_state);
+	/** EDHOC context transcript hash buffer. */
+	uint8_t EDHOC_PRIVATE(th)[EDHOC_MAX_MAC_LEN];
+	/** Size of the \p th buffer in bytes. */
+	size_t EDHOC_PRIVATE(th_len);
+
+	/** EDHOC context pseudorandom key state. */
+	enum edhoc_prk_state EDHOC_PRIVATE(prk_state);
+	/** EDHOC context pseudorandom key buffer. */
+	uint8_t EDHOC_PRIVATE(prk)[EDHOC_MAX_MAC_LEN];
+	/** Size of the \p prk buffer in bytes. */
+	size_t EDHOC_PRIVATE(prk_len);
+
+	/** EDHOC interface for external authorization data. */
+	struct edhoc_ead EDHOC_PRIVATE(ead);
+	/** EDHOC interface for crypographics key operations. */
+	struct edhoc_keys EDHOC_PRIVATE(keys);
+	/** EDHOC interface for crypographics function operations. */
+	struct edhoc_crypto EDHOC_PRIVATE(crypto);
+	/** EDHOC interface for authentication credentials. */
+	struct edhoc_credentials EDHOC_PRIVATE(cred);
+
+	/** EDHOC EAD tokens buffer. */
+	struct edhoc_ead_token
+		EDHOC_PRIVATE(ead_token)[EDHOC_MAX_NR_OF_EAD_TOKENS + 1];
+	/** Length of the \p ead_token buffer. */
+	size_t EDHOC_PRIVATE(nr_of_ead_tokens);
+
+	/** User context. */
+	void *EDHOC_PRIVATE(user_ctx);
+
+	/** EDHOC error code. */
+	enum edhoc_error_code EDHOC_PRIVATE(error_code);
+
+	/** User logger callback. */
+	edhoc_logger_t logger;
+};
+
+/* Module interface variables and constants -------------------------------- */
+/* Extern variables and constant declarations ------------------------------ */
+/* Module interface function declarations ---------------------------------- */
+
+/**@}*/
+
+#endif /* EDHOC_CONTEXT_H */

package/external/libedhoc/include/edhoc_credentials.h

@@ -0,0 +1,217 @@
+/**
+ * \file    edhoc_credentials.h
+ * \author  Kamil Kielbasa
+ * \brief   EDHOC authentication credentials interface.
+ * \version 0.4
+ * \date    2024-01-01
+ * 
+ * \copyright Copyright (c) 2024
+ * 
+ */
+
+/* Header guard ------------------------------------------------------------ */
+#ifndef EDHOC_CREDENTIALS_H
+#define EDHOC_CREDENTIALS_H
+
+/* Include files ----------------------------------------------------------- */
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+/* Defines ----------------------------------------------------------------- */
+/* Types and type definitions ---------------------------------------------- */
+
+/** \defgroup edhoc-interface-credentials EDHOC interface credentials
+ * @{
+ */
+
+/**
+ * \brief CBOR encoding type where we can choose between integer or byte string.
+ */
+enum edhoc_encode_type {
+	/** Encode as CBOR integer. */
+	EDHOC_ENCODE_TYPE_INTEGER,
+	/** Encode as CBOR byte string. */
+	EDHOC_ENCODE_TYPE_BYTE_STRING,
+};
+
+/**
+ * \brief Supported IANA COSE header labels.
+ *
+ * \ref https://www.iana.org/assignments/cose/cose.xhtml
+ */
+enum edhoc_cose_header {
+	/** Authentication credentials identified by key identifier. */
+	EDHOC_COSE_HEADER_KID = 4,
+	/** Authentication credentials identified by an ordered chain of X.509 certificates. */
+	EDHOC_COSE_HEADER_X509_CHAIN = 33,
+	/** Authentication credentials identified by hash of an X.509 certificate. */
+	EDHOC_COSE_HEADER_X509_HASH = 34,
+};
+
+/**
+ * \brief Key identifier authentication method.
+ *
+ * \section fetch-kid For fetch callback we need to fill:
+ * - any type of credentials:           \p cred and \p cred_len.
+ * - is credentials cborised:           \p cred_is_cbor.
+ * - encoding type of key identifer:    \p encode_type.
+ * - key identifier:                    \p key_id_int or
+ *                                      \p key_id_bstr and \p key_id_bstr_length.
+ *
+ * \section verify-kid In verify callback we will receive:
+ * - \p encode_type.
+ * - \p key_id_int or
+ *   \p key_id_bstr & \p key_id_bstr_length.
+ *
+ * If key id has been found in local storage, reference for \p cred and
+ * \p cred_len needs to written for further EDHOC processing.
+ */
+struct edhoc_auth_cred_key_id {
+	/** Credentials buffor. */
+	const uint8_t *cred;
+	/** Size of the \p cred buffer in bytes. */
+	size_t cred_len;
+	/** Is credentials cborised? E.g. CWT, CCS. */
+	bool cred_is_cbor;
+
+	/** Encoding type of key identifier. 
+         *
+         * It must follow representation of byte string identifiers described in RFC 9528: 3.3.2. */
+	enum edhoc_encode_type encode_type;
+
+	/** Key identifier as cbor integer. */
+	int32_t key_id_int;
+
+	/** Key identifier as cbor byte string buffer. */
+	uint8_t key_id_bstr[EDHOC_CRED_KEY_ID_LEN + 1];
+	/** Size of the \p key_id_bstr buffer in bytes. */
+	size_t key_id_bstr_length;
+};
+
+/**
+ * \brief X.509 chain authentication method.
+ *
+ * \section fetch-x5chain For fetch callback we need to fill:
+ * - number of certificates: \p nr_of_certs.
+ * - certificates: \p cert.
+ * - certificate lengths: \p cert_len.
+ *
+ * \section verify-x5chain For verify callback we will receive:
+ * - number of certificates: \p nr_of_certs.
+ * - certificates: \p cert.
+ * - certificate lengths: \p cert_len.
+ */
+struct edhoc_auth_cred_x509_chain {
+	/** Number of certificates in chain. */
+	size_t nr_of_certs;
+	/** Certificates references. */
+	const uint8_t *cert[EDHOC_MAX_NR_OF_CERTS_IN_X509_CHAIN];
+	/** Sizes of the \p cert references in bytes. */
+	size_t cert_len[EDHOC_MAX_NR_OF_CERTS_IN_X509_CHAIN];
+};
+
+/**
+ * \brief X.509 hash authentication method.
+ *
+ * \section fetch-x5t For fetch callback we need to fill:
+ * - certificate:                               \p cert & \p cert_len.
+ * - certificate fingerprint:                   \p cert_fp & \p cert_fp_len.
+ * - encoding type of fingerprint algorithm:    \p encode_type.
+ * - fingerprint algorithm:                     \p alg_int or
+ *                                              \p alg_bstr & \p alg_bstr_length.
+ *
+ * \section verify-x5t In verify callback we will receive:
+ * - \p cert_fp & \p cert_fp_len.
+ * - \p encode_type.
+ * - \p alg_int or
+ *   \p alg_bstr & \p alg_bstr_length.
+ *
+ * If certificate fingerprint has been found in local storage, reference for
+ * \p cert and \p cert_len needs to written for further EDHOC processing.
+ */
+struct edhoc_auth_cred_x509_hash {
+	/** Certificate buffer. */
+	const uint8_t *cert;
+	/** Size of the \p cert buffer in bytes. */
+	size_t cert_len;
+
+	/** Certificate fingerprint buffer. */
+	const uint8_t *cert_fp;
+	/** Size of the \p cert_fp buffer in bytes. */
+	size_t cert_fp_len;
+
+	/** Encoding type of certificate fingerprint algorithm. */
+	enum edhoc_encode_type encode_type;
+
+	/** Fingerprint algorithm as cbor integer. */
+	int32_t alg_int;
+
+	/** Fingerprint algorithm as cbor byte string buffer. */
+	uint8_t alg_bstr[EDHOC_CRED_X509_HASH_ALG_LEN + 1];
+	/** Size of the \p alg_bstr buffer in bytes. */
+	size_t alg_bstr_length;
+};
+
+/**
+ * \brief Common structure for different authentication credentials methods.
+ */
+struct edhoc_auth_creds {
+	/** Private signature or static DH key. */
+	uint8_t priv_key_id[EDHOC_KID_LEN];
+
+	/** COSE IANA label. */
+	enum edhoc_cose_header label;
+	union {
+		/** Key identifier authentication structure. */
+		struct edhoc_auth_cred_key_id key_id;
+		/** X.509 chain authentication structure. */
+		struct edhoc_auth_cred_x509_chain x509_chain;
+		/** X.509 hash authentication structure. */
+		struct edhoc_auth_cred_x509_hash x509_hash;
+	};
+};
+
+/**
+ * \brief Authentication credentials fetch callback.
+ *
+ * \param[in] user_context              User context.
+ * \param[out] credentials              Authentication credentials handle.
+ *
+ * \return EDHOC_SUCCESS on success, otherwise failure.
+ */
+typedef int (*edhoc_credentials_fetch_t)(void *user_context,
+					 struct edhoc_auth_creds *credentials);
+
+/**
+ * \brief Authentication credentials verify callback.
+ *
+ * \param[in] user_context              User context.
+ * \param[in,out] credentials           Peer authentication credentials handle.
+ * \param[out] public_key_reference     Pointer address where the public key address is to be written.
+ * \param[out] public_key_length        On success, the number of bytes that make up the public key.
+ *
+ * \return EDHOC_SUCCESS on success, otherwise failure.
+ */
+typedef int (*edhoc_credentials_verify_t)(void *user_context,
+					  struct edhoc_auth_creds *credentials,
+					  const uint8_t **public_key_reference,
+					  size_t *public_key_length);
+
+/**
+ * \brief Bind structure for authentication credentials.
+ */
+struct edhoc_credentials {
+	/** Authentication credentials fetch callback. */
+	edhoc_credentials_fetch_t fetch;
+	/** Authentication credentials verify callback. */
+	edhoc_credentials_verify_t verify;
+};
+
+/* Module interface variables and constants -------------------------------- */
+/* Extern variables and constant declarations ------------------------------ */
+/* Module interface function declarations ---------------------------------- */
+
+/**@}*/
+
+#endif /* EDHOC_CREDENTIALS_H */