README.MD
1# uOSCORE / uEDHOC -- A Lightweight IoT Security Protocol Stack
2
3
4
5uOSCORE / uEDHOC is a lightweight C implementation of the IETF protocols [OSCORE (RFC8613)](https://www.rfc-editor.org/rfc/rfc8613.html) and [EDHOC (RFC9528)](https://www.rfc-editor.org/rfc/rfc9528.html), specifically designed for microcontrollers. This implementation is independent of the operating system, cryptographic engine, and, in the case of uEDHOC, the transport protocol. Notably, uOSCORE / uEDHOC operates using only stack memory, avoiding heap allocation.
6
7The OSCORE and EDHOC protocols were developed by the IETF to provide a lightweight alternative to (D)TLS for IoT deployments. Unlike (D)TLS, OSCORE and EDHOC function at the application layer, which is typically [CoAP](https://www.rfc-editor.org/rfc/rfc7252.html) rather than at the transport layer. This allows for end-to-end authenticated and encrypted communication through CoAP proxies—a capability that transport layer security protocols like (D)TLS cannot achieve.
8
9For detailed background information and performance evaluations in terms of speed, RAM, and flash memory requirements, refer to our paper, [The Cost of OSCORE and EDHOC for Constrained Devices](https://arxiv.org/pdf/2103.13832.pdf) and the [Benchmarks](benchmarks.md).
10
11## Enterprise Support
12[Eriptic Technologies](https://eriptic.com/) has co-developed uOSCORE / uEDHOC and provides enterprise support services centered around it. Our offerings encompass:
13* Integration of uOSCORE / uEDHOC to designated customer platforms.
14* Tailored threat analysis for unique customer use cases.
15* Designing security architecture for embedded systems.
16* Developing custom embedded security solutions.
17
18For more information visit our website [eriptic.com](https://eriptic.com/) or send us an email uoscore-uedhoc@eriptic.com
19
20## How to Build and Link
21
22* check the configurations in `makefile_config.mk` and adjust them if necessary
23* run `make`
24* link the static library `build/libuoscore-uedhoc.a` in your project
25
26## Test coverage
27* [Test coverage report uOSCORE](https://eriptic.github.io/uoscore-uedhoc/src/oscore/index.html)
28* [Test coverage report uEDHOC](https://eriptic.github.io/uoscore-uedhoc/src/edhoc/index.html)
29
30
31## Project (Folder) Structure
32
33```
34.
35|---cddl_models/
36|---externals/
37|---inc/
38|---samples/
39|---scripts/
40|---src/
41|---test/
42|---test_vectors/
43```
44* The folder `cddl_models` contains CDDL models for all CBOR structures.
45* The folder `externals` contains the external libraries and tools as git submodules.
46* The folder `inc` contains all header file.
47* The folder `samples` contains some usage examples.
48* The folder `scripts` contains scripts for generatinc C code from CDDL models and converting the json formatted EDHOC test vectors to a C header
49* The folder `src` contains all source file.
50* The folder `test` contains automated tests.
51* The folder `test_vectors` contains tests vectors.
52
53## API and Usage Model
54
55#### uOSCORE
56
57The API of uOSCORE consists of three functions:
58* `oscore_context_init()`,
59* `coap2oscore()` and
60* `oscore2coap()`.
61
62`coap2oscore()` and `oscore2coap()` convert CoAP to OSCORE packets and vice versa. `oscore_context_init()` initializes the OSCORE security context.
63
64First, `oscore_context_init()` function needs to be called on the client and server side, then `coap2oscore()` and `oscore2coap()` are called just before sending or receiving packets over the network.
65
66<img src="oscore_usage.svg" alt="drawing" width="600"/>
67
68
69#### uEDHOC
70
71The API of uEDHOC consists of four functions:
72* `ephemeral_dh_key_gen()`
73* `edhoc_initiator_run()`,
74* `edhoc_responder_run()`,
75* `edhoc_exporter()`,
76
77`ephemeral_dh_key_gen()` is used to generate fresh ephemeral DH keys before running the protocol. This function requires a random seed suable for cryptographic purposes. `edhoc_initiator_run()` and `edhoc_responder_run() ` has to be called on the initiator and responder side respectively. They return the External Authorization data `EAD_x`, the derived shared secret `PRK_out`. `PRK_out` is used as input for `edhoc_exporter()` to derive application specific keys, e.g., OSCORE master secret and OSCORE master salt.
78
79The EDHOC protocol requires the exchange of three messages (and an optional message 4) which is independent of the underlying message transport protocol. For example [appendix-A.2 in the EDHOC specification](https://datatracker.ietf.org/doc/html/draft-ietf-lake-edhoc-15#appendix-A.2) describes how EDHOC can be transferred over CoAP, however CoAP is not mandatory. In order to be independent of the transport protocol uEDHOC uses two callback functions which need to be implemented by the user for handling the sending and receiving of messages. These functions are:
80
81```c
82/**
83 * @brief The user should call inside this function its send function.
84 *
85 *
86 * @param sock a pointer used to identify the rx chanel,
87 * e.g. a socket handler
88 * @param data data to be send
89 */
90enum err tx(void *sock, struct byte_array *data);
91
92/**
93 * @brief The user should call inside this function its receive
94 * function. The user should copy the received data in \p data.
95 *
96 * THE USER MUST MAKE SURE THAT HE/SHE IS NOT WRITING DATA OUTSIDE THE
97 * RECEIVE BUFFER, I.E., THE LENGTH OF THE RECEIVED DATA IS SMALLER
98 * THAN \p data->len.
99 *
100 * After copying, the length of the received data should be written
101 * in \p data->len.
102 *
103 *
104 * @param sock a pointer used to identify the rx chanel,
105 * e.g. a socket handler
106 * @param data the received message must be copied here
107 */
108enum err rx(void *sock, struct byte_array *data);
109```
110
111Note that uEDHOC does not provide correlation of messages. Correlation may be handled on the transport layer completely or partially. In cases when the correlation cannot be handled by the transport protocol the edhoc message needs to be prepended with a connection identifier, that is used on the other side to determine to which session a given message belongs. In order to remain conform with the specification in the cases where the transport cannot handle correlation a connection identifier needs to be prepended in `tx()` function and removed in the `rx()` function.
112
113
114## Supported Cipher Suites
115
116##### uOSCORE
117
118| Algorithms |
119| --------------------------- |
120| AES-CCM-16-64-128, SHA-256 |
121
122##### uEDHOC
123
124
125| Suit | Algorithms |
126| ---- | -------------------------------------------------------------------------- |
127| 0 | AES-CCM-16-64-128, SHA-256, 8, X25519, EdDSA, AES-CCM-16-64-128, SHA-256 |
128| 1 | AES-CCM-16-128-128, SHA-256, 16, X25519, EdDSA, AES-CCM-16-64-128, SHA-256 |
129| 2 | AES-CCM-16-64-128, SHA-256, 8, P-256, ES256, AES-CCM-16-64-128, SHA-256 |
130| 3 | AES-CCM-16-128-128, SHA-256, 16, P-256, ES256, AES-CCM-16-64-128, SHA-256 |
131
132
133
134
135## Using Different Cryptographic Libraries or Hardware Accelerators
136
137The logic of uOSCORE and uEDHOC is independent form the cryptographic library, i.e., the cryptographic library can easily be exchanged by the user. For that the user needs to provide implementations for the functions specified in `crypto_wrapper.c`.
138
139## Preventing Nonce Reuse Attacks in OSCORE
140
141AES keys should never be used more than once with a given nonce, see [RFC5084](https://datatracker.ietf.org/doc/html/rfc5084). In order to avoid this situation, the user has 2 options while creating context structure:
142- setting `fresh_master_secret_salt = true`, when given context is new (freshly obtained e.g. with EDHOC)
143- setting `fresh_master_secret_salt = false`, when the same context is used between reboots/reconnections. In this case, the user must enable Non-volatile Memory support (see `OSCORE_NVM_SUPPORT` in `makefile_config.mk`) and implement two functions that require access to NVM (see below).
144
145Note that using NVM support is independent of the parameter above. Although it is required for using the same context multiple times, it will also be utilized (if enabled) to store context obtained with EDHOC, enabling the user to reuse it after the reboot. This behaviour is useful in situations where multiple sessions need to be stored on a device, while at the same time being able to start a completely new session with EDHOC. When such feature is not needed, `OSCORE_NVM_SUPPORT` can be disabled so only fresh sessions are acceptable.
146
147 ```c
148 /**
149 * @brief When the same OSCORE master secret and salt are reused through
150 * several reboots of the device, e.g., no fresh shared secret is
151 * derived through EDHOC (or some other method) the Sender Sequence
152 * Number MUST be stored periodically in NVM.
153 * @param nvm_key part of the context that is permitted to be used for identifying the right store slot in NVM.
154 * @param ssn SSN to be written in NVM.
155 * @retval ok or error code if storing the SSN was not possible.
156 */
157 enum err nvm_write_ssn(const struct nvm_key_t *nvm_key, uint64_t ssn);
158
159 /**
160 * @brief When the same OSCORE master secret and salt are reused through
161 * several reboots of the device, e.g., no fresh shared secret is
162 * derived through EDHOC (or some other method) the Sender Sequence
163 * Number MUST be restored from NVM at each reboot.
164 * @param nvm_key part of the context that is permitted to be used for identifying the right store slot in NVM.
165 * @param ssn SSN to be read out from NVM.
166 * @retval ok or error code if the retrieving the SSN was not possible.
167 */
168 enum err nvm_read_ssn(const struct nvm_key_t *nvm_key, uint64_t *ssn);
169 ```
170
171## Additional configuration options
172The build configuration can be adjusted in the [makefile_config.mk](makefile_config.mk).
173
){kind=link}
