From 14dea7cbdc8b9dc172f75782bba2fd8b7e6f94a2 Mon Sep 17 00:00:00 2001 From: Geovane Fedrecheski Date: Tue, 26 Mar 2024 10:49:10 +0100 Subject: [PATCH 1/6] chore: udpate readme --- README.md | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0ddd46e0..ee4b6e17 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,22 @@ -# lakers: EDHOC implemented in Rust +# lakers   [![CI status](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml) [![crates.io](https://img.shields.io/crates/v/lakers.svg)](https://crates.io/crates/lakers) -[![Build and test](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml) -![crates.io](https://img.shields.io/crates/v/lakers.svg) +An implementation of [EDHOC (RFC 9528)](https://datatracker.ietf.org/doc/html/rfc9528) in Rust. -An implementation of [EDHOC (RFC9528)](https://datatracker.ietf.org/doc/html/rfc9528) in Rust: +# What is EDHOC? + +Ephemeral Diffie-Hellman Over COSE (EDHOC) is a new IETF standard that provides a [very lightweight](https://hal.science/hal-04382397/document) authenticated key exchange, ideal for usage in constrained scenarios, such as in Internet of Things environments. + +# EDHOC Features +- lightweight: full authenticated key exchange in as few as 101 bytes +- secure: mutual authentication, forward secrecy, and identity protection +- transport-agnostic: can be used on scenarios with or without IP connectivity; a common way to transport EDHOC is [over reliable CoAP](https://www.rfc-editor.org/rfc/rfc9528.html#coap) +- code re-use: achieved due to re-using technologies common in IoT scenarios, such as COSE, CBOR, and CoAP +- finally, a main use case of EDHOC is to establish an [OSCORE](https://datatracker.ietf.org/doc/rfc8613/) security context + + +# lakers features + +- easy to use, typestated API for Initiator and Responder - microcontroller-optimized: `no_std`, no heap allocations, zero-dependencies (other than crypto backends) - configurable crypto backends - bindings for [C](https://github.com/openwsn-berkeley/lakers/releases/) and [Python](https://pypi.org/project/lakers-python/) @@ -11,6 +24,10 @@ An implementation of [EDHOC (RFC9528)](https://datatracker.ietf.org/doc/html/rfc It currently supports authentication mode STAT-STAT and Cipher Suite 2 (AES-CCM-16-64-128, SHA-256, 8, P-256, ES256, AES-CCM-16-64-128, SHA-256). +# Getting started + +To use `lakers` in your Rust project, add it to your Cargo.toml: `lakers = "0.5.1"` (check for the [latest version here](https://crates.io/crates/lakers)). + Here's a quick look at the API for the Initiator role (for the Responder role, and more details, check the examples or the unit tests): ```rust // perform the handshake @@ -32,10 +49,6 @@ let context = &[0xa0, 0x11, 0x58, 0xfd, 0xb8, 0x20, 0x89, 0x0c, 0xd6, 0xbe, 0x16 let prk_out_new = initiator.edhoc_key_update(context); ``` -## Installation - -To use `lakers` in your Rust project, simply add it to your Cargo.toml: `lakers = "0.5.1"` (check for the [latest version here](https://crates.io/crates/lakers)). - ### C API C-compatible static libraries and headers are available for download in [the releases page](https://github.com/openwsn-berkeley/lakers/releases). From 7997d7928ccb1d136c0090d3245d28d11deb7b2e Mon Sep 17 00:00:00 2001 From: Geovane Fedrecheski Date: Tue, 26 Mar 2024 11:05:31 +0100 Subject: [PATCH 2/6] chore: update readme Co-authored-by: chrysn --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ee4b6e17..b2a8256c 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ It currently supports authentication mode STAT-STAT and Cipher Suite 2 (AES-CCM- # Getting started -To use `lakers` in your Rust project, add it to your Cargo.toml: `lakers = "0.5.1"` (check for the [latest version here](https://crates.io/crates/lakers)). +To use `lakers` in your Rust project, add it to your Cargo.toml using `cargo add lakers`. Here's a quick look at the API for the Initiator role (for the Responder role, and more details, check the examples or the unit tests): ```rust From 2f4ca7862efe5a74bb5993894b6b7987778c4226 Mon Sep 17 00:00:00 2001 From: Geovane Fedrecheski Date: Tue, 26 Mar 2024 11:27:58 +0100 Subject: [PATCH 3/6] chore: move readme contents into lib and link it from root Cargo publish will not accept a readme from outside the crate folder, this solves that. --- README.md | 119 +------------------------------------------------- lib/README.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 118 deletions(-) mode change 100644 => 120000 README.md create mode 100644 lib/README.md diff --git a/README.md b/README.md deleted file mode 100644 index b2a8256c..00000000 --- a/README.md +++ /dev/null @@ -1,118 +0,0 @@ -# lakers   [![CI status](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml) [![crates.io](https://img.shields.io/crates/v/lakers.svg)](https://crates.io/crates/lakers) - -An implementation of [EDHOC (RFC 9528)](https://datatracker.ietf.org/doc/html/rfc9528) in Rust. - -# What is EDHOC? - -Ephemeral Diffie-Hellman Over COSE (EDHOC) is a new IETF standard that provides a [very lightweight](https://hal.science/hal-04382397/document) authenticated key exchange, ideal for usage in constrained scenarios, such as in Internet of Things environments. - -# EDHOC Features -- lightweight: full authenticated key exchange in as few as 101 bytes -- secure: mutual authentication, forward secrecy, and identity protection -- transport-agnostic: can be used on scenarios with or without IP connectivity; a common way to transport EDHOC is [over reliable CoAP](https://www.rfc-editor.org/rfc/rfc9528.html#coap) -- code re-use: achieved due to re-using technologies common in IoT scenarios, such as COSE, CBOR, and CoAP -- finally, a main use case of EDHOC is to establish an [OSCORE](https://datatracker.ietf.org/doc/rfc8613/) security context - - -# lakers features - -- easy to use, typestated API for Initiator and Responder -- microcontroller-optimized: `no_std`, no heap allocations, zero-dependencies (other than crypto backends) -- configurable crypto backends -- bindings for [C](https://github.com/openwsn-berkeley/lakers/releases/) and [Python](https://pypi.org/project/lakers-python/) -- support for EDHOC extensions, including [zero-touch authorization](https://datatracker.ietf.org/doc/draft-ietf-lake-authz/) - -It currently supports authentication mode STAT-STAT and Cipher Suite 2 (AES-CCM-16-64-128, SHA-256, 8, P-256, ES256, AES-CCM-16-64-128, SHA-256). - -# Getting started - -To use `lakers` in your Rust project, add it to your Cargo.toml using `cargo add lakers`. - -Here's a quick look at the API for the Initiator role (for the Responder role, and more details, check the examples or the unit tests): -```rust -// perform the handshake -let initiator = EdhocInitiator::new(default_crypto()); - -let (initiator, message_1) = initiator.prepare_message_1(None, &None)?; // c_i and ead_1 are set to None - -let (initiator, _c_r, id_cred_r, _ead_2) = initiator.parse_message_2(&message_2)?; -let valid_cred_r = credential_check_or_fetch(Some(CRED_R), id_cred_r)?; // CRED_R contains Responder's public key -let initiator = initiator.verify_message_2(I, cred_i, valid_cred_r)?; // I is Initiator's private key - -let (mut initiator, message_3, i_prk_out) = initiator.prepare_message_3(CredentialTransfer::ByReference, &None)?; // no ead_3 - -// derive a secret to use with OSCORE -let oscore_secret = initiator.edhoc_exporter(0u8, &[], 16); // label is 0 - -// update the prk_out key (context taken from draft-ietf-lake-traces) -let context = &[0xa0, 0x11, 0x58, 0xfd, 0xb8, 0x20, 0x89, 0x0c, 0xd6, 0xbe, 0x16, 0x96, 0x02, 0xb8, 0xbc, 0xea]; -let prk_out_new = initiator.edhoc_key_update(context); -``` - -### C API -C-compatible static libraries and headers are available for download in [the releases page](https://github.com/openwsn-berkeley/lakers/releases). - -### Python API -`lakers-python` is [available on PyPI](https://pypi.org/project/lakers-python/), to install it run `pip install lakers-python`. - -### Development -To work on `lakers` itself, follow the instructions below: - -1. Make sure you have [Rust](https://www.rust-lang.org/tools/install) installed. - -2. Download, compile, and run the tests: -``` -git clone git@github.com:openwsn-berkeley/lakers.git && cd lakers -cargo build -cargo test -``` - -`lakers` can be compiled with different configurations depending on the enabled features. To learn what are the available features and how to select them for several configurations of build and test, check the [Github Actions file](./.github/workflows/rust.yml). - -## Example: EDHOC over CoAP on native host - -In one terminal, run an example CoAP server: -``` -cargo run --bin coapserver -``` - -In another one, run the client: -``` -cargo run --bin coapclient -``` - -In the output you should find the EDHOC handshake messages and the derived OSCORE secret/salt. - -The source code for these examples is at `examples/coap/src/bin`. - -## Example: EDHOC on nRF52840 device with different crypto backends - -To build an example application that works on the [nrf52840dk](https://www.nordicsemi.com/Products/Development-hardware/nrf52840-dk), do as follows: - -```bash -# head to the example `no_std` example -cd ./examples/lakers-no_std - -# build using the cryptocell310 crypto backend (hardware-accelerated) -cargo build --target="thumbv7em-none-eabihf" --release - -# build using the psa crypto backend (software-based) -cargo build --target="thumbv7em-none-eabihf" --no-default-features --features="crypto-psa, ead-none, rtt" --release - -``` - -To build **and** flash to the board: -1. install [cargo-embed](https://crates.io/crates/cargo-embed) -1. run one of the commands above, but use the command `embed` in place of `build`. For example: `cargo embed --target="thumbv7em-none-eabihf"` - -## Directory structure -This library is structured as a [cargo workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html). -Its main members are: - -- `lib`: The main library providing the EDHOC implementation. -- `crypto`: Diferent cryptographic backends (e.g. psa, cryptocell310, rustcrypto). -- `ead`: Implementation of extensions to EDHOC via the External Authorization Data (EAD) field. -- `shared`: Defines shared structs and modules used throughout the workspace members. -- `lakers-c`: Provides a foreign function interface that enables using `lakers` from C code. -- `lakers-python`: API for using `lakers` in Python. -- `examples`: Example applications that demonstrate how to use the library. diff --git a/README.md b/README.md new file mode 120000 index 00000000..5be180e3 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +lib/README.md \ No newline at end of file diff --git a/lib/README.md b/lib/README.md new file mode 100644 index 00000000..b2a8256c --- /dev/null +++ b/lib/README.md @@ -0,0 +1,118 @@ +# lakers   [![CI status](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml) [![crates.io](https://img.shields.io/crates/v/lakers.svg)](https://crates.io/crates/lakers) + +An implementation of [EDHOC (RFC 9528)](https://datatracker.ietf.org/doc/html/rfc9528) in Rust. + +# What is EDHOC? + +Ephemeral Diffie-Hellman Over COSE (EDHOC) is a new IETF standard that provides a [very lightweight](https://hal.science/hal-04382397/document) authenticated key exchange, ideal for usage in constrained scenarios, such as in Internet of Things environments. + +# EDHOC Features +- lightweight: full authenticated key exchange in as few as 101 bytes +- secure: mutual authentication, forward secrecy, and identity protection +- transport-agnostic: can be used on scenarios with or without IP connectivity; a common way to transport EDHOC is [over reliable CoAP](https://www.rfc-editor.org/rfc/rfc9528.html#coap) +- code re-use: achieved due to re-using technologies common in IoT scenarios, such as COSE, CBOR, and CoAP +- finally, a main use case of EDHOC is to establish an [OSCORE](https://datatracker.ietf.org/doc/rfc8613/) security context + + +# lakers features + +- easy to use, typestated API for Initiator and Responder +- microcontroller-optimized: `no_std`, no heap allocations, zero-dependencies (other than crypto backends) +- configurable crypto backends +- bindings for [C](https://github.com/openwsn-berkeley/lakers/releases/) and [Python](https://pypi.org/project/lakers-python/) +- support for EDHOC extensions, including [zero-touch authorization](https://datatracker.ietf.org/doc/draft-ietf-lake-authz/) + +It currently supports authentication mode STAT-STAT and Cipher Suite 2 (AES-CCM-16-64-128, SHA-256, 8, P-256, ES256, AES-CCM-16-64-128, SHA-256). + +# Getting started + +To use `lakers` in your Rust project, add it to your Cargo.toml using `cargo add lakers`. + +Here's a quick look at the API for the Initiator role (for the Responder role, and more details, check the examples or the unit tests): +```rust +// perform the handshake +let initiator = EdhocInitiator::new(default_crypto()); + +let (initiator, message_1) = initiator.prepare_message_1(None, &None)?; // c_i and ead_1 are set to None + +let (initiator, _c_r, id_cred_r, _ead_2) = initiator.parse_message_2(&message_2)?; +let valid_cred_r = credential_check_or_fetch(Some(CRED_R), id_cred_r)?; // CRED_R contains Responder's public key +let initiator = initiator.verify_message_2(I, cred_i, valid_cred_r)?; // I is Initiator's private key + +let (mut initiator, message_3, i_prk_out) = initiator.prepare_message_3(CredentialTransfer::ByReference, &None)?; // no ead_3 + +// derive a secret to use with OSCORE +let oscore_secret = initiator.edhoc_exporter(0u8, &[], 16); // label is 0 + +// update the prk_out key (context taken from draft-ietf-lake-traces) +let context = &[0xa0, 0x11, 0x58, 0xfd, 0xb8, 0x20, 0x89, 0x0c, 0xd6, 0xbe, 0x16, 0x96, 0x02, 0xb8, 0xbc, 0xea]; +let prk_out_new = initiator.edhoc_key_update(context); +``` + +### C API +C-compatible static libraries and headers are available for download in [the releases page](https://github.com/openwsn-berkeley/lakers/releases). + +### Python API +`lakers-python` is [available on PyPI](https://pypi.org/project/lakers-python/), to install it run `pip install lakers-python`. + +### Development +To work on `lakers` itself, follow the instructions below: + +1. Make sure you have [Rust](https://www.rust-lang.org/tools/install) installed. + +2. Download, compile, and run the tests: +``` +git clone git@github.com:openwsn-berkeley/lakers.git && cd lakers +cargo build +cargo test +``` + +`lakers` can be compiled with different configurations depending on the enabled features. To learn what are the available features and how to select them for several configurations of build and test, check the [Github Actions file](./.github/workflows/rust.yml). + +## Example: EDHOC over CoAP on native host + +In one terminal, run an example CoAP server: +``` +cargo run --bin coapserver +``` + +In another one, run the client: +``` +cargo run --bin coapclient +``` + +In the output you should find the EDHOC handshake messages and the derived OSCORE secret/salt. + +The source code for these examples is at `examples/coap/src/bin`. + +## Example: EDHOC on nRF52840 device with different crypto backends + +To build an example application that works on the [nrf52840dk](https://www.nordicsemi.com/Products/Development-hardware/nrf52840-dk), do as follows: + +```bash +# head to the example `no_std` example +cd ./examples/lakers-no_std + +# build using the cryptocell310 crypto backend (hardware-accelerated) +cargo build --target="thumbv7em-none-eabihf" --release + +# build using the psa crypto backend (software-based) +cargo build --target="thumbv7em-none-eabihf" --no-default-features --features="crypto-psa, ead-none, rtt" --release + +``` + +To build **and** flash to the board: +1. install [cargo-embed](https://crates.io/crates/cargo-embed) +1. run one of the commands above, but use the command `embed` in place of `build`. For example: `cargo embed --target="thumbv7em-none-eabihf"` + +## Directory structure +This library is structured as a [cargo workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html). +Its main members are: + +- `lib`: The main library providing the EDHOC implementation. +- `crypto`: Diferent cryptographic backends (e.g. psa, cryptocell310, rustcrypto). +- `ead`: Implementation of extensions to EDHOC via the External Authorization Data (EAD) field. +- `shared`: Defines shared structs and modules used throughout the workspace members. +- `lakers-c`: Provides a foreign function interface that enables using `lakers` from C code. +- `lakers-python`: API for using `lakers` in Python. +- `examples`: Example applications that demonstrate how to use the library. From 03a122ff1c6190f264a236ee0dd6f81d125d462b Mon Sep 17 00:00:00 2001 From: Geovane Fedrecheski Date: Tue, 26 Mar 2024 11:43:50 +0100 Subject: [PATCH 4/6] chore: update crate metadata --- Cargo.toml | 1 + lib/Cargo.toml | 4 ++-- shared/Cargo.toml | 1 + 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 214e528d..0faec6f4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -36,6 +36,7 @@ version = "0.5.1" repository = "https://github.com/openwsn-berkeley/lakers/" license = "BSD-3-Clause" readme = "shared/README.md" +keywords = ["iot", "security", "protocol", "crypto", "edhoc"] [workspace.dependencies] diff --git a/lib/Cargo.toml b/lib/Cargo.toml index c43f082d..ad996237 100644 --- a/lib/Cargo.toml +++ b/lib/Cargo.toml @@ -4,9 +4,9 @@ version.workspace = true edition = "2021" authors = ["Mališa Vučinić "] license.workspace = true -description = "EDHOC implementation in Rust" +description = "An implementation of EDHOC (RFC 9528)" repository.workspace = true -readme = "../README.md" +keywords.workspace = true [dependencies] lakers-shared.workspace = true diff --git a/shared/Cargo.toml b/shared/Cargo.toml index cb39aa73..db09b26d 100644 --- a/shared/Cargo.toml +++ b/shared/Cargo.toml @@ -8,6 +8,7 @@ description = "EDHOC crypto library constants crate" repository.workspace = true # It's implied, but still better for consistency to have it explicit. readme.workspace = true +keywords.workspace = true [dependencies] pyo3 = { version = "0.20.2", features = ["extension-module"], optional = true } From 65c47d27bdae6f7c8349008f4114f336bf58b1d3 Mon Sep 17 00:00:00 2001 From: Geovane Fedrecheski Date: Tue, 26 Mar 2024 11:55:05 +0100 Subject: [PATCH 5/6] chore: add api docs badge to readme --- lib/README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/lib/README.md b/lib/README.md index b2a8256c..f1a0b5ae 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,4 +1,11 @@ -# lakers   [![CI status](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml) [![crates.io](https://img.shields.io/crates/v/lakers.svg)](https://crates.io/crates/lakers) +# lakers   [![CI status]][actions] [![Latest Version]][crates.io] [![API Documentation]][docs.rs] + +[CI status]: https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml/badge.svg +[actions]: https://github.com/openwsn-berkeley/lakers/actions/workflows/build-and-test.yml +[Latest Version]: https://img.shields.io/crates/v/lakers.svg +[crates.io]: https://crates.io/crates/lakers +[API Documentation]: https://docs.rs/lakers/badge.svg +[docs.rs]: https://docs.rs/lakers An implementation of [EDHOC (RFC 9528)](https://datatracker.ietf.org/doc/html/rfc9528) in Rust. From 43fe76848b9b38633608f43fd3a596071f8eaeaa Mon Sep 17 00:00:00 2001 From: Geovane Fedrecheski Date: Tue, 26 Mar 2024 14:01:30 +0100 Subject: [PATCH 6/6] chore: update crate metadata Co-authored-by: chrysn --- Cargo.toml | 1 + lib/Cargo.toml | 1 + shared/Cargo.toml | 1 + 3 files changed, 3 insertions(+) diff --git a/Cargo.toml b/Cargo.toml index 0faec6f4..4586f037 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -37,6 +37,7 @@ repository = "https://github.com/openwsn-berkeley/lakers/" license = "BSD-3-Clause" readme = "shared/README.md" keywords = ["iot", "security", "protocol", "crypto", "edhoc"] +categories = [ "no-std::no-alloc", "network-programming", "embedded" ] [workspace.dependencies] diff --git a/lib/Cargo.toml b/lib/Cargo.toml index ad996237..e24d5d1d 100644 --- a/lib/Cargo.toml +++ b/lib/Cargo.toml @@ -7,6 +7,7 @@ license.workspace = true description = "An implementation of EDHOC (RFC 9528)" repository.workspace = true keywords.workspace = true +categories.workspace = true [dependencies] lakers-shared.workspace = true diff --git a/shared/Cargo.toml b/shared/Cargo.toml index db09b26d..8a8f3377 100644 --- a/shared/Cargo.toml +++ b/shared/Cargo.toml @@ -9,6 +9,7 @@ repository.workspace = true # It's implied, but still better for consistency to have it explicit. readme.workspace = true keywords.workspace = true +categories.workspace = true [dependencies] pyo3 = { version = "0.20.2", features = ["extension-module"], optional = true }