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

MOD: docs updated

This commit is contained in:
JohnE 2026-03-03 09:43:39 -08:00
parent 46478434a4
commit 045370c46a
3 changed files with 481 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
README.rst
View File

@ -4,10 +4,30 @@ Copius Cipher Chain Cryptography Library
Overview 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 Repository What ships Depends on
@ -19,16 +39,75 @@ Repository What ships Depends on
Guiding Principles 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 2. **Zero Crypto Logic in Dart**
hard-coding of ``available: true/false``. - No encryption, hashing, KDF, MAC, or KEM logic in Dart.
2. Algorithm IDs in Rust map 1-to-1 to the integer constants in - Dart is orchestration only.
``cipher_constants.dart`` — zero Dart changes needed when wiring up.
3. Key material is zeroed on drop (``zeroize`` crate) everywhere. 3. **1-to-1 Algorithm Mapping**
4. A conformance test suite validates NIST/RFC vectors for every algorithm - Rust enum discriminants match the integer constants in
before any provider is marked ``available``. ``cipher_constants.dart`` exactly.
5. The library has no runtime dependency on Flutter; it is consumable by any - No translation layer or remapping table in Dart.
FFI host (Flutter plugin, Python tests, CLI tools).
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)

298
docs/ccc_fplugin_architecture_design.rst Normal file
View File

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

91
docs/readme_flutter_ffi.md Normal file
View File

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