# libsoliton

Pure-Rust post-quantum cryptographic library. Provides composite identity keys (X-Wing + ML-DSA-65), hybrid signatures, KEM-based authentication, asynchronous key exchange, double-ratchet message encryption, and encrypted storage — all without a C toolchain.

**Use cases:** any application requiring two-party encrypted communication or authenticated key agreement — messaging, voice/video calls, peer-to-peer sessions, file transfer, encrypted storage, zero-knowledge authentication, password-protected key vaults. The library provides the complete primitive stack; the application layer decides the transport and session management.

## Documentation

| Document | Description |
|----------|-------------|
| [Abstract.md](Abstract.md) | Security analysis specification — adversary model, theorems, and verification targets for formal modeling |
| [Specification.md](Specification.md) | Full cryptographic specification (v1) |
| [CHEATSHEET.md](CHEATSHEET.md) | API quick reference with types, sizes, and signatures |

## Crate Layout

| Package | Path | Purpose |
|---------|------|---------|
| `libsoliton` (crates.io) | `soliton/` | Core library — all cryptographic logic |
| `libsoliton_capi` (crates.io) | `soliton_capi/` | C ABI FFI layer (cbindgen-generated header) |
| `soliton` (PyPI) | `soliton_py/` | Python binding (PyO3/maturin, wraps core Rust API) |
| `soliton-wasm` (npm) | `soliton_wasm/` | WASM binding (wasm-bindgen, wraps core Rust API) |
| `soliton-cli` (cargo) | `soliton_cli/` | Native CLI (`cargo install soliton-cli`) |
| `soliton_zig` | `soliton_zig/` | Zig wrapper (consumes CAPI via `@cImport`) |

## Testing

**By location** (non-overlapping — these add up to the total):

| Location | Count | Description |
|----------|-------|-------------|
| Core unit tests | 488 | `soliton/src/**/` `#[cfg(test)]` — unit tests + proptests |
| Core integration tests | 61 | `soliton/tests/` — KEX → ratchet, storage round-trips, argon2, zeroization verification, Appendix F vectors |
| CAPI tests | 287 | `soliton_capi/tests/` — null pointers, invalid lengths, round-trips, error codes |
| Python tests | 49 | `soliton_py/tests/` — full KEX → ratchet round-trip, serialize, reset, call keys, storage, streaming (_at), auth, identity, primitives |
| Zig tests | 35 | `soliton_zig/src/soliton.zig` — full KEX → ratchet round-trip, serialize, reset, call keys, storage, streaming (_at), auth, AEAD, X-Wing, argon2id |
| WASM tests | 36 | `soliton_wasm/tests/` — full KEX → ratchet lifecycle, serialize/deserialize, call keys, storage, streaming (_at), auth, identity, primitives, argon2id (Node + Chromium) |
| Fuzz targets | 36 | `*/fuzz/fuzz_targets/` — 29 core + 7 CAPI (`cargo-fuzz` / libFuzzer) |

**Cross-cutting** (subsets of the above):

| Property | Count | Subset of | Description |
|----------|-------|-----------|-------------|
| MIRI-eligible | 455 | core + CAPI | PQ-free subset safe for instruction-level interpretation (`--profile miri`) |
| KAT vectors | 27 | core unit + integration | 17 in `src/**/` `#[cfg(test)]` — SHA3-256, HMAC-SHA3-256, HKDF-SHA3-256, Ed25519, X25519, X-Wing, AEAD, KDF, KEX, streaming, call; 10 in `tests/compute_vectors.rs` — Specification.md Appendix F vectors F.25-F.37 (HKDF, AEAD, HybridSign, streaming, Argon2, HMAC long-key, first-message AAD, SPK sig, session-init sig, LO-Auth) |

```bash
# Full test suite
cargo test -p libsoliton -p libsoliton_capi

# MIRI (requires nightly)
MIRIFLAGS="-Zmiri-disable-isolation" cargo +nightly miri nextest run \
  -p libsoliton -p libsoliton_capi --profile miri -j$(nproc)

# Fuzzing — corpus regression (replays all seeds, no mutations, fast)
./ci_regression.sh

# Fuzzing — overnight campaign (all active targets in parallel)
./fuzz_overnight.sh 24 2    # 24 hours, 2 workers per target
./fuzz_stats.sh             # Post-run summary
```

## Fuzzing

36 fuzz targets (29 core + 7 CAPI) with two corpora (core: `soliton/fuzz/corpus/`, CAPI: `soliton_capi/fuzz/corpus/`) totaling 165,540 entries (883 MB). All corpora are checked in via Git LFS; `ci_regression.sh` replays every seed with zero mutations as a CI regression gate.

**Excluded targets** — 5 of 36 are excluded from overnight campaigns after saturation analysis. All reachable edges were discovered; additional CPU time yields no new coverage. These targets retain their corpora and run in `ci_regression.sh`.

| Target | Corpus | Edges | Reason |
|---|---|---|---|
| `fuzz_identity_from_bytes` | 84 | 107 | 3 length checks only |
| `fuzz_auth_verify` | ~15 | 88 | Single `ct_eq` call |
| `fuzz_xwing_roundtrip` | 7 | 763 | No adversarial input (keygen→encap→decap) |
| `fuzz_verification_phrase` | 29 | 88 | SHA3→wordlist index, trivial surface |
| `fuzz_auth_respond` | 4 | 1573 | Single KEM decap→HMAC, no branching on input |

**Latest campaign** — 31 targets (24 core + 7 CAPI), 1 libFuzzer worker per target, Hetzner CCX53 (32 vCPUs, AMD EPYC, 128 GB RAM), 24 hours.

