From 045370c46a36665feb7ee0d478f3b37aa3d9aceb Mon Sep 17 00:00:00 2001 From: JohnE Date: Tue, 3 Mar 2026 09:43:39 -0800 Subject: [PATCH] MOD: docs updated --- README.rst | 105 +++++++- docs/ccc_fplugin_architecture_design.rst | 298 +++++++++++++++++++++++ docs/readme_flutter_ffi.md | 91 +++++++ 3 files changed, 481 insertions(+), 13 deletions(-) create mode 100644 docs/ccc_fplugin_architecture_design.rst create mode 100644 docs/readme_flutter_ffi.md diff --git a/README.rst b/README.rst index 05b78ba..5217556 100644 --- a/README.rst +++ b/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) + diff --git a/docs/ccc_fplugin_architecture_design.rst b/docs/ccc_fplugin_architecture_design.rst new file mode 100644 index 0000000..c6ab0fd --- /dev/null +++ b/docs/ccc_fplugin_architecture_design.rst @@ -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 cccInit()`` +* ``Future> listProviders()`` +* ``Future encryptAead(...)`` +* ``Future decryptAead(...)`` +* ``Future deriveKey(...)`` +* ``Future hash(...)`` +* ``Future 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) + +---- + diff --git a/docs/readme_flutter_ffi.md b/docs/readme_flutter_ffi.md new file mode 100644 index 0000000..d077796 --- /dev/null +++ b/docs/readme_flutter_ffi.md @@ -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.