# krypteia — Post-Quantum and Classical Cryptography in Rust 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. ## 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 `v0.1` is a deliberate first cut: the four published crates (`krypteia-silentops`, `krypteia-memory`, `krypteia-quantica`, `krypteia-arcana` on crates.io — imported in code as the bare `silentops` / `memory` / `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 | 361 library unit tests pass across the 4 published 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 | Codeberg: [codeberg.org/cslashm/krypteia](https://codeberg.org/cslashm/krypteia). crates.io: `krypteia-silentops`, `krypteia-memory`, `krypteia-quantica`, `krypteia-arcana`. docs.rs auto-built per crate; long-form pack at [cslashm.codeberg.page/krypteia](https://cslashm.codeberg.page/krypteia). | | 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::*`. | | `quantica_ffi` | `quantica_ffi/` | v0.2 preview | **C FFI** for the post-quantum side. Builds `libquantica_ffi.{a,so}` and ships a `quantica.h` header. Workspace-internal in v0.1 (`publish = false`); C ABI stabilises in v0.2. | | `arcana_ffi` | `arcana_ffi/` | v0.2 preview | **C FFI** for the classical side. Builds `libarcana_ffi.{a,so}` and ships an `arcana.h` header. Same v0.1/v0.2 staging as `quantica_ffi`. | | `quantica_wasm` | `quantica_wasm/` | v0.2 preview | **WebAssembly** bindings for `quantica`. Runs ML-KEM, ML-DSA, SLH-DSA in the browser (90 KB `.wasm`). Built with `wasm-pack`. Workspace-internal in v0.1, JS API stabilises in v0.2. | | `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`. | | `arcana_wasm` | `arcana_wasm/` | v0.2 placeholder | WebAssembly bindings for `arcana` — empty skeleton in v0.1, populated in 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. **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 ├── quantica_ffi/ C FFI for the post-quantum side (v0.2 preview) ├── arcana_ffi/ C FFI for the classical side (v0.2 preview) ├── quantica_wasm/ WebAssembly bindings for quantica (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 (`.forgejo/workflows/doc.yml`) to **[https://cslashm.codeberg.page/krypteia](https://cslashm.codeberg.page/krypteia)**. 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 Codeberg Pages doc pack (regenerated by `gendoc.sh` on every push to `main`) when read inside the doc pack, or the source markdown rendered by Codeberg / 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.