MOD: docs updated
This commit is contained in:
JohnE
parent
46478434a4
commit
045370c46a
105
README.rst
105
README.rst
|
|
@ -4,10 +4,30 @@ 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.
|
||||
|
||||
This document describes the architecture for the **CCC Rust Crypto Provider**,
|
||||
the first of three milestones in delivering hardware-grade cryptography to the
|
||||
LetUsMsg application.
|
||||
|
||||
=================================== ========================== ===========================
|
||||
Repository What ships Depends on
|
||||
|
|
@ -19,16 +39,75 @@ Repository What ships Depends on
|
|||
|
||||
|
||||
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.
|
||||
|
||||
1. Every provider reports its own capabilities at runtime — no compile-time
|
||||
hard-coding of ``available: true/false``.
|
||||
2. Algorithm IDs in Rust map 1-to-1 to the integer constants in
|
||||
``cipher_constants.dart`` — zero Dart changes needed when wiring up.
|
||||
3. Key material is zeroed on drop (``zeroize`` crate) everywhere.
|
||||
4. A conformance test suite validates NIST/RFC vectors for every algorithm
|
||||
before any provider is marked ``available``.
|
||||
5. The library has no runtime dependency on Flutter; it is consumable by any
|
||||
FFI host (Flutter plugin, Python tests, CLI tools).
|
||||
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)
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,298 @@
|
|||
CCC Dart Plugin — Architecture & Integration Guide
|
||||
====================================================
|
||||
|
||||
:Status: Milestone 2 (Planned)
|
||||
:Depends on: ``ccc_rust`` ≥ v0.1.0
|
||||
:Target: Flutter (iOS, Android, macOS)
|
||||
:Bridge: ``flutter_rust_bridge`` v2
|
||||
|
||||
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 (Milestone 1)
|
||||
* The LetUsMsg application (Milestone 3)
|
||||
|
||||
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``.
|
||||
|
||||
----
|
||||
|
||||
Architecture Positioning
|
||||
-------------------------
|
||||
|
||||
============= =================================== ===========================
|
||||
Layer Repository Responsibility
|
||||
============= =================================== ===========================
|
||||
Milestone 1 ``ccc_rust`` Pure Rust crypto providers
|
||||
Milestone 2 ``ccc_dart_plugin`` Flutter bridge + Dart API
|
||||
Milestone 3 ``letusmsg`` App integration
|
||||
============= =================================== ===========================
|
||||
|
||||
Hard Boundary Rules
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* This repo **must not modify crypto logic** from ``ccc_rust``.
|
||||
* This repo **must not fork or duplicate algorithm definitions**.
|
||||
* All algorithm enums and discriminants originate in ``ccc_rust``.
|
||||
* All provider capability logic remains in Rust.
|
||||
* The app must depend only on the published Dart package — not directly on Rust.
|
||||
|
||||
----
|
||||
|
||||
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.
|
||||
|
||||
----
|
||||
|
||||
Repository Structure
|
||||
--------------------
|
||||
|
||||
::
|
||||
|
||||
ccc_dart_plugin/
|
||||
├── pubspec.yaml
|
||||
├── lib/
|
||||
│ ├── ccc_crypto.dart
|
||||
│ ├── ccc_provider_catalog.dart
|
||||
│ ├── ccc_self_test.dart
|
||||
│ └── src/
|
||||
│ └── frb_generated.dart
|
||||
├── rust/
|
||||
│ ├── Cargo.toml
|
||||
│ └── src/
|
||||
│ ├── lib.rs
|
||||
│ └── api.rs
|
||||
├── flutter_rust_bridge.yaml
|
||||
├── ios/
|
||||
├── android/
|
||||
├── macos/
|
||||
└── test/
|
||||
└── roundtrip_test.dart
|
||||
|
||||
----
|
||||
|
||||
Rust Bridge Crate
|
||||
------------------
|
||||
|
||||
``rust/Cargo.toml``:
|
||||
|
||||
.. code-block:: toml
|
||||
|
||||
[package]
|
||||
name = "ccc_dart_bridge"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
ccc-crypto-core = { git = "https://github.com/letusmsg/ccc_rust", tag = "v0.1.0" }
|
||||
ccc-crypto-wolfssl = { git = "https://github.com/letusmsg/ccc_rust", tag = "v0.1.0" }
|
||||
flutter_rust_bridge = "2"
|
||||
|
||||
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.
|
||||
|
||||
----
|
||||
|
||||
Dart API Surface
|
||||
----------------
|
||||
|
||||
CccCrypto
|
||||
~~~~~~~~~
|
||||
|
||||
Primary entry point.
|
||||
|
||||
Methods:
|
||||
|
||||
* ``Future<void> cccInit()``
|
||||
* ``Future<List<String>> listProviders()``
|
||||
* ``Future<Uint8List> encryptAead(...)``
|
||||
* ``Future<Uint8List> decryptAead(...)``
|
||||
* ``Future<Uint8List> deriveKey(...)``
|
||||
* ``Future<Uint8List> hash(...)``
|
||||
* ``Future<CccSelfTestResult> runSelfTest()``
|
||||
|
||||
CccProviderCatalog
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Represents runtime provider capabilities:
|
||||
|
||||
* Provider name
|
||||
* Available algorithms
|
||||
* Efficiency score
|
||||
* Reliability score
|
||||
|
||||
CccSelfTest
|
||||
~~~~~~~~~~~
|
||||
|
||||
Wraps ``SelfTestReport`` from Rust and exposes:
|
||||
|
||||
* Pass/fail per algorithm
|
||||
* Overall status
|
||||
* Diagnostic messages
|
||||
|
||||
----
|
||||
|
||||
Initialization Flow
|
||||
-------------------
|
||||
|
||||
1. Flutter app starts.
|
||||
2. ``CccCrypto.cccInit()`` is called.
|
||||
3. Rust bridge:
|
||||
- Registers WolfSslProvider
|
||||
- Runs capability probe
|
||||
- Runs self-test (optional at startup)
|
||||
4. Provider catalog is cached.
|
||||
5. App queries provider capabilities.
|
||||
|
||||
----
|
||||
|
||||
Error Handling Strategy
|
||||
-----------------------
|
||||
|
||||
Rust ``CryptoError`` is mapped to structured Dart exceptions:
|
||||
|
||||
====================== ============================
|
||||
Rust Error Dart Exception
|
||||
====================== ============================
|
||||
UnsupportedAlgorithm CccUnsupportedAlgorithm
|
||||
InvalidKey CccInvalidKey
|
||||
InvalidNonce CccInvalidNonce
|
||||
AuthenticationFailed CccAuthenticationFailed
|
||||
InternalError CccInternalError
|
||||
====================== ============================
|
||||
|
||||
Errors never cross the bridge as raw strings alone.
|
||||
|
||||
----
|
||||
|
||||
Testing Requirements
|
||||
--------------------
|
||||
|
||||
Before tagging ``v0.1.0`` of this plugin:
|
||||
|
||||
* Rust bridge builds for:
|
||||
- iOS (aarch64-apple-ios)
|
||||
- Android (arm64 + x86_64)
|
||||
- macOS (aarch64)
|
||||
* Flutter integration tests:
|
||||
- AEAD roundtrip encrypt/decrypt
|
||||
- HKDF known-vector test
|
||||
- X25519 key agreement test
|
||||
* ``CccSelfTest.runAll()`` returns success
|
||||
* No Dart-side crypto logic present
|
||||
* No modification of ``ccc_rust`` source
|
||||
|
||||
----
|
||||
|
||||
Milestone 3 Handoff Contract
|
||||
-----------------------------
|
||||
|
||||
The LetUsMsg app will:
|
||||
|
||||
* Add this plugin via ``pubspec.yaml``
|
||||
* Call ``CccCrypto.cccInit()`` at startup
|
||||
* Replace existing crypto stubs with plugin calls
|
||||
* Surface provider catalog in debug UI
|
||||
|
||||
No Rust changes are permitted during Milestone 3.
|
||||
|
||||
----
|
||||
|
||||
Versioning Strategy
|
||||
-------------------
|
||||
|
||||
* ``ccc_rust`` tagged independently (e.g., ``v0.1.0``).
|
||||
* ``ccc_dart_plugin`` references exact git tag.
|
||||
* Breaking Rust API changes require:
|
||||
- New Rust tag
|
||||
- Plugin update
|
||||
- New plugin version
|
||||
|
||||
Semantic versioning applies independently to both repositories.
|
||||
|
||||
----
|
||||
|
||||
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
|
||||
-----------------
|
||||
|
||||
Planned enhancements after Milestone 2:
|
||||
|
||||
* Multi-provider selection logic
|
||||
* Dynamic provider priority scoring
|
||||
* Optional secure enclave integration
|
||||
* Streaming AEAD APIs
|
||||
* PQ KEM exposure (ML-KEM, Classic McEliece Phase 5)
|
||||
|
||||
----
|
||||
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
# ccc_cryptography
|
||||
|
||||
A new Flutter FFI plugin project.
|
||||
|
||||
## Getting Started
|
||||
|
||||
This project is a starting point for a Flutter
|
||||
[FFI plugin](https://flutter.dev/to/ffi-package),
|
||||
a specialized package that includes native code directly invoked with Dart FFI.
|
||||
|
||||
## Project structure
|
||||
|
||||
This template uses the following structure:
|
||||
|
||||
* `src`: Contains the native source code, and a CmakeFile.txt file for building
|
||||
that source code into a dynamic library.
|
||||
|
||||
* `lib`: Contains the Dart code that defines the API of the plugin, and which
|
||||
calls into the native code using `dart:ffi`.
|
||||
|
||||
* platform folders (`android`, `ios`, `windows`, etc.): Contains the build files
|
||||
for building and bundling the native code library with the platform application.
|
||||
|
||||
## Building and bundling native code
|
||||
|
||||
The `pubspec.yaml` specifies FFI plugins as follows:
|
||||
|
||||
```yaml
|
||||
plugin:
|
||||
platforms:
|
||||
some_platform:
|
||||
ffiPlugin: true
|
||||
```
|
||||
|
||||
This configuration invokes the native build for the various target platforms
|
||||
and bundles the binaries in Flutter applications using these FFI plugins.
|
||||
|
||||
This can be combined with dartPluginClass, such as when FFI is used for the
|
||||
implementation of one platform in a federated plugin:
|
||||
|
||||
```yaml
|
||||
plugin:
|
||||
implements: some_other_plugin
|
||||
platforms:
|
||||
some_platform:
|
||||
dartPluginClass: SomeClass
|
||||
ffiPlugin: true
|
||||
```
|
||||
|
||||
A plugin can have both FFI and method channels:
|
||||
|
||||
```yaml
|
||||
plugin:
|
||||
platforms:
|
||||
some_platform:
|
||||
pluginClass: SomeName
|
||||
ffiPlugin: true
|
||||
```
|
||||
|
||||
The native build systems that are invoked by FFI (and method channel) plugins are:
|
||||
|
||||
* For Android: Gradle, which invokes the Android NDK for native builds.
|
||||
* See the documentation in android/build.gradle.
|
||||
* For iOS and MacOS: Xcode, via CocoaPods.
|
||||
* See the documentation in ios/ccc_cryptography.podspec.
|
||||
* See the documentation in macos/ccc_cryptography.podspec.
|
||||
* For Linux and Windows: CMake.
|
||||
* See the documentation in linux/CMakeLists.txt.
|
||||
* See the documentation in windows/CMakeLists.txt.
|
||||
|
||||
## Binding to native code
|
||||
|
||||
To use the native code, bindings in Dart are needed.
|
||||
To avoid writing these by hand, they are generated from the header file
|
||||
(`src/ccc_cryptography.h`) by `package:ffigen`.
|
||||
Regenerate the bindings by running `dart run ffigen --config ffigen.yaml`.
|
||||
|
||||
## Invoking native code
|
||||
|
||||
Very short-running native functions can be directly invoked from any isolate.
|
||||
For example, see `sum` in `lib/ccc_cryptography.dart`.
|
||||
|
||||
Longer-running functions should be invoked on a helper isolate to avoid
|
||||
dropping frames in Flutter applications.
|
||||
For example, see `sumAsync` in `lib/ccc_cryptography.dart`.
|
||||
|
||||
## Flutter help
|
||||
|
||||
For help getting started with Flutter, view our
|
||||
[online documentation](https://docs.flutter.dev), which offers tutorials,
|
||||
samples, guidance on mobile development, and a full API reference.
|
||||
Loading…
Reference in New Issue