chore(coverage): Fix missing coverage from API integration tests

Three changes:
1. We neglected to forward stderr from Rosenpass subprocess two
   in the API setup integration test (driveby fix)
2. Added rudimentary signal handling for program termination
   to rosenpass, specifically for the coverage reporting
3. Apparently std::process::Child::kill() sends SIGKILL and not
   SIGTERM, so our nice new signal handler was never used.
   Switched to a rustix based child reaper.

(2) and (3) where necessary because llvm-cov does not produce coverage
when a subprocess terminates due to a default signal handler.

.github/workflows/qc.yaml

@@ -194,19 +194,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - run: rustup default nightly
       - run: rustup component add llvm-tools-preview
       - run: |
           cargo install cargo-llvm-cov || true
-          cargo llvm-cov \
-            --workspace\
-            --all-features \
-            --lcov \
-            --output-path coverage.lcov
+          cargo install grcov || true
+          ./coverage_report.sh
       # If using tarapulin
       #- run: cargo install cargo-tarpaulin
       #- run: cargo tarpaulin --out Xml
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
         with:
-          files: ./coverage.lcov
+          files: ./target/grcov/lcov
           verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

CONTRIBUTING.md

@@ -1,38 +1,41 @@
-**Making a new Release of Rosenpass — Cooking Recipe**
+# Contributing to Rosenpass
 
-If you have to change a file, do what it takes to get the change as commit on the main branch, then **start from step 0**.
-If any other issue occurs
+## Common operations
 
