CCC Rust — Cryptographic Provider Core ======================================= :Repository: ``ccc_rust`` :Milestone: 1 (Foundation Layer) :Status: Implementation-Ready :Language: Rust (stable toolchain) :Primary Provider (Phase 4): wolfSSL v5.7.2-stable Overview -------- ``ccc_rust`` is the **provider-agnostic cryptographic core** of the CCC architecture. It delivers hardware-grade cryptography through a clean, trait-driven design that supports multiple backend providers. This repository contains **no Flutter, no Dart, and no bridge code**. It is a pure Rust workspace that can be consumed by: * Flutter (via FFI bridge — Milestone 2) * CLI tools * Backend services * Test harnesses * Other FFI hosts (Python, Swift, etc.) All cryptographic primitives execute here. ---- Purpose ------- The goals of ``ccc_rust`` are: * Provide a unified trait-based crypto abstraction * Support pluggable providers (wolfSSL first, others later) * Expose runtime capability reporting * Enforce zeroization of sensitive material * Validate correctness via conformance test vectors * Remain independent of UI or platform frameworks This repository is the cryptographic trust root of the CCC system. ---- Guiding Principles ------------------ 1. **Provider-Agnostic Architecture** - All cryptography is defined by traits. - Providers implement traits. - No provider-specific logic leaks into higher layers. 2. **Runtime Capability Discovery** - Algorithms report availability at runtime. - No compile-time assumptions of support. - Missing algorithms fail gracefully. 3. **Strict Layer Isolation** - No Flutter, Dart, or FFI bridge code. - No platform plugin scaffolding. - This crate must build standalone. 4. **1-to-1 Algorithm ID Mapping** - Enum discriminants match ``cipher_constants.dart`` exactly. - No translation tables required downstream. 5. **Zeroization by Default** - Private keys and derived secrets use ``zeroize``. - Sensitive buffers are wiped on drop. 6. **Conformance Before Capability** - An algorithm is considered available only if: - The probe succeeds - Test vectors pass - No silent partial implementations. 7. **Reproducible Builds** - wolfSSL is vendored as a pinned submodule. - Stable Rust toolchain is pinned. - No floating dependency branches. 8. **Security > Convenience** - Explicit errors over silent fallback. - No insecure defaults. - No optional weakening of primitives. ---- Workspace Layout ---------------- :: ccc_rust/ ├── Cargo.toml ├── rust-toolchain.toml ├── .cargo/ │ └── config.toml ├── vendors/ │ └── wolfssl/ (git submodule, pinned) ├── crates/ │ ├── ccc-crypto-core/ │ └── ccc-crypto-wolfssl/ └── tests/ └── conformance/ Crate Responsibilities ~~~~~~~~~~~~~~~~~~~~~~ ccc-crypto-core ^^^^^^^^^^^^^^^ Defines: * Algorithm enums (AEAD, KDF, MAC, Hash, KEM) * Provider traits * Capability structures * Provider registry * Error types * Shared data structures This crate contains **no algorithm implementations**. ccc-crypto-wolfssl ^^^^^^^^^^^^^^^^^^ Implements: * ``CryptoProvider`` trait * wolfSSL-backed AEAD, KDF, MAC, Hash, and KEM * Startup capability probe * Benchmark harness * Self-test integration wolfSSL is compiled via ``cmake`` + ``bindgen`` in ``build.rs``. tests/conformance ^^^^^^^^^^^^^^^^^ Executable test harness validating: * NIST vectors * RFC vectors * DH test vectors * Hash reference outputs All vectors must pass before tagging a release. ---- Supported Algorithms (Phase 4) ------------------------------ AEAD ~~~~ * AES-256-GCM * ChaCha20-Poly1305 * XChaCha20-Poly1305 KDF ~~~ * HKDF-SHA256 * HKDF-SHA384 * HKDF-SHA512 * Argon2id * BLAKE2b-KDF MAC ~~~ * HMAC-SHA256 * HMAC-SHA512 * BLAKE2b-MAC Hash ~~~~ * SHA-256 * SHA-384 * SHA-512 * SHA3-256 * SHA3-512 * BLAKE2b-512 KEM ~~~ * X25519 * X448 Planned (Phase 5): * ML-KEM-768 * ML-KEM-1024 * Classic McEliece ---- Core Traits ----------- The central abstraction: .. code-block:: rust pub trait CryptoProvider: AeadProvider + KdfProvider + MacProvider + HashProvider + Send + Sync { fn provider_name(&self) -> &'static str; fn capabilities(&self) -> ProviderCapabilities; fn self_test(&self) -> SelfTestReport; fn benchmark(&self) -> BenchmarkReport; } Providers are registered in: .. code-block:: rust ProviderRegistry: OnceLock>>> ---- Capability Model ---------------- Each algorithm reports: * ``available: bool`` * ``deterministic_io: bool`` * ``efficiency_score: u8`` * ``reliability_score: u8`` Availability is determined via live probe calls — not compile flags. Benchmark scores are normalized (0–100) based on throughput testing. Self-test reliability is derived from vector validation. ---- Build Instructions ------------------ Standard build: .. code-block:: bash cargo build --workspace Run tests: .. code-block:: bash cargo test --workspace Run conformance suite: .. code-block:: bash cargo run -p ccc-conformance-tests Cross-compile: .. code-block:: bash cargo build --target aarch64-apple-ios cargo build --target aarch64-linux-android Security audit: .. code-block:: bash cargo audit ---- Milestone 1 Release Gate ------------------------ Before tagging ``v0.1.0``: * All unit tests pass * Conformance suite prints ``ALL VECTORS PASSED`` * iOS + Android targets compile * No Flutter or Dart dependencies * No CVEs in dependency tree Only after this gate is passed does Milestone 2 begin. ---- How to Add a New Provider ------------------------- 1. Create a new crate under ``crates/``. 2. Implement all provider traits. 3. Implement capability probing. 4. Implement self-test integration. 5. Implement benchmark(). 6. Register provider in registry. 7. Add vector validation to conformance suite. No changes to existing providers are required. ---- Security Model -------------- * All private keys use ``Zeroizing>``. * No key material is logged. * No debug-only crypto paths. * Capability probing prevents accidental exposure of unsupported algorithms. * No implicit algorithm fallback. This repository contains the cryptographic enforcement layer. Higher layers orchestrate — this layer executes. ---- Non-Goals --------- * No Flutter bindings * No Dart APIs * No UI code * No business logic * No message formatting logic * No network code Those belong to higher milestones. ---- Future Providers (Planned) -------------------------- * libsodium * OpenSSL * BoringSSL * RustCrypto (pure Rust) * liboqs (post-quantum) * Botan * mbedTLS * Nettle The trait system allows incremental addition without breaking consumers.