j3g
/
lum_ccc_rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

MOD: docs included

This commit is contained in:
JohnE 2026-03-03 09:59:50 -08:00
parent 7407a92e69
commit aa61de33a2
2 changed files with 474 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
README.rst Normal file
View File

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

357
README_all.rst Normal file
View File

@ -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.