-0. Make sure you are in the root directory of the project
-   - `cd "$(git rev-parse --show-toplevel)"`
-1. Make sure you locally checked out the head of the main branch
-   - `git stash --include-untracked && git checkout main && git pull`
-2. Make sure all tests pass
-   - `cargo test --workspace --all-features`
-3. Make sure the current version in `rosenpass/Cargo.toml` matches that in the [last release on GitHub](https://github.com/rosenpass/rosenpass/releases)
-   - Only normal releases count, release candidates and draft releases can be ignored
-4. Pick the kind of release that you want to make (`major`, `minor`, `patch`, `rc`, ...)
-   - See `cargo release --help` for more information on the available release types
-   - Pick `rc` if in doubt
-5. Try to release a new version
-   - `cargo release rc --package rosenpass`
-   - An issue was reported? Go fix it, start again with step 0!
-6. Actually make the release
-   - `cargo release rc --package rosenpass --execute`
-   - Tentatively wait for any interactions, such as entering ssh keys etc.
-   - You may be asked for your ssh key multiple times!
+### Apply code formatting
 
-**Frequently Asked Questions (FAQ)**
+Format rust code:
 
-- You have untracked files, which `cargo release` complains about?
-  - `git stash --include-untracked`
-- You cannot push to crates.io because you are not logged in?
-  - Follow the steps displayed in [`cargo login`](https://doc.rust-lang.org/cargo/commands/cargo-login.html)
-- How is the release page added to [GitHub Releases](https://github.com/rosenpass/rosenpass/releases) itself?
-  - Our CI Pipeline will create the release, once `cargo release` pushed the new version tag to the repo. The new release should pop up almost immediately in [GitHub Releases](https://github.com/rosenpass/rosenpass/releases) after the [Actions/Release](https://github.com/rosenpass/rosenpass/actions/workflows/release.yaml) pipeline started.
-- No new release pops up in the `Release` sidebar element on the [main page](https://github.com/rosenpass/rosenpass)
-  - Did you push a `rc` release? This view only shows non-draft release, but `rc` releases are considered as draft. See [Releases](https://github.com/rosenpass/rosenpass/releases) page to see all (including draft!) releases.
-- The release page was created on GitHub, but there are no assets/artifacts other than the source code tar ball/zip?
-  - The artifacts are generated and pushed automatically to the release, but this takes some time (a couple of minutes). You can check the respective CI pipeline: [Actions/Release](https://github.com/rosenpass/rosenpass/actions/workflows/release.yaml), which should start immediately after `cargo release` pushed the new release tag to the repo. The release artifacts only are added later to the release, once all jobs in bespoke pipeline finished.
-- How are the release artifacts generated, and what are they?
-  - The release artifacts are built using one Nix derivation per platform, `nix build .#release-package`. It contains both statically linked versions of `rosenpass` itself and OCI container images.
+```bash
+cargo fmt
+```
+
+Format rust code in markdown files:
+
+```bash
+./format_rust_code.sh --mode fix
+```
+
+### Spawn a development environment with nix
+
+```bash
+nix develop .#fullEnv
+```
+
+You need to [install this nix package manager](https://wiki.archlinux.org/title/Nix) first.
+
+### Run our test
+
+Make sure to increase the stack size available; some of our cryptography operations require a lot of stack memory.
+
+```bash
+RUST_MIN_STACK=8388608 cargo test --workspace --all-features
+```
+
+### Generate coverage reports
+
+Keep in mind that many of Rosenpass' tests are doctests, so to get an accurate read on our code coverage, you have to include doctests:
+
+```bash
+./coverage_report.sh
+```

Cargo.lock

@@ -1850,6 +1850,7 @@ dependencies = [
  "rustix",
  "serde",
  "serial_test",
+ "signal-hook",
  "stacker",
  "static_assertions",
  "tempfile",
@@ -2003,9 +2004,11 @@ dependencies = [
  "rosenpass-util",
  "rosenpass-wireguard-broker",
  "rtnetlink",
+ "serde",
  "stacker",
  "tempfile",
  "tokio",
+ "toml",
  "x25519-dalek",
  "zeroize",
 ]
@@ -2176,6 +2179,16 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "signal-hook"
+version = "0.3.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8621587d4798caf8eb44879d42e56b9a93ea5dcd315a6487c357130095b62801"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
 [[package]]
 name = "signal-hook-registry"
 version = "1.4.2"

Cargo.toml

@@ -74,6 +74,7 @@ hex = { version = "0.4.3" }
 heck = { version = "0.5.0" }
 libc = { version = "0.2" }
 uds = { git = "https://github.com/rosenpass/uds" }
+signal-hook = "0.3.17"
 
 #Dev dependencies
 serial_test = "3.2.0"
@@ -89,4 +90,4 @@ procspawn = { version = "1.0.1", features = ["test-support"] }
 #Broker dependencies (might need cleanup or changes)
 wireguard-uapi = { version = "3.0.0", features = ["xplatform"] }
 command-fds = "0.2.3"
-rustix = { version = "0.38.41", features = ["net", "fs"] }
+rustix = { version = "0.38.41", features = ["net", "fs", "process"] }

ciphers/src/hash_domain.rs

@@ -6,96 +6,192 @@ use crate::keyed_hash as hash;
 
 pub use hash::KEY_LEN;
 
+///
+///```rust
+/// # use rosenpass_ciphers::hash_domain::{HashDomain, HashDomainNamespace, SecretHashDomain, SecretHashDomainNamespace};
+/// use rosenpass_secret_memory::Secret;
+/// # rosenpass_secret_memory::secret_policy_use_only_malloc_secrets();
+///
+/// const PROTOCOL_IDENTIFIER: &str = "MY_PROTOCOL:IDENTIFIER";
+/// # fn do_doc_test() -> Result<(), Box<dyn std::error::Error>> {
+/// // create use once hash domain for the protocol identifier
+/// let mut hash_domain = HashDomain::zero();
+/// hash_domain = hash_domain.mix(PROTOCOL_IDENTIFIER.as_bytes())?;
+/// // upgrade to reusable hash domain
+/// let hash_domain_namespace: HashDomainNamespace = hash_domain.dup();
+/// // derive new key
+/// let key_identifier = "my_key_identifier";
+/// let key = hash_domain_namespace.mix(key_identifier.as_bytes())?.into_value();
+/// // derive a new key based on a secret
+/// const MY_SECRET_LEN: usize = 21;
+/// let my_secret_bytes = "my super duper secret".as_bytes();
+/// let my_secret: Secret<21> = Secret::from_slice("my super duper secret".as_bytes());
+/// let secret_hash_domain: SecretHashDomain = hash_domain_namespace.mix_secret(my_secret)?;
+/// // derive a new key based on the secret key
+/// let new_key_identifier = "my_new_key_identifier".as_bytes();
+/// let new_key = secret_hash_domain.mix(new_key_identifier)?.into_secret();
+///
+/// # Ok(())
+/// # }
+/// # do_doc_test().unwrap();
+///
+///```
+///
+
 // TODO Use a proper Dec interface
+/// A use-once hash domain for a specified key that can be used directly.
+/// The key must consist of [KEY_LEN] many bytes. If the key must remain secret,
+/// use [SecretHashDomain] instead.
 #[derive(Clone, Debug)]
 pub struct HashDomain([u8; KEY_LEN]);
+/// A reusable hash domain for a namespace identified by the key.
+/// The key must consist of [KEY_LEN] many bytes. If the key must remain secret,
+/// use [SecretHashDomainNamespace] instead.
 #[derive(Clone, Debug)]
 pub struct HashDomainNamespace([u8; KEY_LEN]);
+/// A use-once hash domain for a specified key that can be used directly
+/// by wrapping it in [Secret]. The key must consist of [KEY_LEN] many bytes.
 #[derive(Clone, Debug)]
 pub struct SecretHashDomain(Secret<KEY_LEN>);
+/// A reusable secure hash domain for a namespace identified by the key and that keeps the key secure
+/// by wrapping it in [Secret]. The key must consist of [KEY_LEN] many bytes.
 #[derive(Clone, Debug)]
 pub struct SecretHashDomainNamespace(Secret<KEY_LEN>);
 
 impl HashDomain {
+    /// Creates a nw [HashDomain] initialized with a all-zeros key.
     pub fn zero() -> Self {
         Self([0u8; KEY_LEN])
     }
 
+    /// Turns this [HashDomain] into a [HashDomainNamespace], keeping the key.
     pub fn dup(self) -> HashDomainNamespace {
         HashDomainNamespace(self.0)
     }
 
+    /// Turns this [HashDomain] into a [SecretHashDomain] by wrapping the key into a [Secret]
+    /// and creating a new [SecretHashDomain] from it.
     pub fn turn_secret(self) -> SecretHashDomain {
         SecretHashDomain(Secret::from_slice(&self.0))
     }
 
     // TODO: Protocol! Use domain separation to ensure that
+    /// Creates a new [HashDomain] by mixing in a new key `v`. Specifically,
+    /// it evaluates [hash::hash] with this HashDomain's key as the key and `v`
+    /// as the `data` and uses the result as the key for the new [HashDomain].
+    ///
     pub fn mix(self, v: &[u8]) -> Result<Self> {
         Ok(Self(hash::hash(&self.0, v).collect::<[u8; KEY_LEN]>()?))
     }
 
+    /// Creates a new [SecretHashDomain] by mixing in a new key `v`
+    /// by calling [SecretHashDomain::invoke_primitive] with this
+    /// [HashDomain]'s key as `k` and `v` as `d`.
     pub fn mix_secret<const N: usize>(self, v: Secret<N>) -> Result<SecretHashDomain> {
         SecretHashDomain::invoke_primitive(&self.0, v.secret())
     }
 
+    /// Gets the key of this [HashDomain].
     pub fn into_value(self) -> [u8; KEY_LEN] {
         self.0
     }
 }
 
 impl HashDomainNamespace {
+    /// Creates a new [HashDomain] by mixing in a new key `v`. Specifically,
+    /// it evaluates [hash::hash] with the key of this HashDomainNamespace key as the key and `v`
+    /// as the `data` and uses the result as the key for the new [HashDomain].
     pub fn mix(&self, v: &[u8]) -> Result<HashDomain> {
         Ok(HashDomain(
             hash::hash(&self.0, v).collect::<[u8; KEY_LEN]>()?,
         ))
     }
 
+    /// Creates a new [SecretHashDomain] by mixing in a new key `v`
+    /// by calling [SecretHashDomain::invoke_primitive] with the key of this
+    /// [HashDomainNamespace] as `k` and `v` as `d`.
+    ///
+    /// It requires that `v` consists of exactly [KEY_LEN] many bytes.
     pub fn mix_secret<const N: usize>(&self, v: Secret<N>) -> Result<SecretHashDomain> {
         SecretHashDomain::invoke_primitive(&self.0, v.secret())
     }
 }
 
 impl SecretHashDomain {
+    /// Create a new [SecretHashDomain] with the given key `k` and data `d` by calling
+    /// [hash::hash] with `k` as the `key` and `d` s the `data`, and using the result
+    /// as the content for the new [SecretHashDomain].
+    /// Both `k` and `d` have to be exactly [KEY_LEN] bytes in length.
     pub fn invoke_primitive(k: &[u8], d: &[u8]) -> Result<SecretHashDomain> {
         let mut r = SecretHashDomain(Secret::zero());
         hash::hash(k, d).to(r.0.secret_mut())?;
         Ok(r)
     }
 
+    /// Creates a new [SecretHashDomain] that is initialized with an all zeros key.
     pub fn zero() -> Self {
         Self(Secret::zero())
     }
 
+    /// Turns this [SecretHashDomain] into a [SecretHashDomainNamespace].
     pub fn dup(self) -> SecretHashDomainNamespace {
         SecretHashDomainNamespace(self.0)
     }
 
+    /// Creates a new [SecretHashDomain] from a [Secret] `k`.
+    ///
+    /// It requires that `k` consist of exactly [KEY_LEN] bytes.
     pub fn danger_from_secret(k: Secret<KEY_LEN>) -> Self {
         Self(k)
     }
 
+    /// Creates a new [SecretHashDomain] by mixing in a new key `v`. Specifically,
+    /// it evaluates [hash::hash] with this [SecretHashDomain]'s key as the key and `v`
+    /// as the `data` and uses the result as the key for the new [SecretHashDomain].
+    ///
+    /// It requires that `v` consists of exactly [KEY_LEN] many bytes.
     pub fn mix(self, v: &[u8]) -> Result<SecretHashDomain> {
         Self::invoke_primitive(self.0.secret(), v)
     }
 
+    /// Creates a new [SecretHashDomain] by mixing in a new key `v`
+    /// by calling [SecretHashDomain::invoke_primitive] with the key of this
+    /// [HashDomainNamespace] as `k` and `v` as `d`.
+    ///
+    /// It requires that `v` consists of exactly [KEY_LEN] many bytes.
     pub fn mix_secret<const N: usize>(self, v: Secret<N>) -> Result<SecretHashDomain> {
         Self::invoke_primitive(self.0.secret(), v.secret())
     }
 
+    /// Get the secret key data from this [SecretHashDomain].
     pub fn into_secret(self) -> Secret<KEY_LEN> {
         self.0
     }
 
+    /// Evaluate [hash::hash] with this [SecretHashDomain]'s data as the `key` and
+    /// `dst` as the `data` and stores the result as the new data for this [SecretHashDomain].
+    ///
+    /// It requires that both `v` and `d` consist of exactly [KEY_LEN] many bytes.
     pub fn into_secret_slice(mut self, v: &[u8], dst: &[u8]) -> Result<()> {
         hash::hash(v, dst).to(self.0.secret_mut())
     }
 }
 
 impl SecretHashDomainNamespace {
+    /// Creates a new [SecretHashDomain] by mixing in a new key `v`. Specifically,
+    /// it evaluates [hash::hash] with the key of this HashDomainNamespace key as the key and `v`
+    /// as the `data` and uses the result as the key for the new [HashDomain].
+    ///
+    /// It requires that `v` consists of exactly [KEY_LEN] many bytes.
     pub fn mix(&self, v: &[u8]) -> Result<SecretHashDomain> {
         SecretHashDomain::invoke_primitive(self.0.secret(), v)
     }
 
+    /// Creates a new [SecretHashDomain] by mixing in a new key `v`
+    /// by calling [SecretHashDomain::invoke_primitive] with the key of this
+    /// [HashDomainNamespace] as `k` and `v` as `d`.
+    ///
+    /// It requires that `v` consists of exactly [KEY_LEN] many bytes.
     pub fn mix_secret<const N: usize>(&self, v: Secret<N>) -> Result<SecretHashDomain> {
         SecretHashDomain::invoke_primitive(self.0.secret(), v.secret())
     }
@@ -103,6 +199,7 @@ impl SecretHashDomainNamespace {
     // TODO: This entire API is not very nice; we need this for biscuits, but
     // it might be better to extract a special "biscuit"
     // labeled subkey and reinitialize the chain with this
+    /// Get the secret key data from this [SecretHashDomain].
     pub fn danger_into_secret(self) -> Secret<KEY_LEN> {
         self.0
     }

ciphers/src/lib.rs

@@ -2,6 +2,7 @@ use static_assertions::const_assert;
 
 pub mod subtle;
 
+/// All keyed primitives in this crate use 32 byte keys
 pub const KEY_LEN: usize = 32;
 const_assert!(KEY_LEN == aead::KEY_LEN);
 const_assert!(KEY_LEN == xaead::KEY_LEN);
@@ -19,6 +20,7 @@ pub mod keyed_hash {
 }
 
 /// Authenticated encryption with associated data
+/// Chacha20poly1305 is used.
 pub mod aead {
     #[cfg(not(feature = "experiment_libcrux"))]
     pub use crate::subtle::chacha20poly1305_ietf::{decrypt, encrypt, KEY_LEN, NONCE_LEN, TAG_LEN};
@@ -29,6 +31,7 @@ pub mod aead {
 }
 
 /// Authenticated encryption with associated data with a constant nonce
+/// XChacha20poly1305 is used.
 pub mod xaead {
     pub use crate::subtle::xchacha20poly1305_ietf::{
         decrypt, encrypt, KEY_LEN, NONCE_LEN, TAG_LEN,
@@ -37,6 +40,12 @@ pub mod xaead {
 
 pub mod hash_domain;
 
+/// This crate includes two key encapsulation mechanisms.
+/// Namely ClassicMceliece460896 (as [StaticKem]) and Kyber512 (as [EphemeralKem]).
+///
+/// See [rosenpass_oqs::ClassicMceliece460896](rosenpass_oqs::ClassicMceliece460896)
+/// and [rosenpass_oqs::Kyber512](rosenpass_oqs::Kyber512) for more details on the specific KEMS.
+///
 pub mod kem {
     pub use rosenpass_oqs::ClassicMceliece460896 as StaticKem;
     pub use rosenpass_oqs::Kyber512 as EphemeralKem;

ciphers/src/subtle/blake2b.rs

@@ -9,19 +9,43 @@ use blake2::Blake2bMac;
 use rosenpass_to::{ops::copy_slice, with_destination, To};
 use rosenpass_util::typenum2const;
 
+/// Specify that the used implementation of BLAKE2b is the MAC version of BLAKE2b
+/// with output and key length of 32 bytes (see [Blake2bMac<U32>]).
 type Impl = Blake2bMac<U32>;
 
 type KeyLen = <Impl as KeySizeUser>::KeySize;
 type OutLen = <Impl as OutputSizeUser>::OutputSize;
 
+/// The key length for BLAKE2b supported by this API. Currently 32 Bytes.
 const KEY_LEN: usize = typenum2const! { KeyLen };
+/// The output length for BLAKE2b supported by this API. Currently 32 Bytes.
 const OUT_LEN: usize = typenum2const! { OutLen };
 
+/// Minimal key length supported by this API (identical to [KEY_LEN])
 pub const KEY_MIN: usize = KEY_LEN;
+/// maximal key length supported by this API (identical to [KEY_LEN])
 pub const KEY_MAX: usize = KEY_LEN;
+/// minimal output length supported by this API (identical [OUT_LEN])
 pub const OUT_MIN: usize = OUT_LEN;
+/// maximal output length supported by this API (identical [OUT_LEN])
 pub const OUT_MAX: usize = OUT_LEN;
 
+/// Hashes the given `data` with the [Blake2bMac<U32>] hash function under the given `key`.
+/// The [KEY_LEN] and [OUT_LEN] are both set to 32 bytes (or 256 bits).  
+///
+/// # Examples
+///
+///```rust
+/// # use rosenpass_ciphers::subtle::blake2b::hash;
+/// use rosenpass_to::To;
+/// let zero_key: [u8; 32] = [0; 32];
+/// let data: [u8; 32] = [255; 32];
+/// // buffer for the hash output
+/// let mut hash_data: [u8; 32] = [0u8; 32];  
+///
+/// assert!(hash(&zero_key, &data).to(&mut hash_data).is_ok(), "Hashing has to return OK result");
+///```
+///
 #[inline]
 pub fn hash<'a>(key: &'a [u8], data: &'a [u8]) -> impl To<[u8], anyhow::Result<()>> + 'a {
     with_destination(|out: &mut [u8]| {
@@ -36,7 +60,6 @@ pub fn hash<'a>(key: &'a [u8], data: &'a [u8]) -> impl To<[u8], anyhow::Result<(
         let tmp = GenericArray::from_mut_slice(tmp.as_mut());
         h.finalize_into(tmp);
         copy_slice(tmp.as_ref()).to(out);
-
         Ok(())
     })
 }

ciphers/src/subtle/chacha20poly1305_ietf.rs

@@ -6,10 +6,39 @@ use chacha20poly1305::aead::generic_array::GenericArray;
 use chacha20poly1305::ChaCha20Poly1305 as AeadImpl;
 use chacha20poly1305::{AeadCore, AeadInPlace, KeyInit, KeySizeUser};
 
+/// The key length is 32 bytes or 256 bits.
 pub const KEY_LEN: usize = typenum2const! { <AeadImpl as KeySizeUser>::KeySize };
+/// The  MAC tag length is 16 bytes or 128 bits.
 pub const TAG_LEN: usize = typenum2const! { <AeadImpl as AeadCore>::TagSize };
+/// The nonce length is 12 bytes or 96 bits.
 pub const NONCE_LEN: usize = typenum2const! { <AeadImpl as AeadCore>::NonceSize };
 
+/// Encrypts using ChaCha20Poly1305 as implemented in [RustCrypto](https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305).
+/// `key` MUST be chosen (pseudo-)randomly and `nonce` MOST NOT be reused. The `key` slice MUST have
+/// a length of [KEY_LEN]. The `nonce` slice MUST have a length of [NONCE_LEN]. The last [TAG_LEN] bytes
+/// written in `ciphertext` are the tag guaranteeing integrity. `ciphertext` MUST have a capacity of
+/// `plaintext.len()` + [TAG_LEN].
+///
+/// # Examples
+///```rust
+/// # use rosenpass_ciphers::subtle::chacha20poly1305_ietf::{encrypt, TAG_LEN, KEY_LEN, NONCE_LEN};
+///
+/// const PLAINTEXT_LEN: usize = 43;
+/// let plaintext = "post-quantum cryptography is very important".as_bytes();
+/// assert_eq!(PLAINTEXT_LEN, plaintext.len());
+/// let key: &[u8] = &[0u8; KEY_LEN]; // THIS IS NOT A SECURE KEY
+/// let nonce: &[u8] = &[0u8; NONCE_LEN]; // THIS IS NOT A SECURE NONCE
+/// let additional_data: &[u8] = "the encrypted message is very important".as_bytes();
+/// let mut ciphertext_buffer = [0u8;PLAINTEXT_LEN + TAG_LEN];
+///
+/// let res: anyhow::Result<()> = encrypt(&mut ciphertext_buffer, key, nonce, additional_data, plaintext);
+/// assert!(res.is_ok());
+/// # let expected_ciphertext: &[u8] = &[239, 104, 148, 202, 120, 32, 77, 27, 246, 206, 226, 17,
+/// # 83, 78, 122, 116, 187, 123, 70, 199, 58, 130, 21, 1, 107, 230, 58, 77, 18, 152, 31, 159, 80,
+/// # 151, 72, 27, 236, 137, 60, 55, 180, 31, 71, 97, 199, 12, 60, 155, 70, 221, 225, 110, 132, 191,
+/// # 8, 114, 85, 4, 25];
+/// # assert_eq!(expected_ciphertext, &ciphertext_buffer);
+///```
 #[inline]
 pub fn encrypt(
     ciphertext: &mut [u8],
@@ -26,6 +55,33 @@ pub fn encrypt(
     Ok(())
 }
 
+/// Decrypts a `ciphertext` and verifies the integrity of the `ciphertext` and the additional data
+/// `ad`. using ChaCha20Poly1305 as implemented in [RustCrypto](https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305).
+///
+/// The `key` slice MUST have a length of [KEY_LEN]. The `nonce` slice MUST have a length of
+/// [NONCE_LEN]. The plaintext buffer must have a capacity of `ciphertext.len()` - [TAG_LEN].
+///
+/// # Examples
+///```rust
+/// # use rosenpass_ciphers::subtle::chacha20poly1305_ietf::{decrypt, TAG_LEN, KEY_LEN, NONCE_LEN};
+/// let ciphertext: &[u8] = &[239, 104, 148, 202, 120, 32, 77, 27, 246, 206, 226, 17,
+/// 83, 78, 122, 116, 187, 123, 70, 199, 58, 130, 21, 1, 107, 230, 58, 77, 18, 152, 31, 159, 80,
+/// 151, 72, 27, 236, 137, 60, 55, 180, 31, 71, 97, 199, 12, 60, 155, 70, 221, 225, 110, 132, 191,
+/// 8, 114, 85, 4, 25]; // this is the ciphertext generated by the example for the encryption
+/// const PLAINTEXT_LEN: usize = 43;
+/// assert_eq!(PLAINTEXT_LEN + TAG_LEN, ciphertext.len());
+///
+/// let key: &[u8] = &[0u8; KEY_LEN]; // THIS IS NOT A SECURE KEY
+/// let nonce: &[u8] = &[0u8; NONCE_LEN]; // THIS IS NOT A SECURE NONCE
+/// let additional_data: &[u8] = "the encrypted message is very important".as_bytes();
+/// let mut plaintext_buffer = [0u8; PLAINTEXT_LEN];
+///
+/// let res: anyhow::Result<()> = decrypt(&mut plaintext_buffer, key, nonce, additional_data, ciphertext);
+/// assert!(res.is_ok());
+/// let expected_plaintext = "post-quantum cryptography is very important".as_bytes();
+/// assert_eq!(expected_plaintext, plaintext_buffer);
+///
+///```
 #[inline]
 pub fn decrypt(
     plaintext: &mut [u8],

ciphers/src/subtle/chacha20poly1305_ietf_libcrux.rs

@@ -3,10 +3,40 @@ use rosenpass_to::To;
 
 use zeroize::Zeroize;
 
+/// The key length is 32 bytes or 256 bits.
 pub const KEY_LEN: usize = 32; // Grrrr! Libcrux, please provide me these constants.
+/// The  MAC tag length is 16 bytes or 128 bits.
 pub const TAG_LEN: usize = 16;
+/// The nonce length is 12 bytes or 96 bits.
 pub const NONCE_LEN: usize = 12;
 
+/// Encrypts using ChaCha20Poly1305 as implemented in [libcrux](https://github.com/cryspen/libcrux).
+/// Key and nonce MUST be chosen (pseudo-)randomly. The `key` slice MUST have a length of
+/// [KEY_LEN]. The `nonce` slice MUST have a length of [NONCE_LEN]. The last [TAG_LEN] bytes
+/// written in `ciphertext` are the tag guaranteeing integrity. `ciphertext` MUST have a capacity of
+/// `plaintext.len()` + [TAG_LEN].
+///  
+/// # Examples
+///```rust
+/// # use rosenpass_ciphers::subtle::chacha20poly1305_ietf_libcrux::{encrypt, TAG_LEN, KEY_LEN, NONCE_LEN};
+///
+/// const PLAINTEXT_LEN: usize = 43;
+/// let plaintext = "post-quantum cryptography is very important".as_bytes();
+/// assert_eq!(PLAINTEXT_LEN, plaintext.len());
+/// let key: &[u8] = &[0u8; KEY_LEN]; // THIS IS NOT A SECURE KEY
+/// let nonce: &[u8] = &[0u8; NONCE_LEN]; // THIS IS NOT A SECURE NONCE
+/// let additional_data: &[u8] = "the encrypted message is very important".as_bytes();
+/// let mut ciphertext_buffer = [0u8; PLAINTEXT_LEN + TAG_LEN];
+///
+/// let res: anyhow::Result<()> = encrypt(&mut ciphertext_buffer, key, nonce, additional_data, plaintext);
+/// assert!(res.is_ok());
+/// # let expected_ciphertext: &[u8] = &[239, 104, 148, 202, 120, 32, 77, 27, 246, 206, 226, 17,
+/// # 83, 78, 122, 116, 187, 123, 70, 199, 58, 130, 21, 1, 107, 230, 58, 77, 18, 152, 31, 159, 80,
+/// # 151, 72, 27, 236, 137, 60, 55, 180, 31, 71, 97, 199, 12, 60, 155, 70, 221, 225, 110, 132, 191,
+/// # 8, 114, 85, 4, 25];
+/// # assert_eq!(expected_ciphertext, &ciphertext_buffer);
+///```
+///
 #[inline]
 pub fn encrypt(
     ciphertext: &mut [u8],
@@ -33,6 +63,33 @@ pub fn encrypt(
     Ok(())
 }
 
+/// Decrypts a `ciphertext` and verifies the integrity of the `ciphertext` and the additional data
+/// `ad`. using ChaCha20Poly1305 as implemented in [libcrux](https://github.com/cryspen/libcrux).
+///
+/// The `key` slice MUST have a length of [KEY_LEN]. The `nonce` slice MUST have a length of
+/// [NONCE_LEN]. The plaintext buffer must have a capacity of `ciphertext.len()` - [TAG_LEN].
+///
+/// # Examples
+///```rust
+/// # use rosenpass_ciphers::subtle::chacha20poly1305_ietf_libcrux::{decrypt, TAG_LEN, KEY_LEN, NONCE_LEN};
+/// let ciphertext: &[u8] = &[239, 104, 148, 202, 120, 32, 77, 27, 246, 206, 226, 17,
+/// 83, 78, 122, 116, 187, 123, 70, 199, 58, 130, 21, 1, 107, 230, 58, 77, 18, 152, 31, 159, 80,
+/// 151, 72, 27, 236, 137, 60, 55, 180, 31, 71, 97, 199, 12, 60, 155, 70, 221, 225, 110, 132, 191,
+/// 8, 114, 85, 4, 25]; // this is the ciphertext generated by the example for the encryption
+/// const PLAINTEXT_LEN: usize = 43;
+/// assert_eq!(PLAINTEXT_LEN + TAG_LEN, ciphertext.len());
+///
+/// let key: &[u8] = &[0u8; KEY_LEN]; // THIS IS NOT A SECURE KEY
+/// let nonce: &[u8] = &[0u8; NONCE_LEN]; // THIS IS NOT A SECURE NONCE
+/// let additional_data: &[u8] = "the encrypted message is very important".as_bytes();
+/// let mut plaintext_buffer = [0u8; PLAINTEXT_LEN];
+///
+/// let res: anyhow::Result<()> = decrypt(&mut plaintext_buffer, key, nonce, additional_data, ciphertext);
+/// assert!(res.is_ok());
+/// let expected_plaintext = "post-quantum cryptography is very important".as_bytes();
+/// assert_eq!(expected_plaintext, plaintext_buffer);
+///
+///```
 #[inline]
 pub fn decrypt(
     plaintext: &mut [u8],

ciphers/src/subtle/incorrect_hmac_blake2b.rs

@@ -6,10 +6,15 @@ use rosenpass_to::{ops::copy_slice, with_destination, To};
 
 use crate::subtle::blake2b;
 
+/// The key length, 32 bytes or 256 bits.
 pub const KEY_LEN: usize = 32;
+/// The minimal key length, identical to [KEY_LEN]
 pub const KEY_MIN: usize = KEY_LEN;
+/// The maximal key length, identical to [KEY_LEN]
 pub const KEY_MAX: usize = KEY_LEN;
+/// The minimal output length, see [blake2b::OUT_MIN]
 pub const OUT_MIN: usize = blake2b::OUT_MIN;
+/// The maximal output length, see [blake2b::OUT_MAX]
 pub const OUT_MAX: usize = blake2b::OUT_MAX;
 
 /// This is a woefully incorrect implementation of hmac_blake2b.
@@ -19,6 +24,22 @@ pub const OUT_MAX: usize = blake2b::OUT_MAX;
 ///
 /// This will be replaced, likely by Kekkac at some point soon.
 /// <https://github.com/rosenpass/rosenpass/pull/145>
+///
+/// # Examples
+///```rust
+/// # use rosenpass_ciphers::subtle::incorrect_hmac_blake2b::hash;
+/// use rosenpass_to::To;
+/// let key: [u8; 32] = [0; 32];
+/// let data: [u8; 32] = [255; 32];
+/// // buffer for the hash output
+/// let mut hash_data: [u8; 32] = [0u8; 32];
+///
+/// assert!(hash(&key, &data).to(&mut hash_data).is_ok(), "Hashing has to return OK result");
+/// # let expected_hash: &[u8] = &[5, 152, 135, 141, 151, 106, 147, 8, 220, 95, 38, 66, 29, 33, 3,
+/// 104, 250, 114, 131, 119, 27, 56, 59, 44, 11, 67, 230, 113, 112, 20, 80, 103];
+/// # assert_eq!(hash_data, expected_hash);
+///```
+///
 #[inline]
 pub fn hash<'a>(key: &'a [u8], data: &'a [u8]) -> impl To<[u8], anyhow::Result<()>> + 'a {
     const IPAD: [u8; KEY_LEN] = [0x36u8; KEY_LEN];

ciphers/src/subtle/mod.rs

@@ -1,3 +1,9 @@
+/// This module provides the following cryptographic schemes:
+/// - [blake2b]: The blake2b hash function
+/// - [chacha20poly1305_ietf]: The Chacha20Poly1305 AEAD as implemented in [RustCrypto](https://crates.io/crates/chacha20poly1305) (only used when the feature `experiment_libcrux` is disabled.
+/// - [chacha20poly1305_ietf_libcrux]: The Chacha20Poly1305 AEAD as implemented in [libcrux](https://github.com/cryspen/libcrux) (only used when the feature `experiment_libcrux` is enabled.
+/// - [incorrect_hmac_blake2b]: An (incorrect) hmac based on [blake2b].
+/// - [xchacha20poly1305_ietf] The Chacha20Poly1305 AEAD as implemented in [RustCrypto](https://crates.io/crates/chacha20poly1305)
 pub mod blake2b;
 #[cfg(not(feature = "experiment_libcrux"))]
 pub mod chacha20poly1305_ietf;

ciphers/src/subtle/xchacha20poly1305_ietf.rs

@@ -6,10 +6,41 @@ use chacha20poly1305::aead::generic_array::GenericArray;
 use chacha20poly1305::XChaCha20Poly1305 as AeadImpl;
 use chacha20poly1305::{AeadCore, AeadInPlace, KeyInit, KeySizeUser};
 
+/// The key length is 32 bytes or 256 bits.
 pub const KEY_LEN: usize = typenum2const! { <AeadImpl as KeySizeUser>::KeySize };
+/// The  MAC tag length is 16 bytes or 128 bits.
 pub const TAG_LEN: usize = typenum2const! { <AeadImpl as AeadCore>::TagSize };
+/// The nonce length is 24 bytes or 192 bits.
 pub const NONCE_LEN: usize = typenum2const! { <AeadImpl as AeadCore>::NonceSize };
 
+/// Encrypts using XChaCha20Poly1305 as implemented in [RustCrypto](https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305).
+/// `key` and `nonce` MUST be chosen (pseudo-)randomly. The `key` slice MUST have a length of
+/// [KEY_LEN]. The `nonce` slice MUST have a length of [NONCE_LEN].
+/// In contrast to [chacha20poly1305_ietf::encrypt](crate::subtle::chacha20poly1305_ietf::encrypt) and
+/// [chacha20poly1305_ietf_libcrux::encrypt](crate::subtle::chacha20poly1305_ietf_libcrux::encrypt),
+/// `nonce` is also written into `ciphertext` and therefore ciphertext MUST have a length
+/// of at least [NONCE_LEN] + `plaintext.len()` + [TAG_LEN].
+///
+/// # Examples
+///```rust
+/// # use rosenpass_ciphers::subtle::xchacha20poly1305_ietf::{encrypt, TAG_LEN, KEY_LEN, NONCE_LEN};
+/// const PLAINTEXT_LEN: usize = 43;
+/// let plaintext = "post-quantum cryptography is very important".as_bytes();
+/// assert_eq!(PLAINTEXT_LEN, plaintext.len());
+/// let key: &[u8] = &[0u8; KEY_LEN]; // THIS IS NOT A SECURE KEY
+/// let nonce: &[u8] = &[0u8; NONCE_LEN]; // THIS IS NOT A SECURE NONCE
+/// let additional_data: &[u8] = "the encrypted message is very important".as_bytes();
+/// let mut ciphertext_buffer = [0u8; NONCE_LEN + PLAINTEXT_LEN + TAG_LEN];
+///
+///
+/// let res: anyhow::Result<()> = encrypt(&mut ciphertext_buffer, key, nonce, additional_data, plaintext);
+/// # assert!(res.is_ok());
+/// # let expected_ciphertext: &[u8] = &[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+/// # 0, 0, 0, 0, 8, 241, 229, 253, 200, 81, 248, 30, 183, 149, 134, 168, 149, 87, 109, 49, 159, 108,
+/// # 206, 89, 51, 232, 232, 197, 163, 253, 254, 208, 73, 76, 253, 13, 247, 162, 133, 184, 177, 44,
+/// # 73, 138, 176, 193, 61, 248, 61, 183, 164, 192, 214, 168, 4, 1, 62, 243, 36, 48, 149, 164, 6];
+/// # assert_eq!(expected_ciphertext, &ciphertext_buffer);
+///```
 #[inline]
 pub fn encrypt(
     ciphertext: &mut [u8],
@@ -28,6 +59,38 @@ pub fn encrypt(
     Ok(())
 }
 
+/// Decrypts a `ciphertext` and verifies the integrity of the `ciphertext` and the additional data
+/// `ad`. using XChaCha20Poly1305 as implemented in [RustCrypto](https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305).
+///
+/// The `key` slice MUST have a length of [KEY_LEN]. The `nonce` slice MUST have a length of
+/// [NONCE_LEN]. The plaintext buffer must have a capacity of `ciphertext.len()` - [TAG_LEN] - [NONCE_LEN].
+///
+/// In contrast to [chacha20poly1305_ietf::decrypt](crate::subtle::chacha20poly1305_ietf::decrypt) and
+/// [chacha20poly1305_ietf_libcrux::decrypt](crate::subtle::chacha20poly1305_ietf_libcrux::decrypt),
+/// `ciperhtext` MUST include the as it is not given otherwise.
+///
+/// # Examples
+///```rust
+/// # use rosenpass_ciphers::subtle::xchacha20poly1305_ietf::{decrypt, TAG_LEN, KEY_LEN, NONCE_LEN};
+/// let ciphertext: &[u8] = &[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+/// # 0, 0, 0, 0, 8, 241, 229, 253, 200, 81, 248, 30, 183, 149, 134, 168, 149, 87, 109, 49, 159, 108,
+/// # 206, 89, 51, 232, 232, 197, 163, 253, 254, 208, 73, 76, 253, 13, 247, 162, 133, 184, 177, 44,
+/// # 73, 138, 176, 193, 61, 248, 61, 183, 164, 192, 214, 168, 4, 1, 62, 243, 36, 48, 149, 164, 6];
+/// // this is the ciphertext generated by the example for the encryption
+/// const PLAINTEXT_LEN: usize = 43;
+/// assert_eq!(PLAINTEXT_LEN + TAG_LEN + NONCE_LEN, ciphertext.len());
+///
+/// let key: &[u8] = &[0u8; KEY_LEN]; // THIS IS NOT A SECURE KEY
+/// let nonce: &[u8] = &[0u8; NONCE_LEN]; // THIS IS NOT A SECURE NONCE
+/// let additional_data: &[u8] = "the encrypted message is very important".as_bytes();
+/// let mut plaintext_buffer = [0u8; PLAINTEXT_LEN];
+///
+/// let res: anyhow::Result<()> = decrypt(&mut plaintext_buffer, key, additional_data, ciphertext);
+/// assert!(res.is_ok());
+/// let expected_plaintext = "post-quantum cryptography is very important".as_bytes();
+/// assert_eq!(expected_plaintext, plaintext_buffer);
+///
+///```
 #[inline]
 pub fn decrypt(
     plaintext: &mut [u8],

coverage_report.sh

@@ -0,0 +1,44 @@
+#! /usr/bin/env bash
+
+set -e -o pipefail
+
+OUTPUT_DIR="target/grcov"
+
+log() {
+  echo >&2 "$@"
+}
+
+exc() {
+  echo '$' "$@"
+  "$@"
+}
+
+main() {
+  exc cd "$(dirname "$0")"
+
+  local open="0"
+  if [[ "$1" == "--open" ]]; then
+    open="1"
+  fi
+
+  exc cargo llvm-cov --all-features --workspace --doctests
+
+  exc rm -rf "${OUTPUT_DIR}"
+  exc mkdir -p "${OUTPUT_DIR}"
+  exc grcov target/llvm-cov-target/ --llvm  -s . --branch \
+    --binary-path ./target/llvm-cov-target/debug/deps \
+    --ignore-not-existing --ignore '../*' --ignore "/*" \
+    --excl-line '^\s*#\[(derive|repr)\(' \
+    -t lcov,html,markdown -o "${OUTPUT_DIR}"
+
+  if (( "${open}" == 1 )); then
+    xdg-open "${PWD}/${OUTPUT_DIR}/html/index.html"
+  fi
+
+  log ""
+  log "Generated reports in \"${PWD}/${OUTPUT_DIR}\"."
+  log "Open \"${PWD}/${OUTPUT_DIR}/html/index.html\" to view HTML report."
+  log ""
+}
+
+main "$@"

flake.nix

@@ -121,6 +121,7 @@
               proverif-patched
               inputs.fenix.packages.${system}.complete.toolchain
               pkgs.cargo-llvm-cov
+              pkgs.grcov
             ];
           };
           devShells.coverage = pkgs.mkShell {
@@ -128,11 +129,15 @@
             nativeBuildInputs = [
               inputs.fenix.packages.${system}.complete.toolchain
               pkgs.cargo-llvm-cov
+              pkgs.grcov
             ];
           };
 
 
           checks = {
+            systemd-rosenpass = pkgs.testers.runNixOSTest ./tests/systemd/rosenpass.nix;
+            systemd-rp = pkgs.testers.runNixOSTest ./tests/systemd/rp.nix;
+
             cargo-fmt = pkgs.runCommand "check-cargo-fmt"
               { inherit (self.devShells.${system}.default) nativeBuildInputs buildInputs; } ''
               cargo fmt --manifest-path=${./.}/Cargo.toml --check --all && touch $out

pkgs/release-package.nix

@@ -20,7 +20,7 @@ in
 runCommandNoCC "lace-result" { } ''
   mkdir {bin,$out}
   tar -cvf $out/rosenpass-${stdenvNoCC.hostPlatform.system}-${version}.tar \
-    -C ${package} bin/rosenpass \
+    -C ${package} bin/rosenpass lib/systemd \
     -C ${rp} bin/rp
   cp ${oci-image} \
     $out/rosenpass-oci-image-${stdenvNoCC.hostPlatform.system}-${version}.tar.gz

pkgs/rosenpass.nix

@@ -12,6 +12,8 @@ let
     extensions = [
       "lock"
       "rs"
+      "service"
+      "target"
       "toml"
     ];
     # Files to explicitly include
@@ -69,6 +71,13 @@ rustPlatform.buildRustPackage {
 
   hardeningDisable = lib.optional isStatic "fortify";
 
+  postInstall = ''
+    mkdir -p $out/lib/systemd/system
+    install systemd/rosenpass@.service $out/lib/systemd/system
+    install systemd/rp@.service $out/lib/systemd/system
+    install systemd/rosenpass.target $out/lib/systemd/system
+  '';
+
   meta = {
     inherit (cargoToml.package) description homepage;
     license = with lib.licenses; [ mit asl20 ];

readme.md

@@ -23,6 +23,12 @@ rosenpass help
 
 Follow [quick start instructions](https://rosenpass.eu/#start) to get a VPN up and running.
 
+## Contributing
+
+Contributions are generally welcome. Join our [Matrix Chat](https://matrix.to/#/#rosenpass:matrix.org) if you are looking for guidance on how to contribute or for people to collaborate with.
+
+We also have a – as of now, very minimal – [contributors guide](CONTRIBUTING.md).
+
 ## Software architecture
 
 The [rosenpass tool](./src/) is written in Rust and uses liboqs[^liboqs]. The tool establishes a symmetric key and provides it to WireGuard. Since it supplies WireGuard with key through the PSK feature using Rosenpass+WireGuard is cryptographically no less secure than using WireGuard on its own ("hybrid security"). Rosenpass refreshes the symmetric key every two minutes.

rosenpass/Cargo.toml

@@ -62,6 +62,7 @@ heck = { workspace = true, optional = true }
 command-fds = { workspace = true, optional = true }
 rustix = { workspace = true, optional = true }
 uds = { workspace = true, optional = true, features = ["mio_1xx"] }
+signal-hook = { workspace = true, optional = true }
 
 [build-dependencies]
 anyhow = { workspace = true }
@@ -87,5 +88,6 @@ experiment_api = [
     "rosenpass-util/experiment_file_descriptor_passing",
     "rosenpass-wireguard-broker/experiment_api",
 ]
+internal_signal_handling_for_coverage_reports = ["signal-hook"]
 internal_testing = []
 internal_bin_gen_ipc_msg_types = ["hex", "heck"]

rosenpass/src/api/mod.rs

@@ -1,3 +1,5 @@
+//! The bulk code relating to the Rosenpass unix socket API
+
 mod api_handler;
 mod boilerplate;
 

rosenpass/src/bin/gen-ipc-msg-types.rs

@@ -3,6 +3,7 @@ use heck::ToShoutySnakeCase;
 
 use rosenpass_ciphers::{hash_domain::HashDomain, KEY_LEN};
 
+/// Recursively calculate a concrete hash value for an API message type
 fn calculate_hash_value(hd: HashDomain, values: &[&str]) -> Result<[u8; KEY_LEN]> {
     match values.split_first() {
         Some((head, tail)) => calculate_hash_value(hd.mix(head.as_bytes())?, tail),
@@ -10,6 +11,7 @@ fn calculate_hash_value(hd: HashDomain, values: &[&str]) -> Result<[u8; KEY_LEN]
     }
 }
 
+/// Print a hash literal for pasting into the Rosenpass source code
 fn print_literal(path: &[&str]) -> Result<()> {
     let val = calculate_hash_value(HashDomain::zero(), path)?;
     let (last, prefix) = path.split_last().context("developer error!")?;
@@ -33,6 +35,8 @@ fn print_literal(path: &[&str]) -> Result<()> {
     Ok(())
 }
 
+/// Tree of domain separators where each leaf represents
+/// an API message ID
 #[derive(Debug, Clone)]
 enum Tree {
     Branch(String, Vec<Tree>),
@@ -68,6 +72,7 @@ impl Tree {
     }
 }
 
+/// Helper for generating hash-based message IDs for the IPC API
 fn main() -> Result<()> {
     let tree = Tree::Branch(
         "Rosenpass IPC API".to_owned(),

rosenpass/src/hash_domains.rs

@@ -1,13 +1,68 @@
 //! Pseudo Random Functions (PRFs) with a tree-like label scheme which
-//! ensures their uniqueness
+//! ensures their uniqueness.
+//!
+//! This ensures [domain separation](https://en.wikipedia.org/wiki/Domain_separation) is used
+//! across the Rosenpass protocol.
+//!
+//! There is a chart containing all hash domains used in Rosenpass in the
+//! [whitepaper](https://rosenpass.eu/whitepaper.pdf) ([/papers/whitepaper.md] in this repository).
+//!
+//! # Tutorial
+//!
+//! ```
+//! use rosenpass::{hash_domain, hash_domain_ns};
+//! use rosenpass::hash_domains::protocol;
+//!
+//! // Declaring a custom hash domain
+//! hash_domain_ns!(protocol, custom_domain, "my custom hash domain label");
+//!
+//! // Declaring a custom hashers
+//! hash_domain_ns!(custom_domain, hashers, "hashers");
+//! hash_domain_ns!(hashers, hasher1, "1");
+//! hash_domain_ns!(hashers, hasher2, "2");
+//!
+//! // Declaring specific domain separators
+//! hash_domain_ns!(custom_domain, domain_separators, "domain separators");
+//! hash_domain!(domain_separators, sep1, "1");
+//! hash_domain!(domain_separators, sep2, "2");
+//!
+//! // Generating values under hasher1 with both domain separators
+//! let h1 = hasher1()?.mix(b"some data")?.dup();
+//! let h1v1 = h1.mix(&sep1()?)?.mix(b"More data")?.into_value();
+//! let h1v2 = h1.mix(&sep2()?)?.mix(b"More data")?.into_value();
+//!
+//! // Generating values under hasher2 with both domain separators
+//! let h2 = hasher2()?.mix(b"some data")?.dup();
+//! let h2v1 = h2.mix(&sep1()?)?.mix(b"More data")?.into_value();
+//! let h2v2 = h2.mix(&sep2()?)?.mix(b"More data")?.into_value();
+//!
+//! // All of the domain separators are now different, random strings
+//! let values = [h1v1, h1v2, h2v1, h2v2];
+//! for i in 0..values.len() {
+//!     for j in (i+1)..values.len() {
+//!         assert_ne!(values[i], values[j]);
+//!     }
+//! }
+//!
+//! Ok::<(), anyhow::Error>(())
+//! ```
 
 use anyhow::Result;
-use rosenpass_ciphers::{hash_domain::HashDomain, KEY_LEN};
+use rosenpass_ciphers::hash_domain::HashDomain;
 
+/// Declare a hash function
+///
+/// # Examples
+///
+/// See the source file for details about how this is used concretely.
+///
+/// See the [module](self) documentation on how to use the hash domains in general
 // TODO Use labels that can serve as identifiers
+#[macro_export]
 macro_rules! hash_domain_ns {
-    ($base:ident, $name:ident, $($lbl:expr),* ) => {
-        pub fn $name() -> Result<HashDomain> {
+    ($(#[$($attrss:tt)*])* $base:ident, $name:ident, $($lbl:expr),+ ) => {
+        $(#[$($attrss)*])*
+        pub fn $name() -> ::anyhow::Result<::rosenpass_ciphers::hash_domain::HashDomain> {
             let t = $base()?;
             $( let t = t.mix($lbl.as_bytes())?; )*
             Ok(t)
@@ -15,9 +70,18 @@ macro_rules! hash_domain_ns {
     }
 }
 
+/// Declare a concrete hash value
+///
+/// # Examples
+///
+/// See the source file for details about how this is used concretely.
+///
+/// See the [module](self) documentation on how to use the hash domains in general
+#[macro_export]
 macro_rules! hash_domain {
-    ($base:ident, $name:ident, $($lbl:expr),* ) => {
-        pub fn $name() -> Result<[u8; KEY_LEN]> {
+    ($(#[$($attrss:tt)*])* $base:ident, $name:ident, $($lbl:expr),+ ) => {
+        $(#[$($attrss)*])*
+        pub fn $name() -> ::anyhow::Result<[u8; ::rosenpass_ciphers::KEY_LEN]> {
             let t = $base()?;
             $( let t = t.mix($lbl.as_bytes())?; )*
             Ok(t.into_value())
@@ -25,24 +89,227 @@ macro_rules! hash_domain {
     }
 }
 
+/// The hash domain containing the protocol string.
+///
+/// This serves as a global [domain separator](https://en.wikipedia.org/wiki/Domain_separation)
+/// used in various places in the rosenpass protocol.
+///
+/// This is generally used to create further hash-domains for specific purposes. See
+///
+/// # Examples
+///
+/// See the source file for details about how this is used concretely.
+///
+/// See the [module](self) documentation on how to use the hash domains in general
 pub fn protocol() -> Result<HashDomain> {
     HashDomain::zero().mix("Rosenpass v1 mceliece460896 Kyber512 ChaChaPoly1305 BLAKE2s".as_bytes())
 }
 
-hash_domain_ns!(protocol, mac, "mac");
-hash_domain_ns!(protocol, cookie, "cookie");
-hash_domain_ns!(protocol, cookie_value, "cookie-value");
-hash_domain_ns!(protocol, cookie_key, "cookie-key");
-hash_domain_ns!(protocol, peerid, "peer id");
-hash_domain_ns!(protocol, biscuit_ad, "biscuit additional data");
-hash_domain_ns!(protocol, ckinit, "chaining key init");
-hash_domain_ns!(protocol, _ckextract, "chaining key extract");
+hash_domain_ns!(
+    /// Hash domain based on [protocol] for calculating [crate::msgs::Envelope::mac].
+    ///
+    /// # Examples
+    ///
+    /// See the source of [crate::msgs::Envelope::seal] and [crate::msgs::Envelope::check_seal] 
+    /// to figure out how this is concretely used.
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    protocol, mac, "mac");
+hash_domain_ns!(
+    /// Hash domain based on [protocol] involved in calculating [crate::msgs::Envelope::cookie].
+    ///
+    /// # Examples
+    ///
+    /// See the source of [crate::msgs::Envelope::seal_cookie],
+    /// [crate::protocol::CryptoServer::handle_msg_under_load], and
+    /// [crate::protocol::CryptoServer::handle_cookie_reply]
+    /// to figure out how this is concretely used.
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    protocol, cookie, "cookie");
+hash_domain_ns!(
+    /// Hash domain based on [protocol] involved in calculating [crate::msgs::Envelope::cookie].
+    ///
+    /// # Examples
+    ///
+    /// See the source of [crate::msgs::Envelope::seal_cookie],
+    /// [crate::protocol::CryptoServer::handle_msg_under_load], and
+    /// [crate::protocol::CryptoServer::handle_cookie_reply]
+    /// to figure out how this is concretely used.
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    protocol, cookie_value, "cookie-value");
+hash_domain_ns!(
+    /// Hash domain based on [protocol] involved in calculating [crate::msgs::Envelope::cookie].
+    ///
+    /// # Examples
+    ///
+    /// See the source of [crate::msgs::Envelope::seal_cookie],
+    /// [crate::protocol::CryptoServer::handle_msg_under_load], and
+    /// [crate::protocol::CryptoServer::handle_cookie_reply]
+    /// to figure out how this is concretely used.
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    protocol, cookie_key, "cookie-key");
+hash_domain_ns!(
+    /// Hash domain based on [protocol] for calculating the peer id as transmitted (encrypted)
+    /// in [crate::msgs::InitHello::pidic].
+    ///
+    /// # Examples
+    ///
+    /// See the source of [crate::protocol::CryptoServer::pidm] and
+    /// [crate::protocol::Peer::pidt]
+    /// to figure out how this is concretely used.
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    protocol, peerid, "peer id");
+hash_domain_ns!(
+    /// Hash domain based on [protocol] for calculating the additional data
+    /// during [crate::msgs::Biscuit] encryption, storing the biscuit into
+    /// [crate::msgs::RespHello::biscuit].
+    ///
+    /// # Examples
+    ///
+    /// To understand how the biscuit is used, it is best to read
+    /// the code of [crate::protocol::HandshakeState::store_biscuit] and
+    /// [crate::protocol::HandshakeState::load_biscuit]
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    protocol, biscuit_ad, "biscuit additional data");
+hash_domain_ns!(
+    /// This hash domain begins our actual handshake procedure, initializing the
+    /// chaining key [crate::protocol::HandshakeState::ck]. 
+    ///
+    /// # Examples
+    ///
+    /// To understand how the chaining key is used, study
+    /// [crate::protocol::HandshakeState], especially [crate::protocol::HandshakeState::init]
+    /// and [crate::protocol::HandshakeState::mix].
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    protocol, ckinit, "chaining key init");
+hash_domain_ns!(
+    /// Namespace for chaining key usage domain separators.
+    ///
+    /// During the execution of the Rosenpass protocol, we use the chaining key for multiple
+    /// purposes, so to make sure that we have unique value domains, we mix a domain separator
+    /// into the chaining key before using it for any particular purpose.
+    ///
+    /// We could use the full domain separation strings, but using a hash value here is nice
+    /// because it does not lead to any constraints about domain separator format and we can
+    /// even allow third parties to define their own separators by claiming a namespace.
+    ///
+    /// # Examples
+    ///
+    /// To understand how the chaining key is used, study
+    /// [crate::protocol::HandshakeState], especially [crate::protocol::HandshakeState::init]
+    /// and [crate::protocol::HandshakeState::mix].
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    protocol, _ckextract, "chaining key extract");
 
-hash_domain!(_ckextract, mix, "mix");
-hash_domain!(_ckextract, hs_enc, "handshake encryption");
-hash_domain!(_ckextract, ini_enc, "initiator handshake encryption");
-hash_domain!(_ckextract, res_enc, "responder handshake encryption");
+hash_domain!(
+    /// Used to mix in further values into the chaining key during the handshake.
+    ///
+    /// See [_ckextract].
+    ///
+    /// # Examples
+    ///
+    /// To understand how the chaining key is used, study
+    /// [crate::protocol::HandshakeState], especially [crate::protocol::HandshakeState::init]
+    /// and [crate::protocol::HandshakeState::mix].
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    _ckextract, mix, "mix");
+hash_domain!(
+    /// Chaining key domain separator for generating encryption keys that can
+    /// encrypt parts of the handshake.
+    ///
+    /// See [_ckextract].
+    ///
+    /// # Examples
+    ///
+    /// Encryption of data during the handshake happens in
+    /// [crate::protocol::HandshakeState::encrypt_and_mix] and decryption happens in
+    /// [crate::protocol::HandshakeState::decrypt_and_mix]. See their source code
+    /// for details.
+    ///
+    /// To understand how the chaining key is used, study
+    /// [crate::protocol::HandshakeState], especially [crate::protocol::HandshakeState::init]
+    /// and [crate::protocol::HandshakeState::mix].
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    _ckextract, hs_enc, "handshake encryption");
+hash_domain!(
+    /// Chaining key domain separator for live data encryption.
+    /// Live data encryption is only used to send confirmation of handshake
+    /// done in [crate::msgs::EmptyData].
+    ///
+    /// See [_ckextract].
+    ///
+    /// # Examples
+    ///
+    /// This domain separator finds use in [crate::protocol::HandshakeState::enter_live].
+    ///
+    /// To understand how the chaining key is used, study
+    /// [crate::protocol::HandshakeState], especially [crate::protocol::HandshakeState::init]
+    /// and [crate::protocol::HandshakeState::mix].
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    _ckextract, ini_enc, "initiator handshake encryption");
+hash_domain!(
+    /// Chaining key domain separator for live data encryption.
+    /// Live data encryption is only used to send confirmation of handshake
+    /// done in [crate::msgs::EmptyData].
+    ///
+    /// See [_ckextract].
+    ///
+    /// # Examples
+    ///
+    /// This domain separator finds use in [crate::protocol::HandshakeState::enter_live].
+    /// Check out its source code!
+    ///
+    /// To understand how the chaining key is used, study
+    /// [crate::protocol::HandshakeState], especially [crate::protocol::HandshakeState::init]
+    /// and [crate::protocol::HandshakeState::mix].
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    _ckextract, res_enc, "responder handshake encryption");
 
-hash_domain_ns!(_ckextract, _user, "user");
-hash_domain_ns!(_user, _rp, "rosenpass.eu");
-hash_domain!(_rp, osk, "wireguard psk");
+hash_domain_ns!(
+    /// Chaining key domain separator for any usage specific purposes.
+    ///
+    /// We do recommend that third parties base their specific domain separators
+    /// on a internet domain and/or mix in much more specific information.
+    ///
+    /// We only really use this to derive a output key for wireguard; see [osk].
+    ///
+    /// See [_ckextract].
+    ///
+    /// # Examples
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    _ckextract, _user, "user");
+hash_domain_ns!(
+    /// Chaining key domain separator for any rosenpass specific purposes.
+    ///
+    /// We only really use this to derive a output key for wireguard; see [osk].
+    ///
+    /// See [_ckextract].
+    ///
+    /// # Examples
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    _user, _rp, "rosenpass.eu");
+hash_domain!(
+    /// Chaining key domain separator for deriving the key sent to WireGuard.
+    ///
+    /// See [_ckextract].
+    ///
+    /// # Examples
+    ///
+    /// This domain separator finds use in [crate::protocol::CryptoServer::osk].
+    /// Check out its source code!
+    ///
+    /// See the [module](self) documentation on how to use the hash domains in general.
+    _rp, osk, "wireguard psk");

rosenpass/src/lib.rs

@@ -1,3 +1,18 @@
+//! This is the central rosenpass crate implementing the rosenpass protocol.
+//!
+//! - [crate::app_server] contains the business logic of rosenpass, handling networking
+//! - [crate::cli] contains the cli parsing logic and contains quite a bit of startup logic; the
+//!   main function quickly hands over to [crate::cli::CliArgs::run] which contains quite a bit
+//!   of our startup logic
+//! - [crate::config] has the code to parse and generate configuration files
+//! - [crate::hash_domains] lists the different hash function domains used in the Rosenpass
+//!   protocol
+//! - [crate::msgs] provides declarations of the Rosenpass protocol network messages and facilities
+//!   to parse those messages through the [::zerocopy] crate
+//! - [crate::protocol] this is where the bulk of our code lives; this module contains the actual
+//!   cryptographic protocol logic
+//! - crate::api implements the Rosenpass unix socket API, if feature "experiment_api" is active
+
 #[cfg(feature = "experiment_api")]
 pub mod api;
 pub mod app_server;
@@ -7,14 +22,25 @@ pub mod hash_domains;
 pub mod msgs;
 pub mod protocol;
 
+/// Error types used in diverse places across Rosenpass
 #[derive(thiserror::Error, Debug)]
 pub enum RosenpassError {
+    /// Usually indicates that parsing a struct through the
+    /// [::zerocopy] crate failed
     #[error("buffer size mismatch")]
     BufferSizeMismatch,
+    /// Mostly raised by the `TryFrom<u8>` implementation for [crate::msgs::MsgType]
+    /// to indicate that a message type is not defined
     #[error("invalid message type")]
-    InvalidMessageType(u8),
+    InvalidMessageType(
+        /// The message type that could not be parsed
+        u8,
+    ),
+    /// Raised by the `TryFrom<RawMsgType>` (crate::api::RawMsgType) implementation for crate::api::RequestMsgType
+    /// and crate::api::RequestMsgType to indicate that a message type is not defined
     #[error("invalid API message type")]
-    InvalidApiMessageType(u128),
-    #[error("could not parse API message")]
-    InvalidApiMessage,
+    InvalidApiMessageType(
+        /// The message type that could not be parsed
+        u128,
+    ),
 }

rosenpass/src/main.rs

@@ -1,10 +1,14 @@
+//! For the main function
+
 use clap::CommandFactory;
 use clap::Parser;
 use clap_mangen::roff::{roman, Roff};
 use log::error;
 use rosenpass::cli::CliArgs;
+use rosenpass_util::functional::run;
 use std::process::exit;
 
+/// Printing custom man sections when generating the man page
 fn print_custom_man_section(section: &str, text: &str, file: &mut std::fs::File) {
     let mut roff = Roff::default();
     roff.control("SH", [section]);
@@ -13,6 +17,8 @@ fn print_custom_man_section(section: &str, text: &str, file: &mut std::fs::File)
 }
 
 /// Catches errors, prints them through the logger, then exits
+///
+/// The bulk of the command line logic is handled inside [crate::cli::CliArgs::run].
 pub fn main() {
     // parse CLI arguments
     let args = CliArgs::parse();
@@ -72,30 +78,107 @@ pub fn main() {
         // error!("error dummy");
     }
 
-    let broker_interface = args.get_broker_interface();
-    match args.run(broker_interface, None) {
-        Ok(_) => {}
-        Err(e) => {
-            error!("{e:?}");
-            exit(1);
+    let res = run(|| {
+        #[cfg(feature = "internal_signal_handling_for_coverage_reports")]
+        let term_signal = terminate::TerminateRequested::new()?;
+
+        let broker_interface = args.get_broker_interface();
+        let err = match args.run(broker_interface, None) {
+            Ok(()) => return Ok(()),
+            Err(err) => err,
+        };
+
+        // This is very very hacky and just used for coverage measurement
+        #[cfg(feature = "internal_signal_handling_for_coverage_reports")]
+        {
+            let terminated_by_signal = err
+                .downcast_ref::<std::io::Error>()
+                .filter(|e| e.kind() == std::io::ErrorKind::Interrupted)
+                .filter(|_| term_signal.value())
+                .is_some();
+            if terminated_by_signal {
+                log::warn!(
+                    "\
+                    Terminated by signal; this signal handler is correct during coverage testing \
+                    but should be otherwise disabled"
+                );
+                return Ok(());
+            }
         }
+
+        Err(err)
+    });
+
+    if let Err(e) = res {
+        error!("{e:?}");
+        exit(1);
     }
 }
+
+/// Custom main page section: Exit Status
 static EXIT_STATUS_MAN: &str = r"
 The rosenpass utility exits 0 on success, and >0 if an error occurs.";
 
+/// Custom main page section: See also.
 static SEE_ALSO_MAN: &str = r"
 rp(1), wg(1)
 
 Karolin Varner, Benjamin Lipp, Wanja Zaeske, and Lisa Schmidt, Rosenpass, https://rosenpass.eu/whitepaper.pdf, 2023.";
 
+/// Custom main page section: Standards.
 static STANDARDS_MAN: &str = r"
 This tool is the reference implementation of the Rosenpass protocol, as
 specified within the whitepaper referenced above.";
 
+/// Custom main page section: Authors.
 static AUTHORS_MAN: &str = r"
 Rosenpass was created by Karolin Varner, Benjamin Lipp, Wanja Zaeske, Marei
 Peischl, Stephan Ajuvo, and Lisa Schmidt.";
 
+/// Custom main page section: Bugs.
 static BUGS_MAN: &str = r"
 The bugs are tracked at https://github.com/rosenpass/rosenpass/issues.";
+
+/// These signal handlers are used exclusively used during coverage testing
+/// to ensure that the llvm-cov can produce reports during integration tests
+/// with multiple processes where subprocesses are terminated via kill(2).
+///
+/// llvm-cov does not support producing coverage reports when the process exits
+/// through a signal, so this is necessary.
+///
+/// The functionality of exiting gracefully upon reception of a terminating signal
+/// is desired for the production variant of Rosenpass, but we should make sure
+/// to use a higher quality implementation; in particular, we should use signalfd(2).
+///
+#[cfg(feature = "internal_signal_handling_for_coverage_reports")]
+mod terminate {
+    use signal_hook::flag::register as sig_register;
+    use std::sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    };
+
+    /// Automatically register a signal handler for common termination signals;
+    /// whether one of these signals was issued can be polled using [Self::value].
+    ///
+    /// The signal handler is not removed when this struct goes out of scope.
+    pub struct TerminateRequested {
+        value: Arc<AtomicBool>,
+    }
+
+    impl TerminateRequested {
+        /// Register signal handlers watching for common termination signals
+        pub fn new() -> anyhow::Result<Self> {
+            let value = Arc::new(AtomicBool::new(false));
+            for sig in signal_hook::consts::TERM_SIGNALS.iter().copied() {
+                sig_register(sig, Arc::clone(&value))?;
+            }
+            Ok(Self { value })
+        }
+
+        /// Check whether a termination signal has been set
+        pub fn value(&self) -> bool {
+            self.value.load(Ordering::Relaxed)
+        }
+    }
+}

rosenpass/src/msgs.rs

@@ -9,21 +9,73 @@
 //! To achieve this we utilize the zerocopy library.
 //!
 use std::mem::size_of;
+use std::u8;
 use zerocopy::{AsBytes, FromBytes, FromZeroes};
 
 use super::RosenpassError;
 use rosenpass_cipher_traits::Kem;
 use rosenpass_ciphers::kem::{EphemeralKem, StaticKem};
 use rosenpass_ciphers::{aead, xaead, KEY_LEN};
-pub const MSG_SIZE_LEN: usize = 1;
-pub const RESERVED_LEN: usize = 3;
+
+/// Length of a session ID such as [InitHello::sidi]
+pub const SESSION_ID_LEN: usize = 4;
+/// Length of a biscuit ID; i.e. size of the value in [Biscuit::biscuit_no]
+pub const BISCUIT_ID_LEN: usize = 12;
+
+/// TODO: Unused, remove!
+pub const WIRE_ENVELOPE_LEN: usize = 1 + 3 + 16 + 16; // TODO verify this
+
+/// Size required to fit any message in binary form
+pub const MAX_MESSAGE_LEN: usize = 2500; // TODO fix this
+
+/// length in bytes of an unencrypted Biscuit (plain text)
+pub const BISCUIT_PT_LEN: usize = size_of::<Biscuit>();
+
+/// Length in bytes of an encrypted Biscuit (cipher text)
+pub const BISCUIT_CT_LEN: usize = BISCUIT_PT_LEN + xaead::NONCE_LEN + xaead::TAG_LEN;
+
+/// Size of the field [Envelope::mac]
 pub const MAC_SIZE: usize = 16;
-pub const COOKIE_SIZE: usize = 16;
-pub const SID_LEN: usize = 4;
+/// Size of the field [Envelope::cookie]
+pub const COOKIE_SIZE: usize = MAC_SIZE;
 
-pub type MsgEnvelopeMac = [u8; 16];
-pub type MsgEnvelopeCookie = MsgEnvelopeMac;
+/// Type of the mac field in [Envelope]
+pub type MsgEnvelopeMac = [u8; MAC_SIZE];
 
+/// Type of the cookie field in [Envelope]
+pub type MsgEnvelopeCookie = [u8; COOKIE_SIZE];
+
+/// Header and footer included in all our packages,
+/// including a type field.
+///
+/// # Examples
+///
+/// ```
+/// use rosenpass::msgs::{Envelope, InitHello};
+/// use zerocopy::{AsBytes, FromBytes, Ref, FromZeroes};
+/// use memoffset::offset_of;
+///
+/// // Zero-initialization
+/// let mut ih = Envelope::<InitHello>::new_zeroed();
+///
+/// // Edit fields normally
+/// ih.mac[0] = 1;
+///
+/// // Edit as binary
+/// ih.as_bytes_mut()[offset_of!(Envelope<InitHello>, msg_type)] = 23;
+/// assert_eq!(ih.msg_type, 23);;
+///
+/// // Conversion to bytes
+/// let mut ih2 = ih.as_bytes().to_owned();
+///
+/// // Setting msg_type field, again
+/// ih2[0] = 42;
+///
+/// // Zerocopy parsing
+/// let ih3 = Ref::<&mut [u8], Envelope<InitHello>>::new(&mut ih2).unwrap();
+/// assert_ne!(ih.as_bytes(), ih3.as_bytes());
+/// assert_eq!(ih3.msg_type, 42);
+/// ```
 #[repr(packed)]
 #[derive(AsBytes, FromBytes, FromZeroes, Clone)]
 pub struct Envelope<M: AsBytes + FromBytes> {
@@ -40,6 +92,40 @@ pub struct Envelope<M: AsBytes + FromBytes> {
     pub cookie: MsgEnvelopeCookie,
 }
 
+/// This is the first message sent by the initiator to the responder
+/// during the execution of the Rosenpass protocol.
+///
+/// When transmitted on the wire, this type will generally be wrapped into [Envelope].
+///
+/// # Examples
+///
+/// Check out the code of [crate::protocol::CryptoServer::handle_initiation] (generation on
+/// iniatiator side) and [crate::protocol::CryptoServer::handle_init_hello] (processing on
+/// responder side) to understand how this is used.
+///
+/// [Envelope] contains some extra examples on how to use structures from the [::zerocopy] crate.
+///
+/// ```
+/// use rosenpass::msgs::{Envelope, InitHello};
+/// use zerocopy::{AsBytes, FromBytes, Ref, FromZeroes};
+/// use memoffset::span_of;
+///
+/// // Zero initialization
+/// let mut ih = Envelope::<InitHello>::new_zeroed();
+///
+/// // Conversion to byte representation
+/// let ih = ih.as_bytes_mut();
+///
+/// // Set value on byte representation
+/// ih[span_of!(Envelope<InitHello>, payload)][span_of!(InitHello, sidi)]
+///     .copy_from_slice(&[1,2,3,4]);
+///
+/// // Conversion from bytes
+/// let ih = Ref::<&mut [u8], Envelope<InitHello>>::new(ih).unwrap();
+///
+/// // Check that write above on byte representation was effective
+/// assert_eq!(ih.payload.sidi, [1,2,3,4]);
+/// ```
 #[repr(packed)]
 #[derive(AsBytes, FromBytes, FromZeroes)]
 pub struct InitHello {
@@ -55,6 +141,40 @@ pub struct InitHello {
     pub auth: [u8; aead::TAG_LEN],
 }
 
+/// This is the second message sent by the responder to the initiator
+/// during the execution of the Rosenpass protocol in response to [InitHello].
+///
+/// When transmitted on the wire, this type will generally be wrapped into [Envelope].
+///
+/// # Examples
+///
+/// Check out the code of [crate::protocol::CryptoServer::handle_init_hello] (generation on
+/// responder side) and [crate::protocol::CryptoServer::handle_resp_hello] (processing on
+/// initiator side) to understand how this is used.
+///
+/// [Envelope] contains some extra examples on how to use structures from the [::zerocopy] crate.
+///
+/// ```
+/// use rosenpass::msgs::{Envelope, RespHello};
+/// use zerocopy::{AsBytes, FromBytes, Ref, FromZeroes};
+/// use memoffset::span_of;
+///
+/// // Zero initialization
+/// let mut ih = Envelope::<RespHello>::new_zeroed();
+///
+/// // Conversion to byte representation
+/// let ih = ih.as_bytes_mut();
+///
+/// // Set value on byte representation
+/// ih[span_of!(Envelope<RespHello>, payload)][span_of!(RespHello, sidi)]
+///     .copy_from_slice(&[1,2,3,4]);
+///
+/// // Conversion from bytes
+/// let ih = Ref::<&mut [u8], Envelope<RespHello>>::new(ih).unwrap();
+///
+/// // Check that write above on byte representation was effective
+/// assert_eq!(ih.payload.sidi, [1,2,3,4]);
+/// ```
 #[repr(packed)]
 #[derive(AsBytes, FromBytes, FromZeroes)]
 pub struct RespHello {
@@ -72,6 +192,40 @@ pub struct RespHello {
     pub biscuit: [u8; BISCUIT_CT_LEN],
 }
 
+/// This is the third message sent by the initiator to the responder
+/// during the execution of the Rosenpass protocol in response to [RespHello].
+///
+/// When transmitted on the wire, this type will generally be wrapped into [Envelope].
+///
+/// # Examples
+///
+/// Check out the code of [crate::protocol::CryptoServer::handle_resp_hello] (generation on
+/// initiator side) and [crate::protocol::CryptoServer::handle_init_conf] (processing on
+/// responder side) to understand how this is used.
+///
+/// [Envelope] contains some extra examples on how to use structures from the [::zerocopy] crate.
+///
+/// ```
+/// use rosenpass::msgs::{Envelope, InitConf};
+/// use zerocopy::{AsBytes, FromBytes, Ref, FromZeroes};
+/// use memoffset::span_of;
+///
+/// // Zero initialization
+/// let mut ih = Envelope::<InitConf>::new_zeroed();
+///
+/// // Conversion to byte representation
+/// let ih = ih.as_bytes_mut();
+///
+/// // Set value on byte representation
+/// ih[span_of!(Envelope<InitConf>, payload)][span_of!(InitConf, sidi)]
+///     .copy_from_slice(&[1,2,3,4]);
+///
+/// // Conversion from bytes
+/// let ih = Ref::<&mut [u8], Envelope<InitConf>>::new(ih).unwrap();
+///
+/// // Check that write above on byte representation was effective
+/// assert_eq!(ih.payload.sidi, [1,2,3,4]);
+/// ```
 #[repr(packed)]
 #[derive(AsBytes, FromBytes, FromZeroes, Debug)]
 pub struct InitConf {
@@ -85,6 +239,51 @@ pub struct InitConf {
     pub auth: [u8; aead::TAG_LEN],
 }
 
+/// This is the fourth message sent by the initiator to the responder
+/// during the execution of the Rosenpass protocol in response to [RespHello].
+///
+/// When transmitted on the wire, this type will generally be wrapped into [Envelope].
+///
+/// This message does not serve a cryptographic purpose; it just tells the initiator
+/// to stop package retransmission.
+///
+/// This message should really be called `RespConf`, but when we wrote the protocol,
+/// we initially designed the protocol we still though Rosenpass itself should do
+/// payload transmission at some point so `EmptyData` could have served as a more generic
+/// mechanism.
+///
+/// We might add payload transmission in the future again, but we will treat
+/// it as a protocol extension if we do.
+///
+/// # Examples
+///
+/// Check out the code of [crate::protocol::CryptoServer::handle_init_conf] (generation on
+/// responder side) and [crate::protocol::CryptoServer::handle_resp_conf] (processing on
+/// initiator side) to understand how this is used.
+///
+/// [Envelope] contains some extra examples on how to use structures from the [::zerocopy] crate.
+///
+/// ```
+/// use rosenpass::msgs::{Envelope, EmptyData};
+/// use zerocopy::{AsBytes, FromBytes, Ref, FromZeroes};
+/// use memoffset::span_of;
+///
+/// // Zero initialization
+/// let mut ih = Envelope::<EmptyData>::new_zeroed();
+///
+/// // Conversion to byte representation
+/// let ih = ih.as_bytes_mut();
+///
+/// // Set value on byte representation
+/// ih[span_of!(Envelope<EmptyData>, payload)][span_of!(EmptyData, sid)]
+///     .copy_from_slice(&[1,2,3,4]);
+///
+/// // Conversion from bytes
+/// let ih = Ref::<&mut [u8], Envelope<EmptyData>>::new(ih).unwrap();
+///
+/// // Check that write above on byte representation was effective
+/// assert_eq!(ih.payload.sid, [1,2,3,4]);
+/// ```
 #[repr(packed)]
 #[derive(AsBytes, FromBytes, FromZeroes, Clone, Copy)]
 pub struct EmptyData {
@@ -96,6 +295,22 @@ pub struct EmptyData {
     pub auth: [u8; aead::TAG_LEN],
 }
 
+/// Cookie encrypted and sent to the initiator by the responder in [RespHello]
+/// and returned by the initiator in [InitConf].
+///
+/// The encryption key is randomly chosen by the responder and frequently regenerated.
+/// Using this biscuit value in the protocol allows us to make sure that the responder
+/// is mostly stateless until full initiator authentication is achieved, which is needed
+/// to prevent denial of service attacks. See the [whitepaper](https://rosenpass.eu/whitepaper.pdf)
+/// ([/papers/whitepaper.md] in this repository).
+///
+/// # Examples
+///
+/// To understand how the biscuit is used, it is best to read
+/// the code of [crate::protocol::HandshakeState::store_biscuit] and
+/// [crate::protocol::HandshakeState::load_biscuit]
+///
+/// [Envelope] and [InitHello] contain some extra examples on how to use structures from the [::zerocopy] crate.
 #[repr(packed)]
 #[derive(AsBytes, FromBytes, FromZeroes)]
 pub struct Biscuit {
@@ -107,12 +322,20 @@ pub struct Biscuit {
     pub ck: [u8; KEY_LEN],
 }
 
-#[repr(packed)]
-#[derive(AsBytes, FromBytes, FromZeroes)]
-pub struct DataMsg {
-    pub dummy: [u8; 4],
-}
-
+/// Specialized message for use in the cookie mechanism.
+///
+/// See the [whitepaper](https://rosenpass.eu/whitepaper.pdf) ([/papers/whitepaper.md] in this repository) for details.
+///
+/// Generally used together with [CookieReply] which brings this up to the size
+/// of [InitHello] to avoid amplification Denial of Service attacks.
+///
+/// # Examples
+///
+/// To understand how the biscuit is used, it is best to read
+/// the code of [crate::protocol::CryptoServer::handle_cookie_reply] and
+/// [crate::protocol::CryptoServer::handle_msg_under_load].
+///
+/// [Envelope] and [InitHello] contain some extra examples on how to use structures from the [::zerocopy] crate.
 #[repr(packed)]
 #[derive(AsBytes, FromBytes, FromZeroes)]
 pub struct CookieReplyInner {
@@ -126,6 +349,20 @@ pub struct CookieReplyInner {
     pub cookie_encrypted: [u8; xaead::NONCE_LEN + COOKIE_SIZE + xaead::TAG_LEN],
 }
 
+/// Specialized message for use in the cookie mechanism.
+///
+/// This just brings [CookieReplyInner] up to the size
+/// of [InitHello] to avoid amplification Denial of Service attacks.
+///
+/// See the [whitepaper](https://rosenpass.eu/whitepaper.pdf) ([/papers/whitepaper.md] in this repository) for details.
+///
+/// # Examples
+///
+/// To understand how the biscuit is used, it is best to read
+/// the code of [crate::protocol::CryptoServer::handle_cookie_reply] and
+/// [crate::protocol::CryptoServer::handle_msg_under_load].
+///
+/// [Envelope] and [InitHello] contain some extra examples on how to use structures from the [::zerocopy] crate.
 #[repr(packed)]
 #[derive(AsBytes, FromBytes, FromZeroes)]
 pub struct CookieReply {
@@ -133,33 +370,46 @@ pub struct CookieReply {
     pub padding: [u8; size_of::<Envelope<InitHello>>() - size_of::<CookieReplyInner>()],
 }
 
-// Traits /////////////////////////////////////////////////////////////////////
-
-pub trait WireMsg: std::fmt::Debug {
-    const MSG_TYPE: MsgType;
-    const MSG_TYPE_U8: u8 = Self::MSG_TYPE as u8;
-    const BYTES: usize;
-}
-
-// Constants //////////////////////////////////////////////////////////////////
-
-pub const SESSION_ID_LEN: usize = 4;
-pub const BISCUIT_ID_LEN: usize = 12;
-
-pub const WIRE_ENVELOPE_LEN: usize = 1 + 3 + 16 + 16; // TODO verify this
-
-/// Size required to fit any message in binary form
-pub const MAX_MESSAGE_LEN: usize = 2500; // TODO fix this
-
 /// Recognized message types
+///
+/// # Examples
+///
+/// ```
+/// use rosenpass::msgs::MsgType;
+/// use rosenpass::msgs::MsgType as M;
+///
+/// let values = [M::InitHello, M::RespHello, M::InitConf, M::EmptyData, M::CookieReply];
+/// let values_u8 = values.map(|v| -> u8 { v.into() });
+///
+/// // Can be converted to and from u8 using [::std::convert::Into] or [::std::convert::From]
+/// for v in values.iter().copied() {
+///     let v_u8 : u8 = v.into();
+///     let v2 : MsgType = v_u8.try_into()?;
+///     assert_eq!(v, v2);
+/// }
+///
+/// // Converting an unsupported type produces an error
+/// let invalid_values = (u8::MIN..=u8::MAX)
+///     .filter(|v| !values_u8.contains(v));
+/// for v in invalid_values {
+///     let res : Result<MsgType, _> = v.try_into();
+///     assert!(res.is_err());
+/// }
+///
+/// Ok::<(), anyhow::Error>(())
+/// ```
 #[repr(u8)]
 #[derive(Hash, PartialEq, Eq, PartialOrd, Ord, Debug, Clone, Copy)]
 pub enum MsgType {
+    /// MsgType for [InitHello]
     InitHello = 0x81,
+    /// MsgType for [RespHello]
     RespHello = 0x82,
+    /// MsgType for [InitConf]
     InitConf = 0x83,
+    /// MsgType for [EmptyData]
     EmptyData = 0x84,
-    DataMsg = 0x85,
+    /// MsgType for [CookieReply]
     CookieReply = 0x86,
 }
 
@@ -172,7 +422,6 @@ impl TryFrom<u8> for MsgType {
             0x82 => MsgType::RespHello,
             0x83 => MsgType::InitConf,
             0x84 => MsgType::EmptyData,
-            0x85 => MsgType::DataMsg,
             0x86 => MsgType::CookieReply,
             _ => return Err(RosenpassError::InvalidMessageType(value)),
         })
@@ -185,12 +434,6 @@ impl From<MsgType> for u8 {
     }
 }
 
-/// length in bytes of an unencrypted Biscuit (plain text)
-pub const BISCUIT_PT_LEN: usize = size_of::<Biscuit>();
-
-/// Length in bytes of an encrypted Biscuit (cipher text)
-pub const BISCUIT_CT_LEN: usize = BISCUIT_PT_LEN + xaead::NONCE_LEN + xaead::TAG_LEN;
-
 #[cfg(test)]
 mod test_constants {
     use crate::msgs::{BISCUIT_CT_LEN, BISCUIT_PT_LEN};

rosenpass/src/protocol/mod.rs

@@ -1,3 +1,75 @@
+//! Module containing the cryptographic protocol implementation
+//!
+//! # Overview
+//!
+//! The most important types in this module probably are [PollResult]
+//! & [CryptoServer]. Once a [CryptoServer] is created, the server is
+//! provided with new messages via the [CryptoServer::handle_msg] method.
+//! The [CryptoServer::poll] method can be used to let the server work, which
+//! will eventually yield a [PollResult]. Said [PollResult] contains
+//! prescriptive activities to be carried out. [CryptoServer::osk] can than
+//! be used to extract the shared key for two peers, once a key-exchange was
+//! successful.
+//!
+//! TODO explain briefly the role of epki
+//!
+//! # Example Handshake
+//!
+//! This example illustrates a minimal setup for a key-exchange between two
+//! [CryptoServer].
+//!
+//! ```
+//! use std::ops::DerefMut;
+//! use rosenpass_secret_memory::policy::*;
+//! use rosenpass_cipher_traits::Kem;
+//! use rosenpass_ciphers::kem::StaticKem;
+//! use rosenpass::{
+//!     protocol::{SSk, SPk, MsgBuf, PeerPtr, CryptoServer, SymKey},
+//! };
+//! # fn main() -> anyhow::Result<()> {
+//! // Set security policy for storing secrets
+//!
+//! secret_policy_try_use_memfd_secrets();
+//!
+//! // initialize secret and public key for peer a ...
+//! let (mut peer_a_sk, mut peer_a_pk) = (SSk::zero(), SPk::zero());
+//! StaticKem::keygen(peer_a_sk.secret_mut(), peer_a_pk.deref_mut())?;
+//!
+//! // ... and for peer b
+//! let (mut peer_b_sk, mut peer_b_pk) = (SSk::zero(), SPk::zero());
+//! StaticKem::keygen(peer_b_sk.secret_mut(), peer_b_pk.deref_mut())?;
+//!
+//! // initialize server and a pre-shared key
+//! let psk = SymKey::random();
+//! let mut a = CryptoServer::new(peer_a_sk, peer_a_pk.clone());
+//! let mut b = CryptoServer::new(peer_b_sk, peer_b_pk.clone());
+//!
+//! // introduce peers to each other
+//! a.add_peer(Some(psk.clone()), peer_b_pk)?;
+//! b.add_peer(Some(psk), peer_a_pk)?;
+//!
+//! // declare buffers for message exchange
+//! let (mut a_buf, mut b_buf) = (MsgBuf::zero(), MsgBuf::zero());
+//!
+//! // let a initiate a handshake
+//! let mut maybe_len = Some(a.initiate_handshake(PeerPtr(0), a_buf.as_mut_slice())?);
+//!
+//! // let a and b communicate
+//! while let Some(len) = maybe_len {
+//!    maybe_len = b.handle_msg(&a_buf[..len], &mut b_buf[..])?.resp;
+//!    std::mem::swap(&mut a, &mut b);
+//!    std::mem::swap(&mut a_buf, &mut b_buf);
+//! }
+//!
+//! // all done! Extract the shared keys and ensure they are identical
+//! let a_key = a.osk(PeerPtr(0))?;
+//! let b_key = b.osk(PeerPtr(0))?;
+//! assert_eq!(a_key.secret(), b_key.secret(),
+//!     "the key exchanged failed to establish a shared secret");
+//! # Ok(())
+//! # }
+//! ```
+
 mod build_crypto_server;
 #[allow(clippy::module_inception)]
 mod protocol;

rosenpass/src/protocol/protocol.rs

@@ -1,75 +1,3 @@
-//! Module containing the cryptographic protocol implementation
-//!
-//! # Overview
-//!
-//! The most important types in this module probably are [PollResult]
-//! & [CryptoServer]. Once a [CryptoServer] is created, the server is
-//! provided with new messages via the [CryptoServer::handle_msg] method.
-//! The [CryptoServer::poll] method can be used to let the server work, which
-//! will eventually yield a [PollResult]. Said [PollResult] contains
-//! prescriptive activities to be carried out. [CryptoServer::osk] can than
-//! be used to extract the shared key for two peers, once a key-exchange was
-//! successful.
-//!
-//! TODO explain briefly the role of epki
-//!
-//! # Example Handshake
-//!
-//! This example illustrates a minimal setup for a key-exchange between two
-//! [CryptoServer].
-//!
-//! ```
-//! use std::ops::DerefMut;
-//! use rosenpass_secret_memory::policy::*;
-//! use rosenpass_cipher_traits::Kem;
-//! use rosenpass_ciphers::kem::StaticKem;
-//! use rosenpass::{
-//!     protocol::{SSk, SPk, MsgBuf, PeerPtr, CryptoServer, SymKey},
-//! };
-//! # fn main() -> anyhow::Result<()> {
-//! // Set security policy for storing secrets
-//!
-//! secret_policy_try_use_memfd_secrets();
-//!
-//! // initialize secret and public key for peer a ...
-//! let (mut peer_a_sk, mut peer_a_pk) = (SSk::zero(), SPk::zero());
-//! StaticKem::keygen(peer_a_sk.secret_mut(), peer_a_pk.deref_mut())?;
-//!
-//! // ... and for peer b
-//! let (mut peer_b_sk, mut peer_b_pk) = (SSk::zero(), SPk::zero());
-//! StaticKem::keygen(peer_b_sk.secret_mut(), peer_b_pk.deref_mut())?;
-//!
-//! // initialize server and a pre-shared key
-//! let psk = SymKey::random();
-//! let mut a = CryptoServer::new(peer_a_sk, peer_a_pk.clone());
-//! let mut b = CryptoServer::new(peer_b_sk, peer_b_pk.clone());
-//!
-//! // introduce peers to each other
-//! a.add_peer(Some(psk.clone()), peer_b_pk)?;
-//! b.add_peer(Some(psk), peer_a_pk)?;
-//!
-//! // declare buffers for message exchange
-//! let (mut a_buf, mut b_buf) = (MsgBuf::zero(), MsgBuf::zero());
-//!
-//! // let a initiate a handshake
-//! let mut maybe_len = Some(a.initiate_handshake(PeerPtr(0), a_buf.as_mut_slice())?);
-//!
-//! // let a and b communicate
-//! while let Some(len) = maybe_len {
-//!    maybe_len = b.handle_msg(&a_buf[..len], &mut b_buf[..])?.resp;
-//!    std::mem::swap(&mut a, &mut b);
-//!    std::mem::swap(&mut a_buf, &mut b_buf);
-//! }
-//!
-//! // all done! Extract the shared keys and ensure they are identical
-//! let a_key = a.osk(PeerPtr(0))?;
-//! let b_key = b.osk(PeerPtr(0))?;
-//! assert_eq!(a_key.secret(), b_key.secret(),
-//!     "the key exchanged failed to establish a shared secret");
-//! # Ok(())
-//! # }
-//! ```
-
 use std::borrow::Borrow;
 use std::convert::Infallible;
 use std::fmt::Debug;
@@ -1358,7 +1286,6 @@ impl CryptoServer {
 
                 self.handle_resp_conf(&msg_in.payload)?
             }
-            Ok(MsgType::DataMsg) => bail!("DataMsg handling not implemented!"),
             Ok(MsgType::CookieReply) => {
                 let msg_in: Ref<&[u8], CookieReply> =
                     Ref::new(rx_buf).ok_or(RosenpassError::BufferSizeMismatch)?;

rosenpass/tests/api-integration-tests-api-setup.rs

@@ -33,8 +33,10 @@ struct KillChild(std::process::Child);
 
 impl Drop for KillChild {
     fn drop(&mut self) {
-        self.0.kill().discard_result();
-        self.0.wait().discard_result()
+        use rustix::process::{kill_process, Pid, Signal::Term};
+        let pid = Pid::from_child(&self.0);
+        rustix::process::kill_process(pid, Term).discard_result();
+        self.0.wait().discard_result();
     }
 }
 
@@ -153,7 +155,6 @@ fn api_integration_api_setup() -> anyhow::Result<()> {
                 peer_b.config_file_path.to_str().context("")?,
             ])
             .stdin(Stdio::null())
-            .stderr(Stdio::null())
             .stdout(Stdio::piped())
             .spawn()?,
     );

rosenpass/tests/main-fn-generates-manpages.rs

@@ -0,0 +1,99 @@
+use rosenpass_util::functional::ApplyExt;
+
+fn expect_section(manpage: &str, section: &str) -> anyhow::Result<()> {
+    anyhow::ensure!(manpage.lines().any(|line| { line.starts_with(section) }));
+    Ok(())
+}
+
+fn expect_sections(manpage: &str, sections: &[&str]) -> anyhow::Result<()> {
+    for section in sections.iter().copied() {
+        expect_section(manpage, section)?;
+    }
+    Ok(())
+}
+
+fn expect_contents(manpage: &str, patterns: &[&str]) -> anyhow::Result<()> {
+    for pat in patterns.iter().copied() {
+        anyhow::ensure!(manpage.contains(pat))
+    }
+    Ok(())
+}
+
+fn filter_backspace(str: &str) -> anyhow::Result<String> {
+    let mut out = String::new();
+    for chr in str.chars() {
+        if chr == '\x08' {
+            anyhow::ensure!(out.pop().is_some());
+        } else {
+            out.push(chr);
+        }
+    }
+    Ok(out)
+}
+
+/// Spot tests about man page generation; these are by far not exhaustive.
+#[test]
+fn main_fn_generates_manpages() -> anyhow::Result<()> {
+    let dir = tempfile::TempDir::with_prefix("rosenpass-test-main-fn-generates-mangapges")?;
+    let cmd_out = test_bin::get_test_bin("rosenpass")
+        .args(["--generate-manpage", dir.path().to_str().unwrap()])
+        .output()?;
+    assert!(cmd_out.status.success());
+
+    let expected_manpages = [
+        "rosenpass.1",
+        "rosenpass-exchange.1",
+        "rosenpass-exchange-config.1",
+        "rosenpass-gen-config.1",
+        "rosenpass-gen-keys.1",
+        "rosenpass-keygen.1",
+        "rosenpass-validate.1",
+    ];
+
+    let man_texts: std::collections::HashMap<&str, String> = expected_manpages
+        .iter()
+        .copied()
+        .map(|name| (name, dir.path().join(name)))
+        .map(|(name, path)| {
+            let res = std::process::Command::new("man").arg(path).output()?;
+            assert!(res.status.success());
+            let body = res
+                .stdout
+                .apply(String::from_utf8)?
+                .apply(|s| filter_backspace(&s))?;
+            Ok((name, body))
+        })
+        .collect::<anyhow::Result<_>>()?;
+
+    for (name, body) in man_texts.iter() {
+        expect_sections(body, &["NAME", "SYNOPSIS", "OPTIONS"])?;
+
+        if *name != "rosenpass.1" {
+            expect_section(body, "DESCRIPTION")?;
+        }
+    }
+
+    {
+        let body = man_texts.get("rosenpass.1").unwrap();
+        expect_sections(
+            body,
+            &["EXIT STATUS", "SEE ALSO", "STANDARDS", "AUTHORS", "BUGS"],
+        )?;
+        expect_contents(
+            body,
+            &[
+                "[--log-level]",
+                "rosenpass-exchange-config(1)",
+                "Start Rosenpass key exchanges based on a configuration file",
+                "https://rosenpass.eu/whitepaper.pdf",
+            ],
+        )?;
+    }
+
+    {
+        let body = man_texts.get("rosenpass-exchange.1").unwrap();
+        expect_contents(body, &["[-c|--config-file]", "PSK := preshared-key"])?;
+    }
+
+    Ok(())
+}

rosenpass/tests/main-fn-prints-errors.rs

@@ -0,0 +1,10 @@
+#[test]
+fn main_fn_prints_errors() -> anyhow::Result<()> {
+    let out = test_bin::get_test_bin("rosenpass")
+        .args(["exchange-config", "/"])
+        .output()?;
+    assert!(!out.status.success());
+    assert!(String::from_utf8(out.stderr)?.contains("Is a directory (os error 21)"));
+
+    Ok(())
+}

rp/Cargo.toml

@@ -12,6 +12,8 @@ repository = "https://github.com/rosenpass/rosenpass"
 [dependencies]
 anyhow = { workspace = true }
 base64ct = { workspace = true }
+serde = { workspace = true }
+toml = { workspace = true }
 x25519-dalek = { version = "2", features = ["static_secrets"] }
 zeroize = { workspace = true }
 
@@ -24,10 +26,11 @@ rosenpass-wireguard-broker = { workspace = true }
 
 tokio = { workspace = true }
 
-[target.'cfg(any(target_os = "linux", target_os = "freebsd"))'.dependencies]
-ctrlc-async = "3.2"
 futures = "0.3"
 futures-util = "0.3"
+
+[target.'cfg(any(target_os = "linux", target_os = "freebsd"))'.dependencies]
+ctrlc-async = "3.2"
 genetlink = "0.2"
 rtnetlink = "0.14"
 netlink-packet-core = "0.7"

rp/src/cli.rs

@@ -12,6 +12,9 @@ pub enum Command {
         public_keys_dir: PathBuf,
     },
     Exchange(ExchangeOptions),
+    ExchangeConfig {
+        config_file: PathBuf,
+    },
     Help,
 }
 
@@ -19,6 +22,7 @@ enum CommandType {
     GenKey,
     PubKey,
     Exchange,
+    ExchangeConfig,
 }
 
 #[derive(Default)]
@@ -32,9 +36,10 @@ fn fatal<T>(note: &str, command: Option<CommandType>) -> Result<T, String> {
         Some(command) => match command {
             CommandType::GenKey => Err(format!("{}\nUsage: rp genkey PRIVATE_KEYS_DIR", note)),
             CommandType::PubKey => Err(format!("{}\nUsage: rp pubkey PRIVATE_KEYS_DIR PUBLIC_KEYS_DIR", note)),
-            CommandType::Exchange => Err(format!("{}\nUsage: rp exchange PRIVATE_KEYS_DIR [dev <device>] [listen <ip>:<port>] [peer PUBLIC_KEYS_DIR [endpoint <ip>:<port>] [persistent-keepalive <interval>] [allowed-ips <ip1>/<cidr1>[,<ip2>/<cidr2>]...]]...", note)),
+            CommandType::Exchange => Err(format!("{}\nUsage: rp exchange PRIVATE_KEYS_DIR [dev <device>] [ip <ip1>/<cidr1>] [listen <ip>:<port>] [peer PUBLIC_KEYS_DIR [endpoint <ip>:<port>] [persistent-keepalive <interval>] [allowed-ips <ip1>/<cidr1>[,<ip2>/<cidr2>]...]]...", note)),
+            CommandType::ExchangeConfig => Err(format!("{}\nUsage: rp exchange-config <CONFIG_FILE>", note)),
         },
-        None => Err(format!("{}\nUsage: rp [verbose] genkey|pubkey|exchange [ARGS]...", note)),
+        None => Err(format!("{}\nUsage: rp [verbose] genkey|pubkey|exchange|exchange-config [ARGS]...", note)),
     }
 }
 
@@ -144,6 +149,13 @@ impl ExchangeOptions {
                         return fatal("dev option requires parameter", Some(CommandType::Exchange));
                     }
                 }
+                "ip" => {
+                    if let Some(ip) = args.next() {
+                        options.ip = Some(ip);
+                    } else {
+                        return fatal("ip option requires parameter", Some(CommandType::Exchange));
+                    }
+                }
                 "listen" => {
                     if let Some(addr) = args.next() {
                         if let Ok(addr) = addr.parse::<SocketAddr>() {
@@ -246,6 +258,21 @@ impl Cli {
                     let options = ExchangeOptions::parse(&mut args)?;
                     cli.command = Some(Command::Exchange(options));
                 }
+                "exchange-config" => {
+                    if cli.command.is_some() {
+                        return fatal("Too many commands supplied", None);
+                    }
+
+                    if let Some(config_file) = args.next() {
+                        let config_file = PathBuf::from(config_file);
+                        cli.command = Some(Command::ExchangeConfig { config_file });
+                    } else {
+                        return fatal(
+                            "Required position argument: CONFIG_FILE",
+                            Some(CommandType::ExchangeConfig),
+                        );
+                    }
+                }
                 "help" => {
                     cli.command = Some(Command::Help);
                 }

rp/src/exchange.rs

@@ -1,11 +1,17 @@
-use std::{net::SocketAddr, path::PathBuf};
+use anyhow::Error;
+use serde::Deserialize;
+use std::future::Future;
+use std::ops::DerefMut;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::{net::SocketAddr, path::PathBuf, process::Command};
 
 use anyhow::Result;
 
 #[cfg(any(target_os = "linux", target_os = "freebsd"))]
 use crate::key::WG_B64_LEN;
 
-#[derive(Default)]
+#[derive(Default, Deserialize)]
 pub struct ExchangePeer {
     pub public_keys_dir: PathBuf,
     pub endpoint: Option<SocketAddr>,
@@ -13,11 +19,12 @@ pub struct ExchangePeer {
     pub allowed_ips: Option<String>,
 }
 
-#[derive(Default)]
+#[derive(Default, Deserialize)]
 pub struct ExchangeOptions {
     pub verbose: bool,
     pub private_keys_dir: PathBuf,
     pub dev: Option<String>,
+    pub ip: Option<String>,
     pub listen: Option<SocketAddr>,
     pub peers: Vec<ExchangePeer>,
 }
@@ -131,6 +138,27 @@ mod netlink {
     }
 }
 
+#[derive(Clone)]
+#[cfg(any(target_os = "linux", target_os = "freebsd"))]
+struct CleanupHandlers(
+    Arc<::futures::lock::Mutex<Vec<Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>>>>,
+);
+
+#[cfg(any(target_os = "linux", target_os = "freebsd"))]
+impl CleanupHandlers {
+    fn new() -> Self {
+        CleanupHandlers(Arc::new(::futures::lock::Mutex::new(vec![])))
+    }
+
+    async fn enqueue(&self, handler: Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>) {
+        self.0.lock().await.push(Box::pin(handler))
+    }
+
+    async fn run(self) -> Result<Vec<()>, Error> {
+        futures::future::try_join_all(self.0.lock().await.deref_mut()).await
+    }
+}
+
 #[cfg(any(target_os = "linux", target_os = "freebsd"))]
 pub async fn exchange(options: ExchangeOptions) -> Result<()> {
     use std::fs;
@@ -151,15 +179,50 @@ pub async fn exchange(options: ExchangeOptions) -> Result<()> {
     let (connection, rtnetlink, _) = rtnetlink::new_connection()?;
     tokio::spawn(connection);
 
-    let link_name = options.dev.unwrap_or("rosenpass0".to_string());
+    let link_name = options.dev.clone().unwrap_or("rosenpass0".to_string());
     let link_index = netlink::link_create_and_up(&rtnetlink, link_name.clone()).await?;
 
+    let cleanup_handlers = CleanupHandlers::new();
+    let final_cleanup_handlers = (&cleanup_handlers).clone();
+
+    cleanup_handlers
+        .enqueue(Box::pin(async move {
+            netlink::link_cleanup_standalone(link_index).await
+        }))
+        .await;
+
     ctrlc_async::set_async_handler(async move {
-        netlink::link_cleanup_standalone(link_index)
+        final_cleanup_handlers
+            .run()
             .await
             .expect("Failed to clean up");
     })?;
 
+    if let Some(ip) = options.ip {
+        let dev = options.dev.clone().unwrap_or("rosenpass0".to_string());
+        Command::new("ip")
+            .arg("address")
+            .arg("add")
+            .arg(ip.clone())
+            .arg("dev")
+            .arg(dev.clone())
+            .status()
+            .expect("failed to configure ip");
+        cleanup_handlers
+            .enqueue(Box::pin(async move {
+                Command::new("ip")
+                    .arg("address")
+                    .arg("del")
+                    .arg(ip)
+                    .arg("dev")
+                    .arg(dev)
+                    .status()
+                    .expect("failed to remove ip");
+                Ok(())
+            }))
+            .await;
+    }
+
     // Deploy the classic wireguard private key
     let (connection, mut genetlink, _) = genetlink::new_connection()?;
     tokio::spawn(connection);
@@ -254,6 +317,29 @@ pub async fn exchange(options: ExchangeOptions) -> Result<()> {
             broker_peer,
             peer.endpoint.map(|x| x.to_string()),
         )?;
+
+        // Configure routes
+        if let Some(allowed_ips) = peer.allowed_ips {
+            Command::new("ip")
+                .arg("route")
+                .arg("replace")
+                .arg(allowed_ips.clone())
+                .arg("dev")
+                .arg(options.dev.clone().unwrap_or("rosenpass0".to_string()))
+                .status()
+                .expect("failed to configure route");
+            cleanup_handlers
+                .enqueue(Box::pin(async move {
+                    Command::new("ip")
+                        .arg("route")
+                        .arg("del")
+                        .arg(allowed_ips)
+                        .status()
+                        .expect("failed to remove ip");
+                    Ok(())
+                }))
+                .await;
+        }
     }
 
     let out = srv.event_loop();

rp/src/main.rs

@@ -1,4 +1,4 @@
-use std::process::exit;
+use std::{fs, process::exit};
 
 use cli::{Cli, Command};
 use exchange::exchange;
@@ -36,6 +36,13 @@ async fn main() {
             options.verbose = cli.verbose;
             exchange(options).await
         }
+        Command::ExchangeConfig { config_file } => {
+            let s: String = fs::read_to_string(config_file).expect("cannot read config");
+            let mut options: exchange::ExchangeOptions =
+                toml::from_str::<exchange::ExchangeOptions>(&s).expect("cannot parse config");
+            options.verbose = options.verbose || cli.verbose;
+            exchange(options).await
+        }
         Command::Help => {
             println!("Usage: rp [verbose] genkey|pubkey|exchange [ARGS]...");
             Ok(())

systemd/rosenpass.target

@@ -0,0 +1,2 @@
+[Unit]
+Description=Rosenpass target

systemd/rosenpass@.service

@@ -0,0 +1,47 @@
+[Unit]
+Description=Rosenpass key exchange for %I
+Documentation=man:rosenpass(1)
+Documentation=https://rosenpass.eu/docs
+
+After=network-online.target nss-lookup.target sys-devices-virtual-net-%i.device
+Wants=network-online.target nss-lookup.target
+BindsTo=sys-devices-virtual-net-%i.device
+PartOf=rosenpass.target
+
+[Service]
+ExecStart=rosenpass exchange-config /etc/rosenpass/%i.toml
+LoadCredential=pqsk:/etc/rosenpass/%i/pqsk
+
+AmbientCapabilities=CAP_NET_ADMIN
+CapabilityBoundingSet=~CAP_AUDIT_CONTROL CAP_AUDIT_READ CAP_AUDIT_WRITE CAP_BLOCK_SUSPEND CAP_BPF CAP_CHOWN CAP_FSETID CAP_SETFCAP CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_FOWNER CAP_IPC_OWNER CAP_IPC_LOCK CAP_KILL CAP_LEASE CAP_LINUX_IMMUTABLE CAP_MAC_ADMIN CAP_MAC_OVERRIDE CAP_MKNOD CAP_NET_BIND_SERVICE CAP_NET_BROADCAST CAP_NET_RAW CAP_SETUID CAP_SETGID CAP_SETPCAP CAP_SYS_ADMIN CAP_SYS_BOOT CAP_SYS_CHROOT CAP_SYSLOG CAP_SYS_MODULE CAP_SYS_NICE CAP_SYS_RESOURCE CAP_SYS_PACCT CAP_SYS_PTRACE CAP_SYS_RAWIO CAP_SYS_TIME CAP_SYS_TTY_CONFIG CAP_WAKE_ALARM
+DynamicUser=true
+LockPersonality=true
+MemoryDenyWriteExecute=true
+PrivateDevices=true
+ProcSubset=pid
+ProtectClock=true
+ProtectControlGroups=true
+ProtectHome=true
+ProtectHostname=true
+ProtectKernelLogs=true
+ProtectKernelModules=true
+ProtectKernelTunables=true
+ProtectProc=noaccess
+RestrictAddressFamilies=AF_NETLINK AF_INET AF_INET6
+RestrictNamespaces=true
+RestrictRealtime=true
+SystemCallArchitectures=native
+SystemCallFilter=~@clock
+SystemCallFilter=~@cpu-emulation
+SystemCallFilter=~@debug
+SystemCallFilter=~@module
+SystemCallFilter=~@mount
+SystemCallFilter=~@obsolete
+SystemCallFilter=~@privileged
+SystemCallFilter=~@raw-io
+SystemCallFilter=~@reboot
+SystemCallFilter=~@swap
+UMask=0077
+
+[Install]
+WantedBy=multi-user.target

systemd/rp@.service

@@ -0,0 +1,48 @@
+[Unit]
+Description=Rosenpass key exchange for %I
+Documentation=man:rosenpass(1)
+Documentation=https://rosenpass.eu/docs
+
+After=network-online.target nss-lookup.target
+Wants=network-online.target nss-lookup.target
+PartOf=rosenpass.target
+
+[Service]
+ExecStart=rp exchange-config /etc/rosenpass/%i.toml
+LoadCredential=pqpk:/etc/rosenpass/%i/pqpk
+LoadCredential=pqsk:/etc/rosenpass/%i/pqsk
+LoadCredential=wgsk:/etc/rosenpass/%i/wgsk
+
+AmbientCapabilities=CAP_NET_ADMIN
+CapabilityBoundingSet=~CAP_AUDIT_CONTROL CAP_AUDIT_READ CAP_AUDIT_WRITE CAP_BLOCK_SUSPEND CAP_BPF CAP_CHOWN CAP_FSETID CAP_SETFCAP CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_FOWNER CAP_IPC_OWNER CAP_IPC_LOCK CAP_KILL CAP_LEASE CAP_LINUX_IMMUTABLE CAP_MAC_ADMIN CAP_MAC_OVERRIDE CAP_MKNOD CAP_NET_BIND_SERVICE CAP_NET_BROADCAST CAP_NET_RAW CAP_SETUID CAP_SETGID CAP_SETPCAP CAP_SYS_ADMIN CAP_SYS_BOOT CAP_SYS_CHROOT CAP_SYSLOG CAP_SYS_MODULE CAP_SYS_NICE CAP_SYS_RESOURCE CAP_SYS_PACCT CAP_SYS_PTRACE CAP_SYS_RAWIO CAP_SYS_TIME CAP_SYS_TTY_CONFIG CAP_WAKE_ALARM
+DynamicUser=true
+LockPersonality=true
+MemoryDenyWriteExecute=true
+PrivateDevices=true
+ProcSubset=pid
+ProtectClock=true
+ProtectControlGroups=true
+ProtectHome=true
+ProtectHostname=true
+ProtectKernelLogs=true
+ProtectKernelModules=true
+ProtectKernelTunables=true
+ProtectProc=noaccess
+RestrictAddressFamilies=AF_NETLINK AF_INET AF_INET6
+RestrictNamespaces=true
+RestrictRealtime=true
+SystemCallArchitectures=native
+SystemCallFilter=~@clock
+SystemCallFilter=~@cpu-emulation
+SystemCallFilter=~@debug
+SystemCallFilter=~@module
+SystemCallFilter=~@mount
+SystemCallFilter=~@obsolete
+SystemCallFilter=~@privileged
+SystemCallFilter=~@raw-io
+SystemCallFilter=~@reboot
+SystemCallFilter=~@swap
+UMask=0077
+
+[Install]
+WantedBy=multi-user.target

tests/systemd/rosenpass.nix

@@ -0,0 +1,183 @@
+# This test is largely inspired from:
+# https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/rosenpass.nix
+# https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/wireguard/basic.nix
+{ pkgs, ... }:
+
+let
+  server = {
+    ip4 = "192.168.0.1";
+    ip6 = "fd00::1";
+    wg = {
+      ip4 = "10.23.42.1";
+      ip6 = "fc00::1";
+      public = "mQufmDFeQQuU/fIaB2hHgluhjjm1ypK4hJr1cW3WqAw=";
+      secret = "4N5Y1dldqrpsbaEiY8O0XBUGUFf8vkvtBtm8AoOX7Eo=";
+      listen = 10000;
+    };
+  };
+
+  client = {
+    ip4 = "192.168.0.2";
+    ip6 = "fd00::2";
+    wg = {
+      ip4 = "10.23.42.2";
+      ip6 = "fc00::2";
+      public = "Mb3GOlT7oS+F3JntVKiaD7SpHxLxNdtEmWz/9FMnRFU=";
+      secret = "uC5dfGMv7Oxf5UDfdPkj6rZiRZT2dRWp5x8IQxrNcUE=";
+    };
+  };
+
+  server_config = {
+    listen = [ "0.0.0.0:9999" ];
+    public_key = "/etc/rosenpass/rp0/pqpk";
+    secret_key = "/run/credentials/rosenpass@rp0.service/pqsk";
+    verbosity = "Verbose";
+    peers = [{
+      device = "rp0";
+      peer = client.wg.public;
+      public_key = "/etc/rosenpass/rp0/peers/client/pqpk";
+    }];
+  };
+  client_config = {
+    listen = [ ];
+    public_key = "/etc/rosenpass/rp0/pqpk";
+    secret_key = "/run/credentials/rosenpass@rp0.service/pqsk";
+    verbosity = "Verbose";
+    peers = [{
+      device = "rp0";
+      peer = server.wg.public;
+      public_key = "/etc/rosenpass/rp0/peers/server/pqpk";
+      endpoint = "${server.ip4}:9999";
+    }];
+  };
+
+  config = pkgs.runCommand "config" { } ''
+    mkdir -pv $out
+    cp -v ${(pkgs.formats.toml {}).generate "rp0.toml" server_config} $out/server
+    cp -v ${(pkgs.formats.toml {}).generate "rp0.toml" client_config} $out/client
+  '';
+in
+{
+  name = "rosenpass unit";
+
+  nodes =
+    let
+      shared = peer: { config, modulesPath, pkgs, ... }: {
+        # Need to work around a problem in recent systemd changes.
+        # It won't be necessary in other distros (for which the systemd file was designed), this is NixOS specific
+        # https://github.com/NixOS/nixpkgs/issues/258371#issuecomment-1925672767
+        # This can potentially be removed in future nixpkgs updates
+        systemd.packages = [
+          (pkgs.runCommand "rosenpass" { } ''
+            mkdir -p $out/lib/systemd/system
+            < ${pkgs.rosenpass}/lib/systemd/system/rosenpass.target > $out/lib/systemd/system/rosenpass.target
+            < ${pkgs.rosenpass}/lib/systemd/system/rosenpass@.service \
+            sed 's@^\(\[Service]\)$@\1\nEnvironment=PATH=${pkgs.wireguard-tools}/bin@' |
+            sed 's@^ExecStartPre=envsubst @ExecStartPre='"${pkgs.envsubst}"'/bin/envsubst @' |
+            sed 's@^ExecStart=rosenpass @ExecStart='"${pkgs.rosenpass}"'/bin/rosenpass @' > $out/lib/systemd/system/rosenpass@.service
+          '')
+        ];
+        networking.wireguard = {
+          enable = true;
+          interfaces.rp0 = {
+            ips = [ "${peer.wg.ip4}/32" "${peer.wg.ip6}/128" ];
+            privateKeyFile = "/etc/wireguard/wgsk";
+          };
+        };
+        environment.etc."wireguard/wgsk".text = peer.wg.secret;
+        networking.interfaces.eth1 = {
+          ipv4.addresses = [{
+            address = peer.ip4;
+            prefixLength = 24;
+          }];
+          ipv6.addresses = [{
+            address = peer.ip6;
+            prefixLength = 64;
+          }];
+        };
+      };
+    in
+    {
+      server = {
+        imports = [ (shared server) ];
+        networking.firewall.allowedUDPPorts = [ 9999 server.wg.listen ];
+        networking.wireguard.interfaces.rp0 = {
+          listenPort = server.wg.listen;
+          peers = [
+            {
+              allowedIPs = [ client.wg.ip4 client.wg.ip6 ];
+              publicKey = client.wg.public;
+            }
+          ];
+        };
+      };
+      client = {
+        imports = [ (shared client) ];
+        networking.wireguard.interfaces.rp0 = {
+          peers = [
+            {
+              allowedIPs = [ "10.23.42.0/24" "fc00::/64" ];
+              publicKey = server.wg.public;
+              endpoint = "${server.ip4}:${toString server.wg.listen}";
+            }
+          ];
+        };
+      };
+    };
+  testScript = { ... }: ''
+    from os import system
+    rosenpass = "${pkgs.rosenpass}/bin/rosenpass"
+
+    start_all()
+
+    for machine in [server, client]:
+      machine.wait_for_unit("multi-user.target")
+      machine.wait_for_unit("network-online.target")
+
+    with subtest("Key, Config, and Service Setup"):
+      for name, machine, remote in [("server", server, client), ("client", client, server)]:
+        # generate all the keys
+        system(f"{rosenpass} gen-keys --public-key {name}-pqpk --secret-key {name}-pqsk")
+
+        # copy private keys to our side
+        machine.copy_from_host(f"{name}-pqsk", "/etc/rosenpass/rp0/pqsk")
+        machine.copy_from_host(f"{name}-pqpk", "/etc/rosenpass/rp0/pqpk")
+
+        # copy public keys to other side
+        remote.copy_from_host(f"{name}-pqpk", f"/etc/rosenpass/rp0/peers/{name}/pqpk")
+
+        machine.copy_from_host(f"${config}/{name}", "/etc/rosenpass/rp0.toml")
+
+      for machine in [server, client]:
+        machine.wait_for_unit("wireguard-rp0.service")
+
+    with subtest("wg network test"):
+      client.succeed("wg show all preshared-keys | grep none", timeout=5);
+      client.succeed("ping -c5 ${server.wg.ip4}")
+      server.succeed("ping -c5 ${client.wg.ip6}")
+
+    with subtest("Set up rosenpass"):
+      for machine in [server, client]:
+        machine.succeed("systemctl start rosenpass@rp0.service")
+
+      for machine in [server, client]:
+        machine.wait_for_unit("rosenpass@rp0.service")
+
+
+    with subtest("compare preshared keys"):
+      client.wait_until_succeeds("wg show all preshared-keys | grep --invert-match none", timeout=5);
+      server.wait_until_succeeds("wg show all preshared-keys | grep --invert-match none", timeout=5);
+
+      def get_psk(m):
+        psk = m.succeed("wg show rp0 preshared-keys | awk '{print $2}'")
+        psk = psk.strip()
+        assert len(psk.split()) == 1, "Only one PSK"
+        return psk
+
+      assert get_psk(client) == get_psk(server), "preshared keys need to match"
+
+    with subtest("rosenpass network test"):
+      client.succeed("ping -c5 ${server.wg.ip4}")
+      server.succeed("ping -c5 ${client.wg.ip6}")
+  '';
+}

tests/systemd/rp.nix

@@ -0,0 +1,139 @@
+{ pkgs, ... }:
+
+let
+  server = {
+    ip4 = "192.168.0.1";
+    ip6 = "fd00::1";
+    wg = {
+      ip6 = "fc00::1";
+      listen = 10000;
+    };
+  };
+
+  client = {
+    ip4 = "192.168.0.2";
+    ip6 = "fd00::2";
+    wg = {
+      ip6 = "fc00::2";
+    };
+  };
+
+  server_config = {
+    listen = "${server.ip4}:9999";
+    private_keys_dir = "/run/credentials/rp@test-rp-device0.service";
+    verbose = true;
+    dev = "test-rp-device0";
+    ip = "fc00::1/64";
+    peers = [{
+      public_keys_dir = "/etc/rosenpass/test-rp-device0/peers/client";
+      allowed_ips = "fc00::2";
+    }];
+  };
+  client_config = {
+    private_keys_dir = "/run/credentials/rp@test-rp-device0.service";
+    verbose = true;
+    dev = "test-rp-device0";
+    ip = "fc00::2/128";
+    peers = [{
+      public_keys_dir = "/etc/rosenpass/test-rp-device0/peers/server";
+      endpoint = "${server.ip4}:9999";
+      allowed_ips = "fc00::/64";
+    }];
+  };
+
+  config = pkgs.runCommand "config" { } ''
+    mkdir -pv $out
+    cp -v ${(pkgs.formats.toml {}).generate "test-rp-device0.toml" server_config} $out/server
+    cp -v ${(pkgs.formats.toml {}).generate "test-rp-device0.toml" client_config} $out/client
+  '';
+in
+{
+  name = "rp systemd unit";
+
+  nodes =
+    let
+      shared = peer: { config, modulesPath, pkgs, ... }: {
+        # Need to work around a problem in recent systemd changes.
+        # It won't be necessary in other distros (for which the systemd file was designed), this is NixOS specific
+        # https://github.com/NixOS/nixpkgs/issues/258371#issuecomment-1925672767
+        # This can potentially be removed in future nixpkgs updates
+        systemd.packages = [
+          (pkgs.runCommand "rp@.service" { } ''
+            mkdir -p $out/lib/systemd/system
+            < ${pkgs.rosenpass}/lib/systemd/system/rosenpass.target > $out/lib/systemd/system/rosenpass.target
+            < ${pkgs.rosenpass}/lib/systemd/system/rp@.service \
+            sed 's@^\(\[Service]\)$@\1\nEnvironment=PATH=${pkgs.iproute2}/bin:${pkgs.wireguard-tools}/bin@' |
+            sed 's@^ExecStartPre=envsubst @ExecStartPre='"${pkgs.envsubst}"'/bin/envsubst @' |
+            sed 's@^ExecStart=rp @ExecStart='"${pkgs.rosenpass}"'/bin/rp @' > $out/lib/systemd/system/rp@.service
+          '')
+        ];
+        environment.systemPackages = [ pkgs.wireguard-tools ];
+        networking.interfaces.eth1 = {
+          ipv4.addresses = [{
+            address = peer.ip4;
+            prefixLength = 24;
+          }];
+          ipv6.addresses = [{
+            address = peer.ip6;
+            prefixLength = 64;
+          }];
+        };
+      };
+    in
+    {
+      server = {
+        imports = [ (shared server) ];
+        networking.firewall.allowedUDPPorts = [ 9999 server.wg.listen ];
+      };
+      client = {
+        imports = [ (shared client) ];
+      };
+    };
+  testScript = { ... }: ''
+    from os import system
+    rp = "${pkgs.rosenpass}/bin/rp"
+
+    start_all()
+
+    for machine in [server, client]:
+      machine.wait_for_unit("multi-user.target")
+      machine.wait_for_unit("network-online.target")
+
+    with subtest("Key, Config, and Service Setup"):
+      for name, machine, remote in [("server", server, client), ("client", client, server)]:
+        # create all the keys
+        system(f"{rp} genkey {name}-sk")
+        system(f"{rp} pubkey {name}-sk {name}-pk")
+
+        # copy secret keys to our side
+        for file in ["pqpk", "pqsk", "wgsk"]:
+          machine.copy_from_host(f"{name}-sk/{file}", f"/etc/rosenpass/test-rp-device0/{file}")
+        # copy public keys to other side
+        for file in ["pqpk", "wgpk"]:
+          remote.copy_from_host(f"{name}-pk/{file}", f"/etc/rosenpass/test-rp-device0/peers/{name}/{file}")
+
+        machine.copy_from_host(f"${config}/{name}", "/etc/rosenpass/test-rp-device0.toml")
+
+      for machine in [server, client]:
+        machine.succeed("systemctl start rp@test-rp-device0.service")
+
+      for machine in [server, client]:
+        machine.wait_for_unit("rp@test-rp-device0.service")
+
+    with subtest("compare preshared keys"):
+      client.wait_until_succeeds("wg show all preshared-keys | grep --invert-match none", timeout=5);
+      server.wait_until_succeeds("wg show all preshared-keys | grep --invert-match none", timeout=5);
+
+      def get_psk(m):
+        psk = m.succeed("wg show test-rp-device0 preshared-keys | awk '{print $2}'")
+        psk = psk.strip()
+        assert len(psk.split()) == 1, "Only one PSK"
+        return psk
+
+      assert get_psk(client) == get_psk(server), "preshared keys need to match"
+
+    with subtest("network test"):
+      client.succeed("ping -c5 ${server.wg.ip6}")
+      server.succeed("ping -c5 ${client.wg.ip6}")
+  '';
+}