Add asm feature

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]`

Cargo.toml

@@ -14,6 +14,7 @@ categories = ["cryptography", "no-std"]
 [features]
 default = []
 std = []
+asm = ["keccak/asm"]
 serialize_secret_state = ["serde", "serde-big-array"]
 
 [dependencies]

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,24 +85,21 @@ 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.
 
 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
 -------

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 {}
 

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/
 ///