358 lines
6.8 KiB
ReStructuredText
358 lines
6.8 KiB
ReStructuredText
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.
|
||
|