118 lines
4.2 KiB
ReStructuredText
118 lines
4.2 KiB
ReStructuredText
========================================
|
|
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
|
|
================== =====================================================
|