# libsoliton

Pure-Rust post-quantum cryptographic library for end-to-end encrypted communications.

## What It Does

libsoliton implements a complete cryptographic protocol stack for applications that need end-to-end encryption resistant to both classical and quantum adversaries:

- **Composite identity keys** — X-Wing (X25519 + ML-KEM-768) for key encapsulation, Ed25519 + ML-DSA-65 for signatures. Every identity operation uses both a classical and post-quantum algorithm; both must succeed.
- **Asynchronous key exchange** (LO-KEX) — a KEM-based protocol analogous to X3DH but built on encapsulation rather than Diffie-Hellman. Supports offline recipients via pre-key bundles.
- **Double ratchet** (LO-Ratchet) — forward-secret, post-compromise-secure message encryption using X-Wing KEM ratchet steps and HKDF-SHA3-256 chain derivation.
- **Encrypted storage** — Argon2id-protected key vaults with XChaCha20-Poly1305 and zstd compression.
- **Streaming AEAD** — chunked encryption for large payloads (files, media) with random-access decrypt support.
- **KEM-based authentication** — zero-knowledge proof of identity key possession without revealing the key.

## Why It Exists

The "harvest now, decrypt later" threat is real: adversaries are collecting encrypted traffic today with the expectation that future quantum computers will break classical key exchange. Encrypted messaging, file storage, and voice/video calls established with ECDH or RSA key agreement are retroactively compromised the moment a sufficiently powerful quantum computer comes online.

libsoliton pairs every classical primitive with a NIST-standardized post-quantum counterpart — ML-KEM-768 for key encapsulation (FIPS 203), ML-DSA-65 for signatures (FIPS 204) — so that the system remains secure even if one algorithm family is completely broken.

This is not speculative. NIST finalized ML-KEM and ML-DSA in 2024. X-Wing, the hybrid KEM construction, is an active IETF draft ([draft-connolly-cfrg-xwing-kem-09](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/)). The post-quantum transition is happening now; libsoliton is built to be used now.

## Who It's For

Developers building applications that require end-to-end encryption and want post-quantum security without depending on C toolchains, system OpenSSL installations, or assembly-language cryptographic backends.

- End-to-end encrypted messaging (the primary target)
- Encrypted voice and video calls (call key derivation from ratchet state)
- Encrypted cloud storage and file transfer
- Password-protected key vaults
- Zero-knowledge authentication

## Design Principles

| Principle | Implementation |
|-----------|---------------|
| Pure Rust, zero C dependencies | All cryptographic backends are Rust crates from RustCrypto and dalek-cryptography. No cmake, no system linker dependencies, no vendored C. |
| Hybrid everywhere | Every key exchange uses X-Wing (X25519 + ML-KEM-768). Every signature uses Ed25519 + ML-DSA-65. Both components must succeed — no fallback to classical-only. |
| Constant-time by construction | XChaCha20-Poly1305 uses ARX operations only — no table lookups, no secret-dependent branches. No hardware acceleration required. |
| Defense in depth | Ratchet state snapshot/rollback on AEAD failure. Zeroization of all secret key material. Domain-separated KDF with unique labels per derivation context. |
| Single audit point | All language bindings call through one C ABI layer into the same Rust implementation. One codebase to audit. |

## At a Glance

| Primitive | Algorithm | Key / Output Size |
|-----------|-----------|-------------------|
| Identity KEM | X-Wing (X25519 + ML-KEM-768) | 1216 B pk / 2432 B sk |
| Identity Signing | Ed25519 + ML-DSA-65 | 3373 B hybrid signature |
| Symmetric AEAD | XChaCha20-Poly1305 | 256-bit key / 128-bit tag |
| Hash | SHA3-256 (FIPS 202) | 32 B |
| KDF | HKDF-SHA3-256 | Variable (max 8160 B) |
| Streaming AEAD | XChaCha20-Poly1305, counter nonces | 1 MiB chunks |
| Password KDF | Argon2id (RFC 9106) | Configurable output |

## 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) |
| `soliton-wasm` (npm) | `soliton_wasm/` | WASM binding (wasm-bindgen) |
| `soliton-cli` (cargo) | `soliton_cli/` | Native CLI |
| `soliton_zig` | `soliton_zig/` | Zig wrapper (consumes CAPI via `@cImport`) |

## Performance

| Operation | Desktop | RPi 5 | VisionFive 2 |
|-----------|---------|-------|--------------|
| Ratchet encrypt (same direction) | 4.3 µs | 7.2 µs | 47.6 µs |
| Ratchet encrypt (direction change) | 182 µs | 651 µs | 2.46 ms |
| Session establishment (initiator) | 1.41 ms | 3.95 ms | 17.1 ms |
| Session establishment (responder) | 585 µs | 1.88 ms | 7.70 ms |
| Streaming encrypt (1 MiB) | 537 µs | 3.96 ms | 31.0 ms |

Desktop: AMD Ryzen 7 7840HS (Zen 4). RPi 5: Cortex-A76. VisionFive 2: SiFive U74 (RISC-V). See [Audit & Testing](Audit-and-Testing) for full benchmark tables.

## Source & Packages

- [git.lo.sh/lo/libsoliton](https://git.lo.sh/lo/libsoliton) — source repository
- [docs.rs/libsoliton](https://docs.rs/libsoliton) — Rust API documentation
- [pypi.org/project/soliton](https://pypi.org/project/soliton) — Python package
- [npmjs.com/package/soliton-wasm](https://www.npmjs.com/package/soliton-wasm) — WASM package