MOD: docs included
This commit is contained in:
JohnE
parent
7407a92e69
commit
aa61de33a2
|
|
@ -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
|
||||
================== =====================================================
|
||||
|
|
@ -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<Mutex<HashMap<&'static str, Box<dyn CryptoProvider>>>>
|
||||
|
||||
----
|
||||
|
||||
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<Vec<u8>>``.
|
||||
* 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.
|
||||
|
||||
Loading…
Reference in New Issue