========================================
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
================== =====================================================
919d4bcc95