# krypteia — Post-Quantum and Classical Cryptography in Rust [![quantica on crates.io](https://img.shields.io/crates/v/krypteia-quantica?label=quantica)](https://crates.io/crates/krypteia-quantica) [![arcana on crates.io](https://img.shields.io/crates/v/krypteia-arcana?label=arcana)](https://crates.io/crates/krypteia-arcana) [![docs](https://img.shields.io/badge/docs-krypteia--rs.dev-3fb950)](https://krypteia-rs.dev) [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/cslashm/krypteia/blob/main/LICENSE) A pure-Rust cryptographic workspace covering both **post-quantum** and **classical** cryptography, with **zero external dependencies** (only the Rust standard library, and `core` + `alloc` in `no_std` mode). Designed from the start for embedded targets — secure elements, Cortex-M, RISC-V — and hardened against physical side-channel attacks. The name **Krypteia** comes from the Greek κρυπτεία (*"the hidden things"*), the same root that gave us *cryptography* — and a nod to ancient Sparta, often cited as one of the earliest practitioners of secret communication. **Documentation:** · **Crates:** [krypteia-silentops](https://crates.io/crates/krypteia-silentops) · [krypteia-memory](https://crates.io/crates/krypteia-memory) · [krypteia-tessera](https://crates.io/crates/krypteia-tessera) · [krypteia-quantica](https://crates.io/crates/krypteia-quantica) · [krypteia-arcana](https://crates.io/crates/krypteia-arcana) · **API docs (docs.rs):** [silentops](https://docs.rs/krypteia-silentops) · [memory](https://docs.rs/krypteia-memory) · [tessera](https://docs.rs/krypteia-tessera) · [quantica](https://docs.rs/krypteia-quantica) · [arcana](https://docs.rs/krypteia-arcana) · **Source:** ## Goals The workspace is built around five non-negotiable rules that apply to **every** crate, classical or post-quantum: 1. **Pure Rust, zero external crates** — only the standard library (`std` / `core` / `alloc`). 2. **Side-channel hardened** against SPA, DPA, DFA, template attacks, and timing attacks. Constant-time primitives are implemented in architecture-specific assembly for several embedded targets. 3. **Embedded-friendly** — small RAM footprint, fits secure elements, STM32 (Cortex-M0/M4/M33), RISC-V parts (ESP32-C3, …). 4. **Validated** against the official NIST ACVP test vectors at minimum, plus Wycheproof edge-case vectors and other recognized vector sets. 5. **Usable from C and JavaScript** through dedicated FFI and WebAssembly crates. The Rust API is the v0.1 stable contract; the `*_ffi` and `quantica_wasm` crates ship as previews in v0.1 (workspace-internal, `publish = false` on crates.io) and stabilise in v0.2. ## Status The pre-1.0 releases (`v0.1`, `v0.2`) are a deliberate first cut: the five published library crates (`krypteia-silentops`, `krypteia-memory`, `krypteia-tessera`, `krypteia-quantica`, `krypteia-arcana` on crates.io — imported in code as the bare `silentops` / `memory` / `tessera` / `quantica` / `arcana` paths via `[lib] name = ""` overrides) are **functional, continuously exercised**, and ready to depend on for prototyping and evaluation. The pre-`1.0` version number reflects that the public Rust API is not yet semver-locked, not that the code is unfinished. | Concern | v0.1 state | |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | Functional correctness | The library unit-test suites pass across the five published library crates, plus the workspace-level NIST ACVP / Wycheproof / CAVP vector corpora. | | Cross-architecture validation | 7 targets exercised on every push: 3 Linux triplets (`aarch64`, `armv7`, `riscv64gc`) under `cross` + qemu-user; 4 bare-metal targets (`riscv32imc` ESP32-C3, `riscv32imac` ESP32-C6/H2, `thumbv6m` Cortex-M0, `thumbv7em` Cortex-M4F) under `qemu-system`. | | Side-channel verification | `ctgrind` (Valgrind memcheck) and `dudect` (Welch t-test) run green on the host CI for every `silentops::ct::*` primitive and every published hot path in `quantica` / `arcana`. | | Public availability | GitHub: [github.com/cslashm/krypteia](https://github.com/cslashm/krypteia). crates.io: the five library crates (`krypteia-silentops`, `krypteia-memory`, `krypteia-tessera`, `krypteia-quantica`, `krypteia-arcana`) plus the C-ABI (`*_ffi`) and WebAssembly (`*_wasm`) bindings, all published from v0.2. docs.rs auto-built per crate; long-form pack at [krypteia-rs.dev](https://krypteia-rs.dev). | | License | Apache-2.0 (single licence across the workspace). | **Honest caveats (what `v0.1` does NOT promise):** * **Pre-`1.0`** — breaking API changes may land in `v0.2` as the Rust surface is reviewed and stabilised. Pin a specific version range for production-class consumers. * **No third-party evaluation yet** — `krypteia` is structured for a lab-class external evaluation but that pass has not happened. Do not deploy `v0.1` in a context that requires an audited cryptographic library. * **Per-primitive hardening tier varies** — every primitive has a documented tier (`T1` = active-vulnerability mitigated, `T2` = standard hardening, `T3` = verification tooling, `T4` = deferred / beyond `v0.1` scope). Some primitives carry stub implementations (Ed448) or `T2`-tier hardening pending (`quantica` `T2-A`/`B`/`D`, `arcana` `T1-A`...`T2-K`). See each crate's Roadmap chapter for the full status matrix. * **C and JavaScript bindings are previews** — `*_ffi` and `quantica_wasm` ship as workspace-internal previews (`publish = false`). The C ABI and JS surface stabilise in `v0.2`. For reviewers and external auditors: every claim above is backed by machine-checkable evidence under each crate's `doc/sca/` tree and the workspace `tools/` scripts (`tools/ctgrind.sh`, `tools/qemu-{user,system,vector}-tests.sh`, `tools/stack-sizes.sh`). The full per-release feature list and known limitations live in **[CHANGELOG](../_gen/changelog.md)**. ## Workspace layout | Crate | Path | v0.1 status | Role | |----------------------------------------|-----------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`krypteia-quantica`](../_gen/quantica_overview.md) | `quantica/` | **published** | **Post-quantum cryptography**: ML-KEM (FIPS 203), ML-DSA (FIPS 204), SLH-DSA (FIPS 205). Feature-gated algorithms, first-order DPA masking + shuffled NTT, typed Zeroize-on-Drop key wrappers, `no_std` support. Import as `use quantica::*` ([lib] name override). | | [`krypteia-arcana`](../_gen/arcana_overview.md) | `arcana/` | **published** | **Classical cryptography**: RSA, ECDSA / ECDH (NIST / SECG / BSI curves), EdDSA / EdDH (Ed25519, X25519, X448; Ed448 stub for v0.2), AES, DES / 3DES, ChaCha20-Poly1305, hashes (SHA-1/2/3, RIPEMD-160), MACs. Custom API + `RustCrypto` trait bridges. Import as `use arcana::*`. | | [`krypteia-silentops`](../_gen/silentops_overview.md) | `silentops/` | **published** | **Side-channel toolkit**: constant-time primitives (`ct_eq`, `ct_select_*`, `ct_zeroize`, …) with arch-specific asm backends, plus a dudect-style timing leakage verifier exposed as a reusable library. Import as `use silentops::*`. | | [`krypteia-memory`](../_gen/memory_overview.md) | `memory/` | **published** | Shared TLSF allocator for bare-metal targets (no-std heap management). Import as `use memory::*`. | | [`krypteia-tessera`](../_gen/tessera_overview.md) | `tessera/` | **v0.2 core (new)** | **Shared hash primitives**: SHA-2, SHA-3 / Keccak, SHAKE / cSHAKE, MGF1, SHA-1, RIPEMD-160, BLAKE2b/2s, BLAKE3, SP 800-185 (KMAC / TupleHash / ParallelHash), HMAC, the KDF family (HKDF, PBKDF2, SP 800-108, scrypt, Argon2) and CRC-16/32 checksums. The single home for every hash — `quantica` and `arcana` build on it. `no_std`, zero deps. Import as `use tessera::*`. | | `krypteia-quantica-ffi` | `quantica_ffi/` | **published** | **C FFI** for the post-quantum side. Builds `libquantica_ffi.{a,so}` and ships a `quantica.h` header. Published from v0.2; the C ABI stays pre-1.0 (may change in a minor bump). | | `krypteia-arcana-ffi` | `arcana_ffi/` | **published** | **C FFI** for the classical side. Builds `libarcana_ffi.{a,so}` and ships an `arcana.h` header. Same staging as the post-quantum FFI. | | `krypteia-tessera-ffi` | `tessera_ffi/` | **published** | **C FFI** for the shared hashes. Builds `libtessera_ffi.{a,so}` and ships a `tessera.h` header. Same staging as the other FFI crates. | | `krypteia-quantica-wasm` | `quantica_wasm/` | **published** | **WebAssembly** bindings for `quantica`. Runs ML-KEM, ML-DSA, SLH-DSA in the browser (90 KB `.wasm`). Built with `wasm-pack`. Published from v0.2; the JS API stays pre-1.0. | | `krypteia-tessera-wasm` | `tessera_wasm/` | **published** | **WebAssembly** bindings for `tessera` (digests, XOFs, HMAC, SP 800-185). No CSPRNG needed. Built with `wasm-pack`. | | `quantica_bench` | `quantica_bench/` | v0.2 preview | Cross-algorithm micro-benchmarks + ctgrind harness for the post-quantum side. Workspace-internal. | | `arcana_bench` | `arcana_bench/` | v0.2 placeholder | Cross-algorithm micro-benchmarks for the classical side — empty skeleton in v0.1, populated in v0.2 mirroring `quantica_bench`. | | `krypteia-arcana-wasm` | `arcana_wasm/` | **published** | **WebAssembly** bindings for `arcana` (RSA, ECDSA, EdDSA, ECDH, AEAD, MAC, DRBG) — the v0.1 skeleton, filled in for v0.2 mirroring `quantica_wasm`. | Each crate has its own README with the per-crate features, examples, test corpora and side-channel notes. The published v0.1 crates carry the long-form chapters; the v0.2-preview / v0.2-placeholder crates carry a short README focused on what they currently do and what they will become. **Published (v0.1):** * **[`quantica/README.md`](../_gen/quantica_overview.md)** — post-quantum: features, Quick Start, typed key wrappers, side-channel countermeasures, ACVP + Wycheproof validation, performance, parameter sets, `no_std` cross-compile. * **[`arcana/README.md`](../_gen/arcana_overview.md)** — classical: the same level of detail for the classical algorithms. * **[`silentops/README.md`](../_gen/silentops_overview.md)** — side-channel toolkit (constant-time primitives, dudect, ctgrind), feature matrix, asm backends per ISA, verification status. * **[`memory/README.md`](../_gen/memory_overview.md)** — TLSF allocator, `os-alloc` / `self-alloc` / `global-alloc` features, bare-metal C usage snippet. **Core crate new in v0.2:** * **[`tessera/README.md`](../_gen/tessera_overview.md)** — shared hash primitives: hashes, XOFs, HMAC, the SP 800-185 keyed constructions, the KDF family (HKDF / PBKDF2 / SP 800-108 / scrypt / Argon2) and CRC-16/32. Traits, Quick Start, side-channel posture (the scrypt / Argon2d cache-timing paths are called out explicitly), and the CAVP / ACVP / RFC test matrix. **Bindings (v0.2 preview, workspace-internal):** * `quantica_ffi/README.md` — C ABI for the post-quantum side. * `arcana_ffi/README.md` — C ABI for the classical side. * `quantica_wasm/README.md` — WebAssembly bindings for the post-quantum side. * `quantica_bench/README.md` — PQC micro-benches + ctgrind harness. **Placeholders (v0.2 deferred):** * `arcana_bench/README.md` — empty skeleton. * `arcana_wasm/README.md` — empty skeleton. ## Project structure ``` krypteia/ Cargo workspace ├── Cargo.toml Workspace manifest + 3 build profiles ├── README.md (this file) ├── CHANGELOG.md Release history (Keep a Changelog 1.1.0 format) ├── CONTRIBUTING.md Contribution policy (AI-assist authorship trailer required) ├── SECURITY.md Maintenance process + vulnerability disclosure policy ├── LICENSE Apache-2.0 ├── NOTICE Third-party attribution notice ├── gendoc.sh Sphinx + cargo-doc documentation builder │ ├── quantica/ Post-quantum crate → quantica/README.md ├── arcana/ Classical crypto crate → arcana/README.md ├── silentops/ CT primitives + dudect + ctgrind → silentops/README.md ├── memory/ Shared TLSF allocator (bare-metal) → memory/README.md ├── tessera/ Shared hash primitives (v0.2) → tessera/README.md ├── quantica_ffi/ C FFI for the post-quantum side (v0.2 preview) ├── arcana_ffi/ C FFI for the classical side (v0.2 preview) ├── tessera_ffi/ C FFI for the shared hashes (v0.2 preview) ├── quantica_wasm/ WebAssembly bindings for quantica (v0.2 preview) ├── tessera_wasm/ WebAssembly bindings for tessera (v0.2 preview) ├── quantica_bench/ PQC micro-benchmarks + ctgrind harness ├── arcana_bench/ Classical micro-benchmarks (v0.2 placeholder) ├── arcana_wasm/ WebAssembly bindings for arcana (v0.2 placeholder) ├── tests-embedded/ Bare-metal qemu-system harness (T3-A) ├── tools/ Helper scripts + vector-runner host generator ├── htmldoc/ Generated HTML documentation (gendoc.sh) │ └── doc/ Workspace-level documentation sources (Sphinx) ├── conf.py Unified Sphinx configuration ├── TOC.md README chapter-list contract (per-crate parity) ├── index_all.rst TOC root for `gendoc.sh all` ├── index_quantica.rst TOC root for `gendoc.sh quantica` ├── index_arcana.rst TOC root for `gendoc.sh arcana` ├── infra/ Workspace-level infra notes (ctgrind, …) └── requirements.txt Sphinx + sphinxcontrib-bibtex + MyST # Per-crate documentation (side-channel analyses, KAT corpora, # research papers, FIPS specs) lives under each crate's own # `doc/` subtree — see `quantica/doc/`, `arcana/doc/`, # `silentops/doc/`. `gendoc.sh` stages them into `doc/_gen/` at # build time. ``` ## Building ```bash # Build all crates (release, sca-protected on by default in quantica) cargo build --release # Run the entire test suite (~4000 vectors + unit tests + doctests) cargo test --release --workspace # Cross-compile quantica for a bare-metal target (no_std + sca-protected) cargo build -p quantica \ --no-default-features \ --features ml-kem,ml-dsa,slh-dsa,sca-protected \ --target thumbv7em-none-eabihf # Build the WebAssembly package for browsers cd quantica_wasm && wasm-pack build --target web --release # Generate the HTML documentation site ./gendoc.sh all # full workspace doc (default) ./gendoc.sh quantica # quantica-only doc (standalone distribution) ./gendoc.sh arcana # arcana-only doc (standalone distribution) ``` Each invocation writes a self-contained, browsable HTML tree under `htmldoc/`, built with Sphinx (RTD theme) and including a copy of the Rust API reference produced by `cargo doc` under `htmldoc/api/`. The latest `main` build is published automatically by the workspace CI (`.github/workflows/doc.yml`) to **[https://krypteia-rs.dev](https://krypteia-rs.dev)**. The crate-level Rust API documentation also auto-builds on [docs.rs](https://docs.rs/) for each crate after a `cargo publish`. For per-crate build / test / feature combinations, see the README inside the relevant crate. ## Cargo profiles Three compilation profiles are declared in the workspace `Cargo.toml`: | Profile | opt-level | CT guarantee | Use case | |---------------------|-------------|---------------------------------------|-----------------------------------| | `release` | `2` | Yes (Rust source-level) | Desktop / server production | | `release-embedded` | `z` + abort | Yes (asm CT backends) | Embedded, minimum size | | `release-bench` | `3` | **No** (LLVM may break CT patterns) | Benchmarks only | > **Warning**: `opt-level=3` can defeat constant-time guarantees: LLVM may convert > bitwise mask patterns into conditional memory accesses. Always use > `opt-level=2` or lower for security-critical builds, or rely on the > assembly CT backends from `silentops` (`asm-aarch64`, `asm-thumbv7`, > `asm-thumbv6m`, `asm-riscv32`) which bypass the compiler entirely. ## Test coverage and references The per-crate vector breakdown (NIST ACVP, Wycheproof, KAT, CAVP, custom-negative) and the per-crate primary-source bibliography (FIPS / RFC / IACR ePrint / TCHES) live in each crate's own `Test validation` and `References` chapters. Start here: * **[`quantica/README.md#test-validation`](../_gen/quantica_overview.md#test-validation)** and **`#references`** — ACVP + Wycheproof + custom-negative vectors for ML-KEM / ML-DSA / SLH-DSA, plus the FIPS 203/204/205 + dudect + masking-paper citation set. * **[`arcana/README.md#test-validation`](../_gen/arcana_overview.md#test-validation)** and **`#references`** — CAVP + Wycheproof + custom vectors for the classical primitives, plus the RFC + NIST SP + Minerva / LadderLeak citation set. The shared workspace-level dependencies (Apache-2.0 licence, the SCA verification toolchain under [`silentops`](../_gen/silentops_overview.md), the side-channel methodology reference Reparaz–Balasch–Verbauwhede 2017 *"dude, is my code constant time?"*) are documented in the respective crate READMEs. ## Contributing and security Two workspace-level governance documents apply to every crate. Each link below resolves to a readable rendered version: the HTML page bundled in the GitHub Pages doc pack (regenerated by `gendoc.sh` on every push to `main`) when read inside the doc pack, or the source markdown rendered by GitHub when read on the repository view. * **[CONTRIBUTING](../_gen/contributing.md)** — contribution policy. Open a PR against `main`; AI-assisted commits must carry a `Co-Authored-By:` trailer that names the model **and** the context-window variant (e.g. `Claude Opus 4.7 (1M context) `). The git history is the audit trail of which tool produced which line — a generic `Claude` / `Claude Code` trailer erases that and is not acceptable. Full details (commit message style, branch policy, hooks) are in the document. * **[SECURITY](../_gen/security.md)** — security maintenance process and **vulnerability disclosure policy**. Private reports go to `cedric.mesnil@pm.me`; the default coordinated-disclosure embargo is 90 calendar days. The document also describes the three pillars of the maintenance process (veille / doc / code), the tier-based hardening plan structure, and the per-crate threat-model contract. Read it before reporting an issue, opening a PR that touches a CT path, or proposing a new countermeasure. ## License Apache-2.0 — see LICENSE and NOTICE.