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