| Metric | Value |
|---|---|
| **Total targets** | 36 (29 core + 7 CAPI) |
| **Active in campaign** | 31 |
| **Total executions** | 574.6 billion |
| **Corpus** | 165,540 entries (883 MB) |
| **Crashes / Timeouts / OOM** | **0 / 0 / 0** |

The state-machine fuzzer (`fuzz_ratchet_state_machine`) performs full cryptographic sessions with up to 200 protocol actions per execution (KEM, AEAD, HKDF, HMAC per message) — 12,714 coverage features, the highest of any target.

```bash
./ci_regression.sh          # Replay all seeds — fast, runs in CI
./fuzz_overnight.sh 24 1    # 31 active targets, 24 hours, 1 worker each
./fuzz_stats.sh             # Per-target breakdown (edges, features, throughput, RSS)
```

## Benchmarks

Measured with `cargo +nightly bench` across three platforms. ML-DSA-65, SHA3-256, and Keccak do not have SIMD implementations in the current RustCrypto crates — expect these numbers to improve as upstream adds platform-specific optimizations. All operations are pure ARX or field arithmetic; no hardware acceleration is required.

**Platform support:** Tested on x86-64, aarch64, riscv64gc, and wasm32. 32-bit native platforms are untested and unsupported — the library uses `u64` extensively and the PQ primitives have non-trivial stack requirements.

| Platform | CPU | Arch | Clock |
|----------|-----|------|-------|
| **Desktop** | AMD Ryzen 7 7840HS | x86-64 (Zen 4) | ~5.1 GHz boost |
| **RPi 5** | Cortex-A76 | aarch64 | 2.4 GHz |
| **VisionFive 2** | SiFive U74 | riscv64gc | 1.5 GHz |

**Per-message hot paths** (what users feel on every send/receive):

| Operation | Desktop | RPi 5 | VisionFive 2 | Notes |
|-----------|---------|-------|-------------|-------|
| Ratchet encrypt (same epoch) | 4.3 µs | 7.2 µs | 47.6 µs | HMAC-SHA3-256 + XChaCha20-Poly1305 |
| Ratchet decrypt (same epoch) | 6.2 µs | 10.1 µs | 67.5 µs | Includes `from_bytes` deserialization |
| KDF root (isolated) | 5.7 µs | 9.2 µs | 59.5 µs | HKDF-SHA3-256, 64-byte output |
| Ratchet serialize | 1.6 µs | 6.1 µs | 38.1 µs | `to_bytes` |
| Ratchet deserialize | 0.7 µs | 2.7 µs | 17.8 µs | `from_bytes_with_min_epoch` |

**Direction-change paths** (one KEM round-trip per direction switch):

| Operation | Desktop | RPi 5 | VisionFive 2 | Notes |
|-----------|---------|-------|-------------|-------|
| Ratchet encrypt (direction change) | 182 µs | 651 µs | 2.46 ms | X-Wing keygen + encapsulate + KDF |
| Ratchet decrypt (direction change) | 127 µs | 473 µs | 1.76 ms | X-Wing decapsulate + KDF |

**Session establishment** (one-time per conversation):

| Operation | Desktop | RPi 5 | VisionFive 2 | Notes |
|-----------|---------|-------|-------------|-------|
| Identity keygen | 417 µs | 1.05 ms | 4.90 ms | X-Wing + Ed25519 + ML-DSA-65 |
| Hybrid sign | 988 µs | 2.85 ms | 10.6 ms | Ed25519 + ML-DSA-65 (no SIMD) |
| Hybrid verify | 254 µs | 794 µs | 3.31 ms | Ed25519 + ML-DSA-65 (no SIMD) |
| X-Wing encapsulate | 104 µs | 417 µs | 1.44 ms | X25519 + ML-KEM-768 |
| X-Wing decapsulate | 112 µs | 451 µs | 1.61 ms | X25519 + ML-KEM-768 |
| Initiate session (Alice) | 1.41 ms | 3.95 ms | 17.1 ms | Ephemeral keygen + 3 encaps + HKDF + sign |
| Receive session (Bob) | 585 µs | 1.88 ms | 7.70 ms | Verify + 3 decaps + HKDF |

**Streaming AEAD** (file/media encryption):

| Operation | Desktop | RPi 5 | VisionFive 2 | Notes |
|-----------|---------|-------|-------------|-------|
| Encrypt 1 MiB | 537 µs (1.95 GB/s) | 3.96 ms (265 MB/s) | 31.0 ms (33.8 MB/s) | XChaCha20-Poly1305, single chunk |
| Decrypt 1 MiB | 749 µs (1.40 GB/s) | 4.74 ms (221 MB/s) | 34.9 ms (30.0 MB/s) | Includes init overhead |
| Encrypt 4 MiB sequential | 2.58 ms (1.55 GB/s) | 15.8 ms (253 MB/s) | 124 ms (32.3 MB/s) | 4 chunks, sequential API |
| Encrypt 4 MiB parallel | 867 µs (4.61 GB/s) | 5.35 ms (748 MB/s) | 33.0 ms (121 MB/s) | 4 chunks via `encrypt_chunk_at`, rayon (4 cores) |
| Encrypt 8 MiB parallel | 1.29 ms (6.21 GB/s) | 10.7 ms (748 MB/s) | 67.8 ms (118 MB/s) | 8 chunks, 2 rounds on 4 cores |

**Password KDF** (key vault protection):

| Operation | Desktop | RPi 5 | VisionFive 2 | Notes |
|-----------|---------|-------|-------------|-------|
| Argon2id OWASP minimum | 10.9 ms | 42.0 ms | 256 ms | 19 MiB, 2 passes, 1 lane |
| Argon2id recommended | 65.0 ms | 227 ms | 1.35 s | 64 MiB, 3 passes, 4 lanes |

## License

[AGPL-3.0-only](LICENSE.md)