Preparation for v1.0.0

* Added integration tests for all dual layer handshake NQ-PQ pattern combos
* Doc fixes and updates

README.md

@@ -32,7 +32,7 @@ Clatter provides [`DualLayerHandshake`](https://docs.rs/clatter/latest/clatter/s
 
 This crate tracks Noise protocol framework **revision 34**. As of now we omit support for the following features:
 
-* Handshake pattern parsing support - Handshakes have to instantiated with the correct primitives compile-time
+* Handshake pattern parsing support - Handshakes have to be instantiated with the correct primitives compile-time
 * Curve 448 DH support - No suitable Rust implementation exists for our requirements
 * Deferred pattern support - can be implemented by the user
 * Fallback pattern support - Can be implemented by the user
@@ -147,7 +147,7 @@ the parties. During a DH key exchange the shared secret is generated by both par
 computations on the publicly transmitted data - whereas **KEMs** are used to transmit the shared 
 secret directly.
 
-The motivation to use KEMs lies in the fact that there are KEM algorithms that are currently though to
+The motivation to use KEMs lies in the fact that there are KEM algorithms that are currently thought to
 be secure against cryptoanalytic attacks by quantum computers. The DH algorithms used by Noise rely on
 the difficulty of mathematical problems that can be easily solved on a powerful quantum computer.
 Such quantum computers do not exist yet, but the world is already shifting towards quantum-safe

src/cipherstate.rs

@@ -6,7 +6,7 @@ use crate::bytearray::ByteArray;
 use crate::error::{CipherError, CipherResult};
 use crate::traits::{Cipher, CryptoComponent};
 
-/// Pair of [`CipherState`] instances for sending and receiving transport messages
+/// Pair of [`CipherState`] instances for encrypting and decrypting transport messages
 pub struct CipherStates<C: Cipher> {
     /// Cipher for initiator -> responder communication
     pub initiator_to_responder: CipherState<C>,
@@ -17,9 +17,9 @@ pub struct CipherStates<C: Cipher> {
 /// Cipherstate for encrypting and decrypting messages
 ///
 /// Contains the encryption key and nonce and provides
-/// methods for encrypting messages. Will automatically
-/// increment the nonce and return an error if that
-/// overflows.
+/// methods for encrypting and decrypting data.
+/// Will automatically increment the nonce and return an
+/// error if that overflows.
 #[derive(ZeroizeOnDrop, Zeroize)]
 pub struct CipherState<C: Cipher> {
     k: C::Key,
@@ -34,7 +34,7 @@ impl<C: Cipher> CryptoComponent for CipherState<C> {
 }
 
 impl<C: Cipher> CipherState<C> {
-    /// Initialize cipherstate with given key and nonce
+    /// Initialize with given key and nonce
     ///
     /// # Panics
     /// Panics if key data has incorrect length

src/handshakestate/dual_layer.rs

@@ -17,6 +17,13 @@ use crate::transportstate::TransportState;
 /// Dual layer handshakes require an additional intermediate buffer
 /// for decrypting outer layer handshake messages. The buffer size
 /// is controlled by the generic parameter `BUF`.
+///
+/// # Message Sequences
+///
+/// With dual layer handshakes it is possible to construct handshake pattern
+/// combinations which result in one party having to send **two handshake
+/// messages in a row**. Take care when implementing your handshaking logic and
+/// always use [`Self::is_write_turn`] to check who should send next.
 pub struct DualLayerHandshake<Outer, Inner, C, H, const BUF: usize>
 where
     Inner: Handshaker<C, H>,
@@ -48,10 +55,11 @@ where
     /// * `const BUF` - Intermediate decrypt buffer size - Must be large enough to fit all inner handshake messages
     ///
     /// # Panics
-    /// Panics if `outer` and `inner` aren't both either
-    /// initiators or responders.
+    /// * If `outer` and `inner` aren't both either initiators or responders
+    /// * If outer handshake is a one-way pattern
     pub fn new(outer: Outer, inner: Inner) -> Self {
         assert!(outer.is_initiator() == inner.is_initiator());
+        assert!(!outer.get_pattern().is_one_way());
 
         Self {
             outer: Some(outer),

src/symmetricstate.rs

@@ -115,7 +115,7 @@ where
         Ok(())
     }
 
-    /// Return [`CipherStates`] for encrypting transport messages
+    /// Return [`CipherStates`] for encrypting and decrypting transport messages
     ///
     /// # Panics
     /// * If no key material has been stablished

src/transportstate.rs

@@ -2,9 +2,10 @@
 //!
 //! [`TransportState`] is constructed from a [`Handshaker`] once the handshake
 //! is completed and it can be used for encrypting and decrypting transport
-//! communication with the peer. Methods for rekeying and configuring the
-//! encryption nonce are also provided so that the user can easily implement
-//! higher level protocol features.
+//! communication with the peer.
+//!
+//! Methods for rekeying and configuring the encryption nonce are also provided
+//! so that the user can easily implement higher level protocol features.
 
 use crate::bytearray::ByteArray;
 use crate::cipherstate::CipherStates;

test.sh

@@ -1,3 +1,6 @@
+#!/bin/bash
+set -e
+
 # Without alloc
 cargo test --release --all -- --nocapture
 # With alloc