84 lines
5.5 KiB
Markdown
84 lines
5.5 KiB
Markdown
# 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
|