From aa61de33a260724c83c818ae5d4efc7aaf6ce884 Mon Sep 17 00:00:00 2001 From: JohnE Date: Tue, 3 Mar 2026 09:59:50 -0800 Subject: [PATCH] MOD: docs included --- README.rst | 117 ++++++++++++++++ README_all.rst | 357 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 474 insertions(+) create mode 100644 README.rst create mode 100644 README_all.rst diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..fc1face --- /dev/null +++ b/README.rst @@ -0,0 +1,117 @@ +======================================== +Copius Cipher Chain Cryptography Library +======================================== + +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. + + +=================================== ========================== =========================== +Repository What ships Depends on +=================================== ========================== =========================== +``ccc_rust`` Pure Rust crypto library wolfSSL (vendored) +``ccc_dart_plugin`` Flutter plugin + Dart API ``ccc_rust`` (git/semver) +``letusmsg`` (existing app) App integration ``ccc_dart_plugin`` package +=================================== ========================== =========================== + + +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. **Reproducible Builds** + - wolfSSL is vendored as a pinned submodule. + - Stable Rust toolchain is pinned. + - No floating dependency branches. + +7. **Security > Convenience** + - Explicit errors over silent fallback. + - No insecure defaults. + - No optional weakening of primitives. + +8. **FFI host compatible** + - Consumable by any FFI host (Flutter plugin, Python tests, CLI tools). + - The library has no runtime dependency on Flutter. + + + +Implementation Summary (Milestone 1) +==================================== + +Core crate (``ccc-crypto-core``) +-------------------------------- +* Algorithm enums with fixed ``u32`` discriminants for cross-layer compatibility. +* Provider trait surfaces: + * ``AeadProvider`` + * ``KdfProvider`` + * ``MacProvider`` + * ``HashProvider`` + * ``KemProvider`` + * ``CryptoProvider`` +* ``ProviderRegistry`` (global, lazy-initialized registry model). +* Core result/error and crypto data types, including zeroized key material handling. + + +wolfSSL provider crate (``ccc-crypto-wolfssl``) +------------------------------------------------ +* AEAD: AES-256-GCM, ChaCha20-Poly1305, XChaCha20-Poly1305. +* KDF: HKDF-SHA256/384/512, Argon2id, BLAKE2b-based KDF path. +* MAC: HMAC-SHA256/384/512, BLAKE2b-MAC, constant-time verification. +* Hash: SHA-256/384/512, SHA3-256/512, BLAKE2b-512. +* KEM: X25519 and X448 keygen/encap/decap. +* Startup capability probing and benchmark hooks. + + +Conformance test suite +---------------------- +* NIST SP 800-38D AES-GCM vectors. +* RFC 8439 ChaCha20-Poly1305 vectors. +* RFC 5869 HKDF vectors. +* RFC 4231 HMAC vectors. +* FIPS/reference hash vectors. +* RFC 7748 X25519/X448 DH vectors. +* XChaCha20-Poly1305 extended-nonce roundtrip + auth-failure checks. + + + +Future Providers +================ + +================== ===================================================== +Library Rust crate / approach +================== ===================================================== +libsodium ``sodiumoxide`` or ``safe_libsodium`` +OpenSSL ``openssl`` crate +BoringSSL ``boring`` crate +RustCrypto Pure-Rust trait impls; no native dep +liboqs Open Quantum Safe — ML-KEM, BIKE, HQC, Falcon, Dilithium, SPHINCS+ +Signal libsignal ``libsignal`` (Apache-2 subset) +Botan ``botan`` crate +mbedTLS ``mbedtls`` crate +Nettle ``nettle-sys`` crate +================== ===================================================== diff --git a/README_all.rst b/README_all.rst new file mode 100644 index 0000000..76e250d --- /dev/null +++ b/README_all.rst @@ -0,0 +1,357 @@ +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. +