commit 5232663aa04970d2c1f37ccd9a8c1ce4e9d9cff8 Author: kamal Date: Thu Apr 2 20:49:22 2026 +0000 Add Home diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..dab68af --- /dev/null +++ b/Home.md @@ -0,0 +1,84 @@ +# 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