From 125ac945804e882be2b58bf370275f27a96f5326 Mon Sep 17 00:00:00 2001 From: Michael Rosenberg Date: Wed, 24 Jul 2024 13:19:57 -0400 Subject: [PATCH 1/7] Added asm feature flag --- Cargo.toml | 1 + README.md | 12 ++++-------- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index f90fc0d..360d981 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,6 +14,7 @@ categories = ["cryptography", "no-std"] [features] default = [] std = [] +asm = ["keccak/asm"] serialize_secret_state = ["serde", "serde-big-array"] [dependencies] diff --git a/README.md b/README.md index d388e05..6feee94 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ strobe-rs [![Version](https://img.shields.io/crates/v/strobe-rs.svg)](https://crates.io/crates/strobe-rs) [![Docs](https://docs.rs/strobe-rs/badge.svg)](https://docs.rs/strobe-rs) -This is a pure Rust, `no_std` implementation of the [Strobe protocol framework][strobe]. It is intended to be used as a library to build other protocols and frameworks. This implementation currently only supports Keccak-f\[1600\] as the internal permutation function, which is the largest possible block size, so big deal. +This is a pure Rust, `no_std` implementation of the [Strobe protocol framework][strobe]. It is intended to be used as a library to build other protocols and frameworks. This implementation currently only supports Keccak-f\[1600\] (the highest security level) as the internal permutation function. [strobe]: https://strobe.sourceforge.io/ @@ -69,8 +69,9 @@ Default features flags: [none] Feature flag list: -* `std` - Implements `std::error::Error` for `AuthError`. -* `serialize_secret_state` - Implements `serde`'s `Serialize` and `Deserialize` traits for the `Strobe` struct. **SECURITY NOTE**: Serializing Strobe state outputs security sensitive data that MUST be kept private. Treat the data as you would a private encryption/decryption key. +* `std` — Implements `std::error::Error` for `AuthError`. +* `asm` — Enables an optimized assembly implementation of the Keccak permutation, if available. Assembly currently only exists for ARMv8. +* `serialize_secret_state` — Implements `serde`'s `Serialize` and `Deserialize` traits for the `Strobe` struct. **SECURITY NOTE**: Serializing Strobe state outputs security sensitive data that MUST be kept private. Treat the data as you would a private encryption/decryption key. For info on how to omit or include feature flags, see the [cargo docs on features](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#choosing-features). @@ -97,11 +98,6 @@ To benchmark, run This will produce a summary with plots in `target/crieteron/report/index.html`. These won't be very interesting, since almost every function in STROBE has the same runtime. -TODO ----- - -* Contribute an asm impelmentation of Keccak-f\[1600\] to tiny-keccak and expose a feature flag that lets `strobe-rs` users choose which implementation they prefer. - License ------- From fa5108c48a298dc8410fc2a3a9de9258bd82d505 Mon Sep 17 00:00:00 2001 From: Michael Rosenberg Date: Wed, 24 Jul 2024 13:56:10 -0400 Subject: [PATCH 2/7] General docs cleanup --- README.md | 11 ++++++----- src/lib.rs | 46 +++------------------------------------------- 2 files changed, 9 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 6feee94..f1ca115 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,10 @@ strobe-rs [![Version](https://img.shields.io/crates/v/strobe-rs.svg)](https://crates.io/crates/strobe-rs) [![Docs](https://docs.rs/strobe-rs/badge.svg)](https://docs.rs/strobe-rs) -This is a pure Rust, `no_std` implementation of the [Strobe protocol framework][strobe]. It is intended to be used as a library to build other protocols and frameworks. This implementation currently only supports Keccak-f\[1600\] (the highest security level) as the internal permutation function. +This is a pure Rust, `no_std` implementation of the [Strobe protocol framework](https://strobe.sourceforge.io/). The designer's description: +> Strobe is a new framework for cryptographic protocols. It can also be used for regular encryption. Its goals are to make cryptographic protocols much simpler to develop, deploy and analyze; and to fit into even tiny IoT devices. To that end, it uses only one block function — Keccak-f — to encrypt and authenticate messages. -[strobe]: https://strobe.sourceforge.io/ +This implementation currently only supports Keccak-f\[1600\] (the highest security level) as the internal permutation function. Example ------- @@ -65,7 +66,7 @@ fn main() { Features -------- -Default features flags: [none] +Default features flags: _none_ Feature flag list: @@ -85,7 +86,7 @@ Tests To run tests, execute - cargo test --all-features + cargo test --features "std" This includes known-answer tests, which test against JSON-encoded test vectors in the [kat/](kat/) directory. To verify these test vectors against the reference Python implementation, `cd` into `kat/`, run `python2 verify_test_vector.py` and follow the included instructions. @@ -96,7 +97,7 @@ To benchmark, run cargo bench -This will produce a summary with plots in `target/crieteron/report/index.html`. These won't be very interesting, since almost every function in STROBE has the same runtime. +This will produce a summary with plots in `target/crieteron/report/index.html`. These won't be very interesting, since almost every function in STROBE has the same runtime. License ------- diff --git a/src/lib.rs b/src/lib.rs index 91621b6..14324ea 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,46 +1,7 @@ -//! # strobe-rs -//! -//! This is a `no_std` implementation of the [Strobe protocol framework][strobe] in pure Rust. It -//! is intended to be used as a library to build other protocols and frameworks. This -//! implementation currently only supports Keccak-f\[1600\]. -//! -//! Here is a simple program that encrypts and decrypts a message: -//! ``` -//! # use strobe_rs::{SecParam, Strobe}; -//! # fn main() { -//! // Transmitter initializes their STROBE instance with a public context string -//! let mut tx = Strobe::new(b"correctnesstest", SecParam::B128); -//! // Receiver initializes their STROBE instance with a public context string -//! let mut rx = Strobe::new(b"correctnesstest", SecParam::B128); -//! -//! // Transmitter keys their instance -//! tx.key(b"the-combination-on-my-luggage", false); -//! // Receiver keys their instance -//! rx.key(b"the-combination-on-my-luggage", false); -//! -//! // Transmitter encrypts a message in place -//! let mut msg = b"Attack at dawn".to_vec(); -//! tx.send_enc(msg.as_mut_slice(), false); -//! -//! // Rename for clarity. `msg` has been encrypted in-place. -//! let mut ciphertext = msg; -//! -//! // Receiver takes the message and decrypts it in place -//! rx.recv_enc(ciphertext.as_mut_slice(), false); -//! -//! // Rename for clarity again -//! let round_trip_msg = ciphertext; -//! -//! // Ensure that the sent message was the one received -//! assert_eq!(&round_trip_msg, b"Attack at dawn"); -//! # } -//! ``` -//! -//! [strobe]: https://strobe.sourceforge.io/ - -// The doc_cfg feature is only available in nightly. It lets us mark items in documentation as +#![doc = include_str!("../README.md")] +// The doc_auto_cfg feature is only available in nightly. It auto-marks items in documentation as // dependent on specific features. -#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] //-------- no_std stuff --------// #![no_std] @@ -49,7 +10,6 @@ extern crate std; // An Error type is just something that's Debug and Display -#[cfg_attr(docsrs, doc(cfg(feature = "std")))] #[cfg(feature = "std")] impl std::error::Error for AuthError {} From 7492d3c792ec52a1c5da7d462d772dc2c8be98af Mon Sep 17 00:00:00 2001 From: Michael Rosenberg Date: Wed, 24 Jul 2024 14:04:46 -0400 Subject: [PATCH 3/7] Docs wibble --- README.md | 4 ++-- src/strobe.rs | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f1ca115..fe1695b 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ This implementation currently only supports Keccak-f\[1600\] (the highest securi Example ------- -A simple [program](examples/basic.rs) that does authenticated encryption and decryption: +A simple [example](https://github.com/rozbb/strobe-rs/blob/master/examples/basic.rs) that does authenticated encryption and decryption: ```rust use strobe_rs::{SecParam, Strobe}; @@ -71,7 +71,7 @@ Default features flags: _none_ Feature flag list: * `std` — Implements `std::error::Error` for `AuthError`. -* `asm` — Enables an optimized assembly implementation of the Keccak permutation, if available. Assembly currently only exists for ARMv8. +* `asm` — Enables optimized assembly for the Keccak permutation, if available. Assembly currently only exists for ARMv8. * `serialize_secret_state` — Implements `serde`'s `Serialize` and `Deserialize` traits for the `Strobe` struct. **SECURITY NOTE**: Serializing Strobe state outputs security sensitive data that MUST be kept private. Treat the data as you would a private encryption/decryption key. For info on how to omit or include feature flags, see the [cargo docs on features](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#choosing-features). diff --git a/src/strobe.rs b/src/strobe.rs index ebcd218..e0d1c4f 100644 --- a/src/strobe.rs +++ b/src/strobe.rs @@ -59,9 +59,9 @@ impl core::fmt::Display for AuthError { } } -/// The main Strobe object. This is currently limited to using Keccak-f\[1600\] as the internal -/// permutation function. For more information on this object, the [protocol specification][spec] -/// is a great resource. +/// The main Strobe object. This is currently limited to using Keccak-f\[1600\] (the highest +/// security level) as the internal permutation function. For more information on this object, the +/// [protocol specification][spec] is a great resource. /// /// [spec]: https://strobe.sourceforge.io/specs/ /// From 79c4f0b0f0dbfce8359e9e227d3872d94143dce3 Mon Sep 17 00:00:00 2001 From: Michael Rosenberg Date: Wed, 24 Jul 2024 14:05:21 -0400 Subject: [PATCH 4/7] Updated changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a68740..31c72b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## Unreleased + +* Added `asm` feature flag + ## [0.9.0] - 2024-07-24 * Made `(meta_)recv_mac` inputs take a `&[u8; N]` rather than a `&mut [u8]` From e61bf67bdad37ffc0aba492aa5fb338549a047d0 Mon Sep 17 00:00:00 2001 From: Michael Rosenberg Date: Wed, 24 Jul 2024 14:07:46 -0400 Subject: [PATCH 5/7] Fixed spurious doctests --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fe1695b..045b155 100644 --- a/README.md +++ b/README.md @@ -85,8 +85,9 @@ Tests ----- To run tests, execute - - cargo test --features "std" +```shell +cargo test --features "std" +``` This includes known-answer tests, which test against JSON-encoded test vectors in the [kat/](kat/) directory. To verify these test vectors against the reference Python implementation, `cd` into `kat/`, run `python2 verify_test_vector.py` and follow the included instructions. @@ -94,8 +95,9 @@ Benchmarks ---------- To benchmark, run - - cargo bench +```shell +cargo bench +``` This will produce a summary with plots in `target/crieteron/report/index.html`. These won't be very interesting, since almost every function in STROBE has the same runtime. From a343642f70486271de211b247527d4b7f58c2b43 Mon Sep 17 00:00:00 2001 From: Michael Rosenberg Date: Wed, 24 Jul 2024 14:10:35 -0400 Subject: [PATCH 6/7] Made clippy happy --- src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/lib.rs b/src/lib.rs index 14324ea..833840a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,4 @@ +#![allow(clippy::needless_doctest_main)] #![doc = include_str!("../README.md")] // The doc_auto_cfg feature is only available in nightly. It auto-marks items in documentation as // dependent on specific features. From 3e220a46f154c2a7abd4766b3d6128ee0331e95e Mon Sep 17 00:00:00 2001 From: Michael Rosenberg Date: Wed, 24 Jul 2024 14:13:13 -0400 Subject: [PATCH 7/7] Made CI badge reflect master branch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 045b155..d458e2d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ strobe-rs ========= -[![CI](https://github.com/rozbb/strobe-rs/workflows/CI/badge.svg)](https://github.com/rozbb/strobe-rs/actions) +[![CI](https://github.com/rozbb/strobe-rs/workflows/CI/badge.svg?branch=master)](https://github.com/rozbb/strobe-rs/actions) [![Version](https://img.shields.io/crates/v/strobe-rs.svg)](https://crates.io/crates/strobe-rs) [![Docs](https://docs.rs/strobe-rs/badge.svg)](https://docs.rs/strobe-rs)