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]` 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..d458e2d 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,19 @@ 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) -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](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 ------- -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}; @@ -65,12 +66,13 @@ fn main() { Features -------- -Default features flags: [none] +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 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). @@ -83,8 +85,9 @@ Tests ----- To run tests, execute - - cargo test --all-features +```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. @@ -92,15 +95,11 @@ Benchmarks ---------- To benchmark, run +```shell +cargo bench +``` - 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. - -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. +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..833840a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,46 +1,8 @@ -//! # 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 +#![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. -#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] //-------- no_std stuff --------// #![no_std] @@ -49,7 +11,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 {} 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/ ///