114 lines
3.8 KiB
ReStructuredText
114 lines
3.8 KiB
ReStructuredText
========================================
|
||
Copius Cipher Chain Cryptography Library
|
||
========================================
|
||
|
||
Overview
|
||
========
|
||
``ccc_dart_plugin`` is the **Flutter/Dart bridge layer** for the CCC
|
||
cryptographic system.
|
||
|
||
It exposes the Rust-based ``ccc_rust`` crypto providers to Flutter
|
||
applications via ``flutter_rust_bridge`` while maintaining strict
|
||
architectural separation from both:
|
||
|
||
* The Rust crypto implementation
|
||
* The LetUsMsg application
|
||
|
||
This repository contains:
|
||
|
||
* A small Rust bridge crate referencing ``ccc_rust`` via a git tag
|
||
* Generated ``flutter_rust_bridge`` bindings
|
||
* A Flutter plugin scaffold (iOS / Android / macOS)
|
||
* A clean Dart API surface for applications
|
||
|
||
This plugin does **not** implement cryptography itself.
|
||
All cryptographic logic remains in ``ccc_rust``.
|
||
|
||
Using FFI instead of platform channels allows Flutter to call hardware‑grade,
|
||
memory‑safe Rust cryptography directly, delivering native performance,
|
||
lower overhead, and stronger security isolation without reimplementing crypto in Dart.
|
||
|
||
|
||
=================================== ========================== ===========================
|
||
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. **Strict Layer Isolation**
|
||
- Rust crypto code lives only in ``ccc_rust``.
|
||
- Flutter-specific code lives only here.
|
||
- The app layer never calls Rust directly.
|
||
|
||
2. **Zero Crypto Logic in Dart**
|
||
- No encryption, hashing, KDF, MAC, or KEM logic in Dart.
|
||
- Dart is orchestration only.
|
||
|
||
3. **1-to-1 Algorithm Mapping**
|
||
- Rust enum discriminants match the integer constants in
|
||
``cipher_constants.dart`` exactly.
|
||
- No translation layer or remapping table in Dart.
|
||
|
||
4. **Provider-Agnostic by Design**
|
||
- The Dart API does not hard-code wolfSSL.
|
||
- Providers are discovered at runtime via ``CccProviderCatalog``.
|
||
|
||
5. **Deterministic FFI Contracts**
|
||
- All bridge-exposed types are explicit and versioned.
|
||
- No implicit conversions or dynamic typing across FFI.
|
||
|
||
6. **Security First**
|
||
- All key material originates and remains in Rust memory.
|
||
- Dart never stores raw private keys.
|
||
- Sensitive buffers are zeroized in Rust.
|
||
|
||
7. **Reproducible Builds**
|
||
- ``ccc_rust`` is referenced by git tag (e.g., ``v0.1.0``).
|
||
- No floating branch dependencies.
|
||
|
||
8. **Test Before Integration**
|
||
- Bridge-level roundtrip tests must pass before app integration.
|
||
- Self-test and conformance results are exposed to Flutter.
|
||
|
||
|
||
|
||
Main
|
||
====
|
||
|
||
Responsibilities
|
||
----------------
|
||
* Register providers (e.g., WolfSslProvider)
|
||
* Expose thin wrappers over trait methods
|
||
* Convert Rust errors → structured Dart exceptions
|
||
* Expose capability catalog
|
||
* Expose self-test and benchmark results
|
||
|
||
No crypto algorithms are implemented here.
|
||
|
||
|
||
Security Model
|
||
--------------
|
||
* All cryptographic primitives execute in Rust.
|
||
* Private keys never leave Rust memory unencrypted.
|
||
* Dart receives only opaque byte arrays.
|
||
* All sensitive buffers are zeroized in Rust.
|
||
* Capability reporting is runtime-probed, not compile-time assumed.
|
||
|
||
The plugin layer introduces **no new cryptographic primitives** and
|
||
no security policy decisions.
|
||
|
||
|
||
Future Extensions
|
||
-----------------
|
||
* Multi-provider selection logic
|
||
* Dynamic provider priority scoring
|
||
* Optional secure enclave integration
|
||
* Streaming AEAD APIs
|
||
* PQ KEM exposure (ML-KEM, Classic McEliece Phase 5)
|
||
|