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

Compare commits

base: j3g:ddf8c99af20e6ed821616e6975eefb8d67e98130
Branches Tags
j3g:trunk
..
compare: j3g:9f94c6da97eea267b545617130c421ce57bbf3ae
Branches Tags
j3g:trunk

No commits in common. "ddf8c99af20e6ed821616e6975eefb8d67e98130" and "9f94c6da97eea267b545617130c421ce57bbf3ae" have entirely different histories.
ddf8c99af2 ... 9f94c6da97

13 changed files with 153 additions and 2682 deletions
Show Stats Expand all files Collapse all files

3
.vscode/settings.json vendored
View File

@ -3,6 +3,5 @@
"cargo check": true,
"flutter_rust_bridge_codegen": true,
"rustup": true
},
"java.configuration.updateBuildConfiguration": "interactive"
}
}

39
android/build.gradle.bak → android/build.gradle
View File

@ -29,45 +29,24 @@ android {
namespace 'com.flutter_rust_bridge.ccc_cryptography'
}
compileSdk = flutter.compileSdkVersion // 36
ndkVersion = flutter.ndkVersion // 28.2.13676358
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
isCoreLibraryDesugaringEnabled = true
}
kotlinOptions {
jvmTarget = JavaVersion.VERSION_17.toString()
}
defaultConfig {
applicationId = "com.letusmsg.app.ccc_cryptography"
targetSdk = flutter.targetSdkVersion // 36
versionCode = flutter.versionCode // from pubspec.yaml, 2025.8.19+2 == 2
versionName = flutter.versionName // from pubspec.yaml, 2025.8.19+2 == 2025.8.19
minSdk = flutter.minSdkVersion // 24
}
// Bumping the plugin compileSdkVersion requires all clients of this plugin
// to bump the version in their app.
// compileSdkVersion 33
compileSdkVersion 33
// Use the NDK version
// declared in /android/app/build.gradle file of the Flutter project.
// Replace it with a version number if this plugin requires a specfic NDK version.
// (e.g. ndkVersion "23.1.7779620")
// ndkVersion android.ndkVersion
ndkVersion android.ndkVersion
// compileOptions {
// sourceCompatibility JavaVersion.VERSION_1_8
// targetCompatibility JavaVersion.VERSION_1_8
// }
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
// defaultConfig {
// minSdkVersion 19
// }
defaultConfig {
minSdkVersion 19
}
}
apply from: "../cargokit/gradle/plugin.gradle"

53
android/build.gradle.kts
View File

@ -1,53 +0,0 @@
import com.android.build.gradle.LibraryExtension
import org.gradle.kotlin.dsl.configure
import org.gradle.kotlin.dsl.withGroovyBuilder
group = "com.flutter_rust_bridge.ccc_cryptography"
version = "1.0"
buildscript {
repositories {
google()
mavenCentral()
}
dependencies {
classpath("com.android.tools.build:gradle:7.3.0")
}
}
rootProject.allprojects {
repositories {
google()
mavenCentral()
}
}
apply(plugin = "com.android.library")
apply(from = "../cargokit/gradle/plugin.gradle")
configure<LibraryExtension> {
if (project.extensions.extraProperties.has("android") || project.extensions.findByName("android") != null) {
namespace = "com.flutter_rust_bridge.ccc_cryptography"
}
compileSdk = flutter.compileSdkVersion
ndkVersion = flutter.ndkVersion
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
defaultConfig {
minSdk = flutter.minSdkVersion
targetSdk = flutter.targetSdkVersion
}
}
extensions.configure<Any>("cargokit") {
withGroovyBuilder {
setProperty("manifestDir", "../rust")
setProperty("libname", "ccc_cryptography")
}
}

483
docs/ccc_fplugin_build_linux.rst
View File

@ -1,483 +0,0 @@
CCC Flutter Plugin — Linux Build & Test Guide
=============================================
:Created: 2026-03-16
:Status: Pending (Phase 4.4 and Phase 6.7)
:Relates to: ``docs/ccc_fplugin_phases.rst`` §§ 4.4, 6.7
:Platform: Linux — x86_64 (Ubuntu 22.04 LTS or later recommended)
Overview
--------
The ``ccc_cryptography`` Flutter plugin is feature-complete on macOS, iOS,
and Android. All 16 integration tests pass on those three platforms.
Two Linux-specific tasks remain open in the Milestone 2 verification gate:
* **Phase 4.4** — ``flutter build linux`` succeeds
* **Phase 6.7** — all 16 integration tests pass on a Linux host
This guide provides the step-by-step procedure for a developer on a Linux
machine to complete those two tasks and tick off the remaining gate items.
Related Documents
~~~~~~~~~~~~~~~~~
* ``docs/ccc_fplugin_phases.rst`` — master phase tracker (tasks 4.4, 6.7,
and the Milestone 2 Verification Gate)
* ``docs/ccc_fplugin_architecture_design.rst`` — plugin architecture
* ``docs/ccc_fplugin_build_windows.rst`` — equivalent guide for Windows
* ``docs/README_DEV.rst`` — FRB v2 + Cargokit background
----
Platform Status Summary
-----------------------
============================== ========= ====================
Platform Build Integration Tests
============================== ========= ====================
iOS (aarch64-apple-ios) ✅ 17.1 MB ✅ 16/16 passed
Android (arm64, armv7, x86_64) ✅ 44.6 MB ✅ 16/16 passed
macOS (aarch64-apple-darwin) ✅ 44.5 MB ✅ 16/16 passed
**Linux (x86_64-linux-gnu)** **⏳ TBD** **⏳ TBD**
Windows (x86_64-msvc) ⏳ deferred ⏳ deferred
============================== ========= ====================
----
Prerequisites
-------------
Install the following on the Linux host before proceeding.
Commands shown assume **Ubuntu 22.04 LTS** (or Debian-compatible).
Adjust package names for other distributions as needed.
1. System Build Tools
~~~~~~~~~~~~~~~~~~~~~
::
sudo apt update
sudo apt install -y \
build-essential \
cmake \
ninja-build \
pkg-config \
libgtk-3-dev \
git \
curl \
unzip
``libgtk-3-dev`` is required by the Flutter Linux embedding.
``cmake`` must be ≥ 3.10 (``linux/CMakeLists.txt`` minimum requirement).
Verify::
cmake --version # ≥ 3.10
2. Clang / libclang
~~~~~~~~~~~~~~~~~~~~
wolfSSL's ``build.rs`` uses ``bindgen`` to generate Rust FFI bindings from
C headers. ``bindgen`` requires ``libclang`` at build time.
::
sudo apt install -y clang libclang-dev
Verify::
clang --version
llvm-config --version # optional, confirms LLVM installation
On Ubuntu 22.04 the default APT package installs Clang 14 and places
``libclang.so`` in a path that ``bindgen`` finds automatically — no
``LIBCLANG_PATH`` override is required in the typical case.
3. Flutter SDK
~~~~~~~~~~~~~~
Follow the official Flutter Linux installation:
https://docs.flutter.dev/get-started/install/linux
After installation::
flutter doctor
All items relevant to Linux desktop must be green. Enable Linux desktop
if not already done::
flutter config --enable-linux-desktop
4. Rust Toolchain
~~~~~~~~~~~~~~~~~
Install ``rustup``::
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
Verify the stable toolchain is active::
rustup show
Add the Linux target if not already present::
rustup target add x86_64-unknown-linux-gnu
5. SSH Access to the Internal Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The bridge crate depends on ``ccc_rust`` hosted at the internal SSH server.
Ensure the SSH key for ``git@10.0.5.109`` is present and loaded::
ssh -T git@10.0.5.109
Confirm authentication succeeds before proceeding.
----
Rust Target Setup
-----------------
Add the Linux GNU target to the active toolchain::
rustup target add x86_64-unknown-linux-gnu
Verify it is listed::
rustup target list --installed
Expected output includes ``x86_64-unknown-linux-gnu``.
----
Dependency Configuration
------------------------
The bridge crate at ``rust/Cargo.toml`` currently uses **local macOS path
dependencies** that resolve to ``/Volumes/LUM/...``. These paths do not
exist on a Linux machine and must be replaced before building.
Two options are available:
Option A — Local Clone (Development)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Clone ``lum_ccc_rust`` to a local path, then set path deps accordingly::
git clone ssh://git@10.0.5.109/j3g/lum_ccc_rust.git ~/src/lum_ccc_rust
Edit ``rust/Cargo.toml``::
ccc-crypto-core = { path = "/home/<user>/src/lum_ccc_rust/crates/ccc-crypto-core" }
ccc-crypto-wolfssl = { path = "/home/<user>/src/lum_ccc_rust/crates/ccc-crypto-wolfssl" }
Option B — Git/SSH Dependencies (Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Switch to the git/SSH dependencies that are already present (commented out)
in ``rust/Cargo.toml``.
**Remove** the local macOS path lines::
ccc-crypto-core = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-core" }
ccc-crypto-wolfssl = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-wolfssl" }
**Uncomment** the git lines::
ccc-crypto-core = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" }
ccc-crypto-wolfssl = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" }
Pre-fetch the dependency to confirm SSH access works::
cd rust
cargo fetch
.. note::
Before cutting the ``v0.1.0`` tag, replace the commit hash with the
exact release tag — see the Milestone 2 Verification Gate in
``docs/ccc_fplugin_phases.rst``.
----
Environment Variables
---------------------
Linux with the APT-installed ``clang`` + ``libclang-dev`` packages typically
requires **no environment variable overrides** — bindgen locates
``libclang.so`` via ``llvm-config`` automatically.
LIBCLANG_PATH (if needed)
~~~~~~~~~~~~~~~~~~~~~~~~~~
If the build fails with a bindgen error about ``libclang`` not found, set
``LIBCLANG_PATH`` explicitly::
export LIBCLANG_PATH=$(llvm-config --libdir)
Add to ``~/.bashrc`` or ``~/.profile`` to make it permanent.
To use ``.cargo/config.toml`` instead::
[env]
LIBCLANG_PATH = "/usr/lib/llvm-14/lib"
Verify the library is present::
ls $LIBCLANG_PATH/libclang.so*
BINDGEN_EXTRA_CLANG_ARGS (if needed)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If bindgen cannot locate system headers (e.g. ``stddef.h`` errors), add::
export BINDGEN_EXTRA_CLANG_ARGS="--target=x86_64-unknown-linux-gnu"
This mirrors the ``BINDGEN_EXTRA_CLANG_ARGS`` fix applied for Android
in Phase 4.6. On Ubuntu 22.04 with standard clang, this is not expected
to be necessary.
----
Phase 4.4 — Build Verification
-------------------------------
Run from the ``example/`` directory::
cd example
flutter build linux --release
Expected result:
* Build completes with no errors.
* The compiled binary and Cargokit-built ``.so`` are placed in::
example/build/linux/x64/release/bundle/
* Record the output bundle size for the verification gate entry.
.. note::
Cargokit invokes ``cargo build --target x86_64-unknown-linux-gnu``
automatically during ``flutter build linux``. The first build compiles
wolfSSL from source and may take several minutes.
On success, update ``docs/ccc_fplugin_phases.rst`` task 4.4 to ✅ and record
the build output bundle size.
----
Phase 6.7 — Integration Tests on Linux
----------------------------------------
Run from the ``example/`` directory::
cd example
flutter test integration_test/ccc_crypto_test.dart -d linux
Expected result: **16/16 tests passed**.
The 16 tests and their coverage::
[5.1] AEAD roundtrip — AES-256-GCM encrypt/decrypt (1 KB)
[5.2] AEAD roundtrip — ChaCha20-Poly1305 encrypt/decrypt (1 KB)
[5.3] AEAD tamper — modified ciphertext → CccAuthenticationFailed
[5.4] KDF known-vector — HKDF-SHA256 vs RFC 5869 Test Case 1 (42 bytes)
[5.5] MAC roundtrip — HMAC-SHA256 compute + verify returns true
[5.6] MAC tamper — modified data → verify returns false
[5.7] Hash known-vector — SHA-256/384/512 ("abc" test vector)
[5.8] KEM roundtrip — X25519 keygen/encap/decap; shared secrets match
[5.9] KEM roundtrip — X448 keygen/encap/decap; shared secrets match
[5.10] Provider catalog — listProviders() non-empty; getCapabilities() returns scores
[5.11] Self-test — runSelfTest() returns structured report
[5.12] Error handling — invalid key/nonce lengths → correct CccException subtypes
[5.13] Algorithm ID mapping — catalog IDs match Rust enum discriminants (AES-GCM=12, ...)
.. note::
Test 5.11 (self-test) is expected to report AEAD length-mismatch failures
for AES-256-GCM and ChaCha20-Poly1305. This is a known upstream bug in
``ccc_rust`` (the self-test vectors do not account for the appended auth
tag in encrypt output). It is not Linux-specific and the test still
passes overall. See Phase 5 known issues in ``docs/ccc_fplugin_phases.rst``.
On success, update ``docs/ccc_fplugin_phases.rst`` task 6.7 to ✅ and mark
the corresponding Milestone 2 Verification Gate item.
----
Linux Verification Checklist
-----------------------------
Complete this checklist on the Linux host. Items map directly to the
open entries in the Milestone 2 Verification Gate in
``docs/ccc_fplugin_phases.rst``.
.. list-table::
:header-rows: 1
:widths: 5 80 15
* - #
- Item
- Status
* - L-1
- ``rustup target add x86_64-unknown-linux-gnu`` installed and listed
- ☐
* - L-2
- ``rust/Cargo.toml`` updated — local macOS paths replaced with
git/SSH deps (or Linux local paths)
- ☐
* - L-3
- ``clang`` and ``libclang-dev`` installed; bindgen resolves
``libclang.so`` without manual override
- ☐
* - L-4
- ``ssh -T git@10.0.5.109`` succeeds (SSH key loaded)
- ☐
* - L-5
- ``flutter build linux --release`` succeeds; bundle size recorded
- ☐
* - L-6
- Native ``.so`` present in the release bundle directory
- ☐
* - L-7
- ``flutter test integration_test/ccc_crypto_test.dart -d linux``
— 16/16 passed
- ☐
* - L-8
- Tasks 4.4 and 6.7 marked ✅ in ``docs/ccc_fplugin_phases.rst``
- ☐
* - L-9
- Milestone 2 Verification Gate Linux items checked
- ☐
----
Troubleshooting
---------------
bindgen / libclang not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom**::
error: failed to run custom build command for `ccc-crypto-wolfssl`
thread 'main' panicked at '... Unable to find libclang ...'
**Fix:** Install ``clang`` and ``libclang-dev``::
sudo apt install -y clang libclang-dev
Then set ``LIBCLANG_PATH`` if bindgen still cannot find it::
export LIBCLANG_PATH=$(llvm-config --libdir)
If multiple LLVM versions are installed, specify the one in use::
export LIBCLANG_PATH=/usr/lib/llvm-14/lib
Missing system headers during bindgen
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom:** bindgen reports it cannot find ``stddef.h``, ``stdint.h``,
or similar C standard headers.
**Fix:** Install the Linux headers package::
sudo apt install -y linux-libc-dev
If the error persists, set::
export BINDGEN_EXTRA_CLANG_ARGS="--target=x86_64-unknown-linux-gnu"
GTK development headers not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom:** ``flutter build linux`` fails with errors about missing
``gtk/gtk.h`` or ``pkg-config`` not finding ``gtk+-3.0``.
**Fix:**::
sudo apt install -y libgtk-3-dev pkg-config
cmake not found or too old
~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom:** Cargokit or ``flutter build linux`` fails with "CMake not
found" or "CMake version 3.10 or later required".
**Fix:**::
sudo apt install -y cmake
Ubuntu 22.04 ships CMake 3.22 which satisfies the ≥ 3.10 requirement.
If on an older distro, install via the Kitware APT repository or snap::
sudo snap install cmake --classic
cargo fetch fails — SSH key not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom**::
error: failed to authenticate when downloading repository
Caused by: ... no auth methods succeeded
**Fix:** Ensure the SSH agent has the correct key loaded::
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519 # adjust key filename
Or configure ``~/.ssh/config``::
Host 10.0.5.109
User git
IdentityFile ~/.ssh/id_ed25519
flutter build linux fails — display not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom:** Running integration tests on a headless server fails with
a display-related error (Flutter Linux requires a display server).
**Fix:** Use a virtual framebuffer::
sudo apt install -y xvfb
Xvfb :99 -screen 0 1280x1024x24 &
export DISPLAY=:99
flutter test integration_test/ccc_crypto_test.dart -d linux
Alternatively, run on a machine with a desktop environment, or use a
remote desktop session.
ninja not found
~~~~~~~~~~~~~~~~
**Symptom:** CMake generates a build but ``ninja`` is not found.
**Fix:**::
sudo apt install -y ninja-build
----
After Completion
----------------
Once both Phase 4.4 and Phase 6.7 are verified:
1. Update ``docs/ccc_fplugin_phases.rst``:
* Mark tasks 4.4 and 6.7 ✅
* Check the corresponding Milestone 2 Verification Gate entries
2. If the ``ccc_rust`` dependency commit hash is still floating, pin it
to the final ``v0.1.0`` tag of that repository.
3. Proceed with the remaining Phase 6 tasks (6.9 example app update,
6.10 CHANGELOG, 6.11 final review, 6.12 ``v0.1.0`` tag).
Windows (Phase 4.5 / Phase 6.8) follows the same general pattern but
substitutes ``x86_64-pc-windows-msvc`` as the Rust target. LLVM must
be installed manually on Windows, and ``LIBCLANG_PATH`` is always required.
See ``docs/ccc_fplugin_build_windows.rst`` for full details.

477
docs/ccc_fplugin_build_windows.rst
View File

@ -1,477 +0,0 @@
CCC Flutter Plugin — Windows Build & Test Guide
===============================================
:Created: 2026-03-16
:Status: Pending (Phase 4.5 and Phase 6.8)
:Relates to: ``docs/ccc_fplugin_phases.rst`` §§ 4.5, 6.8
:Platform: Windows 10 / Windows 11 — x86_64
Overview
--------
The ``ccc_cryptography`` Flutter plugin is feature-complete on macOS, iOS,
and Android. All 16 integration tests pass on those three platforms.
Two Windows-specific tasks remain open in the Milestone 2 verification gate:
* **Phase 4.5** — ``flutter build windows`` succeeds
* **Phase 6.8** — all 16 integration tests pass on a Windows host
This guide provides the step-by-step procedure for a developer on a Windows
machine to complete those two tasks and tick off the remaining gate items.
Related Documents
~~~~~~~~~~~~~~~~~
* ``docs/ccc_fplugin_phases.rst`` — master phase tracker (tasks 4.5, 6.8,
and the Milestone 2 Verification Gate)
* ``docs/ccc_fplugin_architecture_design.rst`` — plugin architecture
* ``docs/README_DEV.rst`` — FRB v2 + Cargokit background
----
Platform Status Summary
-----------------------
============================== ========= ====================
Platform Build Integration Tests
============================== ========= ====================
iOS (aarch64-apple-ios) ✅ 17.1 MB ✅ 16/16 passed
Android (arm64, armv7, x86_64) ✅ 44.6 MB ✅ 16/16 passed
macOS (aarch64-apple-darwin) ✅ 44.5 MB ✅ 16/16 passed
Linux (x86_64-linux-gnu) ⏳ deferred ⏳ deferred
**Windows (x86_64-msvc)** **⏳ TBD** **⏳ TBD**
============================== ========= ====================
----
Prerequisites
-------------
Install the following on the Windows host before proceeding.
1. Visual Studio 2022
~~~~~~~~~~~~~~~~~~~~~
Install **Visual Studio 2022** (Community edition or higher) with the
following workloads and components:
* **Desktop development with C++**
* MSVC v143 — VS 2022 C++ x64/x86 build tools (selected by default)
* Windows 11 SDK (10.0.22000 or later) — or Windows 10 SDK ≥ 10.0.20348
* CMake tools for Windows (or install CMake ≥ 3.14 separately)
.. note::
``windows/CMakeLists.txt`` requires ``cmake_minimum_required(VERSION 3.14)``.
The CMake bundled with VS 2022 satisfies this requirement.
2. Flutter SDK
~~~~~~~~~~~~~~
Install Flutter (stable channel) and verify::
flutter doctor
All items relevant to Windows desktop must be green. Enable Windows desktop
if not already done::
flutter config --enable-windows-desktop
3. Rust Toolchain (MSVC ABI — not GNU)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install ``rustup`` from https://rustup.rs. During installation select the
**MSVC** ABI, which is the default when Visual Studio is detected.
.. warning::
The GNU ABI toolchain (``*-pc-windows-gnu``) does **not** link against
the MSVC C runtime and will fail when building wolfSSL.
Only ``x86_64-pc-windows-msvc`` is supported.
Verify the active toolchain is MSVC::
rustup show
Add the Windows target if not already present::
rustup target add x86_64-pc-windows-msvc
4. LLVM / Clang
~~~~~~~~~~~~~~~
wolfSSL's ``build.rs`` uses ``bindgen`` to generate Rust FFI bindings from
C headers. ``bindgen`` requires a Clang/libclang installation at build time.
Install LLVM (≥ 14) using one of the following methods:
* **winget** (preferred)::
winget install LLVM.LLVM
* **Chocolatey**::
choco install llvm
* **Installer** from https://llvm.org/releases — check
"Add LLVM to the system PATH" during install.
After installation, set ``LIBCLANG_PATH`` (see § Environment Variables).
5. Git with SSH Access to the Internal Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The bridge crate depends on ``ccc_rust`` hosted at the internal SSH server.
Ensure Git is installed and the SSH key for ``git@10.0.5.109`` is present::
ssh -T git@10.0.5.109
Confirm authentication succeeds before proceeding.
----
Rust Target Setup
-----------------
Add the Windows MSVC target to the active toolchain::
rustup target add x86_64-pc-windows-msvc
Verify it is listed::
rustup target list --installed
Expected output includes ``x86_64-pc-windows-msvc``.
----
Dependency Configuration
------------------------
The bridge crate at ``rust/Cargo.toml`` currently uses **local macOS path
dependencies** that resolve to ``/Volumes/LUM/...``. These paths do not
exist on a Windows machine and must be replaced before building.
Two options are available:
Option A — Local Clone (Development)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Clone ``lum_ccc_rust`` to a Windows path, then set path deps accordingly::
git clone ssh://git@10.0.5.109/j3g/lum_ccc_rust.git C:\src\lum_ccc_rust
Edit ``rust/Cargo.toml``::
ccc-crypto-core = { path = "C:/src/lum_ccc_rust/crates/ccc-crypto-core" }
ccc-crypto-wolfssl = { path = "C:/src/lum_ccc_rust/crates/ccc-crypto-wolfssl" }
Option B — Git/SSH Dependencies (Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Switch to the git/SSH dependencies that are already present (commented out)
in ``rust/Cargo.toml``.
**Remove** the local macOS path lines::
ccc-crypto-core = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-core" }
ccc-crypto-wolfssl = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-wolfssl" }
**Uncomment** the git lines::
ccc-crypto-core = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" }
ccc-crypto-wolfssl = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" }
Pre-fetch the dependency to confirm SSH access works::
cd rust
cargo fetch
.. note::
Before cutting the ``v0.1.0`` tag, replace the commit hash with the
exact release tag — see the Milestone 2 Verification Gate in
``docs/ccc_fplugin_phases.rst``.
----
Environment Variables
---------------------
Set the following before running the build. Use PowerShell or set them
permanently in System Properties → Advanced → Environment Variables.
LIBCLANG_PATH
~~~~~~~~~~~~~
Required by ``bindgen`` (used in wolfSSL's ``build.rs``) to locate
``libclang.dll``.
PowerShell::
$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"
CMD::
set LIBCLANG_PATH=C:\Program Files\LLVM\bin
Verify ``libclang.dll`` is present::
dir "$env:LIBCLANG_PATH\libclang.dll"
Optionally, make it permanent via ``.cargo/config.toml`` in the project root::
[env]
LIBCLANG_PATH = "C:\\Program Files\\LLVM\\bin"
BINDGEN_EXTRA_CLANG_ARGS (if needed)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On Android, wolfSSL's ``build.rs`` required extra Clang arguments to find
system headers; that fix was applied in Phase 4.6 via
``BINDGEN_EXTRA_CLANG_ARGS_<target>`` in Cargokit's Android environment.
A similar issue may occur on Windows if bindgen cannot locate MSVC headers.
If the build fails with errors about missing ``stddef.h`` or similar standard
headers, add::
$env:BINDGEN_EXTRA_CLANG_ARGS = "--target=x86_64-pc-windows-msvc -fms-extensions -fms-compatibility"
See the Troubleshooting section for full details.
----
Phase 4.5 — Build Verification
-------------------------------
Run from the ``example/`` directory::
cd example
flutter build windows --release
Expected result:
* Build completes with no errors.
* The compiled ``.exe`` and the Cargokit-built ``.dll`` are placed in::
example\build\windows\x64\runner\Release\
* Record the output directory size for the verification gate entry.
.. note::
Cargokit invokes ``cargo build --target x86_64-pc-windows-msvc``
automatically during ``flutter build windows``. The first build compiles
wolfSSL from source and may take several minutes.
On success, update ``docs/ccc_fplugin_phases.rst`` task 4.5 to ✅ and record
the build output size.
----
Phase 6.8 — Integration Tests on Windows
-----------------------------------------
Run from the ``example/`` directory::
cd example
flutter test integration_test/ccc_crypto_test.dart -d windows
Expected result: **16/16 tests passed**.
The 16 tests and their coverage::
[5.1] AEAD roundtrip — AES-256-GCM encrypt/decrypt (1 KB)
[5.2] AEAD roundtrip — ChaCha20-Poly1305 encrypt/decrypt (1 KB)
[5.3] AEAD tamper — modified ciphertext → CccAuthenticationFailed
[5.4] KDF known-vector — HKDF-SHA256 vs RFC 5869 Test Case 1 (42 bytes)
[5.5] MAC roundtrip — HMAC-SHA256 compute + verify returns true
[5.6] MAC tamper — modified data → verify returns false
[5.7] Hash known-vector — SHA-256/384/512 ("abc" test vector)
[5.8] KEM roundtrip — X25519 keygen/encap/decap; shared secrets match
[5.9] KEM roundtrip — X448 keygen/encap/decap; shared secrets match
[5.10] Provider catalog — listProviders() non-empty; getCapabilities() returns scores
[5.11] Self-test — runSelfTest() returns structured report
[5.12] Error handling — invalid key/nonce lengths → correct CccException subtypes
[5.13] Algorithm ID mapping — catalog IDs match Rust enum discriminants (AES-GCM=12, ...)
.. note::
Test 5.11 (self-test) is expected to report AEAD length-mismatch failures
for AES-256-GCM and ChaCha20-Poly1305. This is a known upstream bug in
``ccc_rust`` (the self-test vectors do not account for the appended auth
tag in encrypt output). It is not Windows-specific and the test still
passes overall. See Phase 5 known issues in ``docs/ccc_fplugin_phases.rst``.
On success, update ``docs/ccc_fplugin_phases.rst`` task 6.8 to ✅ and mark
the corresponding Milestone 2 Verification Gate item.
----
Windows Verification Checklist
-------------------------------
Complete this checklist on the Windows host. Items map directly to the
open entries in the Milestone 2 Verification Gate in
``docs/ccc_fplugin_phases.rst``.
.. list-table::
:header-rows: 1
:widths: 5 80 15
* - #
- Item
- Status
* - W-1
- ``rustup target add x86_64-pc-windows-msvc`` installed and listed
- ☐
* - W-2
- ``rust/Cargo.toml`` updated — local macOS paths replaced with
git/SSH deps (or Windows local paths)
- ☐
* - W-3
- ``LIBCLANG_PATH`` set and ``libclang.dll`` reachable at that path
- ☐
* - W-4
- ``SSH -T git@10.0.5.109`` succeeds (SSH key loaded)
- ☐
* - W-5
- ``flutter build windows --release`` succeeds; output size recorded
- ☐
* - W-6
- Native ``.dll`` present and bundled in the release output directory
- ☐
* - W-7
- ``flutter test integration_test/ccc_crypto_test.dart -d windows``
— 16/16 passed
- ☐
* - W-8
- Tasks 4.5 and 6.8 marked ✅ in ``docs/ccc_fplugin_phases.rst``
- ☐
* - W-9
- Milestone 2 Verification Gate Windows items checked
- ☐
----
Troubleshooting
---------------
bindgen / libclang not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom**::
error: failed to run custom build command for `ccc-crypto-wolfssl`
thread 'main' panicked at '... Unable to find libclang ...'
**Fix:** Set ``LIBCLANG_PATH`` to the LLVM ``bin/`` directory containing
``libclang.dll``. Typical path after winget install::
C:\Program Files\LLVM\bin
MSVC headers not found during bindgen
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom:** bindgen reports it cannot find ``stddef.h``, ``stdint.h``, or
similar MSVC standard headers during the wolfSSL ``build.rs`` run.
**Fix:** Ensure the MSVC C++ workload is installed in VS 2022, then add::
$env:BINDGEN_EXTRA_CLANG_ARGS = "--target=x86_64-pc-windows-msvc -fms-extensions -fms-compatibility"
This mirrors the ``BINDGEN_EXTRA_CLANG_ARGS`` fix applied for Android
in Phase 4.6. If the issue persists, check that the VS 2022 "Windows
SDK" component is installed (bindgen needs its ``include/`` headers).
GNU toolchain conflict
~~~~~~~~~~~~~~~~~~~~~~
**Symptom:** Linker errors referencing ``libgcc``, ``mingw``, or
``crt2.obj`` symbols.
**Fix:** Confirm the active Rust toolchain is MSVC::
rustup show
If the default is ``stable-x86_64-pc-windows-gnu``, override it for
this project::
rustup override set stable-x86_64-pc-windows-msvc
CMake not found
~~~~~~~~~~~~~~~
**Symptom:** Cargokit or ``flutter build windows`` fails reporting
"CMake not found" or similar.
**Fix:** Ensure CMake is in ``PATH``. VS 2022 installs CMake to::
C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin
Add it to ``PATH``, or install the standalone CMake distribution and
check "Add CMake to PATH" during setup. Verify::
cmake --version
Windows long path errors
~~~~~~~~~~~~~~~~~~~~~~~~
wolfSSL's source tree and Cargo's registry can produce paths exceeding
Windows' 260-character default limit.
**Fix:** Enable long path support (requires an elevated PowerShell)::
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
And configure Git::
git config --global core.longpaths true
cargo fetch fails — SSH key not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom**::
error: failed to authenticate when downloading repository
Caused by: ... no auth methods succeeded
**Fix:** Ensure the SSH agent has the correct key loaded::
ssh-add $env:USERPROFILE\.ssh\id_ed25519 # adjust key filename
Or configure ``~/.ssh/config``::
Host 10.0.5.109
User git
IdentityFile ~/.ssh/id_ed25519
flutter build windows fails — missing flutter_windows.dll
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Symptom:** The built executable fails to run (not a build error).
**Fix:** Always use ``flutter build windows --release`` for testing;
never copy just the ``.exe``. The ``Release\`` folder must be kept
intact — it contains ``flutter_windows.dll`` and ``data/``.
----
After Completion
----------------
Once both Phase 4.5 and Phase 6.8 are verified:
1. Update ``docs/ccc_fplugin_phases.rst``:
* Mark tasks 4.5 and 6.8 ✅
* Check the corresponding Milestone 2 Verification Gate entries
2. If the ``ccc_rust`` dependency commit hash is still floating, pin it
to the final ``v0.1.0`` tag of that repository.
3. Proceed with the remaining Phase 6 tasks (6.9 example app update,
6.10 CHANGELOG, 6.11 final review, 6.12 ``v0.1.0`` tag).
Linux (Phase 4.4 / Phase 6.7) follows the same general pattern as Windows
but substitutes ``x86_64-unknown-linux-gnu`` as the Rust target and uses
a Clang package from the system package manager (e.g., ``apt install clang``).
No ``LIBCLANG_PATH`` override is typically needed on Linux.

593
docs/ccc_rust_app_integration_phases.rst
View File

@ -1,593 +0,0 @@
CCC Cryptography Plugin — Milestone 3 App Integration
======================================================
:Created: 2026-03-16
:Status: Ready to Begin (API frozen; Windows + Linux tests deferred)
:Audience: LetUsMsg application team
:Plugin package: ``ccc_cryptography``
:Plugin version: ``0.0.1`` (pre-tag; ``v0.1.0`` tag pending)
:Milestone: 3 of 3
Overview
--------
This document describes how the **LetUsMsg** application integrates the
``ccc_cryptography`` Flutter plugin.
Milestone 2 delivered a fully tested Flutter/Dart crypto plugin backed by
``ccc_rust`` (wolfSSL). All 16 integration tests pass on macOS, iOS, and
Android. Windows and Linux platform builds are deferred but do not block
app integration — the Dart API is frozen.
**The single rule for Milestone 3:** consume the published Dart API only.
No Rust changes, no bridge changes, no modifications to the plugin source.
Related Documents
~~~~~~~~~~~~~~~~~
* ``docs/ccc_fplugin_phases.rst`` — Milestone 2 phase completion status
* ``docs/ccc_fplugin_architecture_design.rst`` — Plugin architecture
* ``docs/ccc_fplugin_build_windows.rst`` — Windows build guide (deferred)
----
Open Items (not blocking M3 start)
-----------------------------------
The following Milestone 2 tasks are open but do not affect the Dart API:
* ``flutter build windows`` / integration tests on Windows — deferred
* ``flutter build linux`` / integration tests on Linux — deferred
* ``CHANGELOG.md`` not yet updated
* ``ccc_rust`` dependency commit not yet pinned to the final ``v0.1.0`` tag
* Plugin not yet tagged ``v0.1.0``
These will be resolved in parallel. The app may begin integration against
the current commit. When the ``v0.1.0`` tag is cut, update the git ref in
the app's ``pubspec.yaml``.
----
Phase Overview
--------------
====== ============================================ ========== ============
Phase Title Status Depends on
====== ============================================ ========== ============
M3-1 Add plugin dependency Not started —
M3-2 App startup initialisation Not started M3-1
M3-3 Replace AEAD crypto stubs Not started M3-2
M3-4 Replace KDF stubs Not started M3-2
M3-5 Replace MAC stubs Not started M3-2
M3-6 Replace Hash stubs Not started M3-2
M3-7 Replace KEM stubs Not started M3-2
M3-8 Provider catalog integration Not started M3-2
M3-9 Self-test debug UI Not started M3-2
M3-10 Exception handling audit Not started M3-3–7
M3-11 End-to-end app testing Not started M3-3–9
====== ============================================ ========== ============
----
Phase M3-1 — Add Plugin Dependency
------------------------------------
Add the plugin to the LetUsMsg ``pubspec.yaml``::
dependencies:
ccc_cryptography:
git:
url: ssh://git@10.0.5.109/j3g/ccc_fplugin.git
ref: main # replace with "v0.1.0" once tagged
Then fetch::
flutter pub get
.. note::
The plugin is not published to pub.dev. It is consumed as a git
dependency. When the ``v0.1.0`` tag is cut, change ``ref: main``
to ``ref: v0.1.0`` and pin the dependency.
----
Phase M3-2 — App Startup Initialisation
-----------------------------------------
``CccCrypto.init()`` must be called **once** at application startup,
before any cryptographic operation. It registers the wolfSSL provider
and initialises the FRB runtime. It is safe to call multiple times
(idempotent), but should be called exactly once in practice.
Typical placement is in ``main()`` before ``runApp()``::
import 'package:ccc_cryptography/ccc_cryptography.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await CccCrypto.init();
runApp(const MyApp());
}
Exit criteria:
* ``CccCrypto.init()`` called before any crypto operation in the app
* No ``CccInternalError`` thrown at startup (provider registered OK)
----
Phase M3-3 — Replace AEAD Crypto Stubs
-----------------------------------------
Replace existing encrypt/decrypt stubs with ``CccCrypto.encryptAead``
and ``CccCrypto.decryptAead``.
API signatures
~~~~~~~~~~~~~~
.. code-block:: dart
// Encrypt — returns ciphertext with authentication tag appended
Future<Uint8List> CccCrypto.encryptAead({
required CccAeadAlgorithm algorithm,
required Uint8List key,
required Uint8List nonce,
required Uint8List plaintext,
Uint8List? aad, // optional associated data; defaults to empty
});
// Decrypt — strips and verifies tag internally
// Throws CccAuthenticationFailed if tag does not verify
Future<Uint8List> CccCrypto.decryptAead({
required CccAeadAlgorithm algorithm,
required Uint8List key,
required Uint8List nonce,
required Uint8List ciphertext, // ciphertext + tag as returned by encryptAead
Uint8List? aad,
});
Algorithm enum and key/nonce sizes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
========================= ===== ======= ===== ========
``CccAeadAlgorithm`` ID Key Nonce Tag
========================= ===== ======= ===== ========
``aesGcm256`` 12 32 B 12 B 16 B
``chaCha20Poly1305`` 13 32 B 12 B 16 B
``xChaCha20Poly1305`` 14 32 B 24 B 16 B
``ascon128a`` 15 16 B 16 B 16 B
========================= ===== ======= ===== ========
.. important::
The returned ciphertext from ``encryptAead`` is
``len(plaintext) + 16 bytes`` (plaintext + 16-byte tag concatenated).
Pass the entire slice to ``decryptAead`` — do not strip the tag
manually.
Example
~~~~~~~
.. code-block:: dart
final key = ... // 32 bytes, from KDF or secure RNG
final nonce = ... // 12 bytes, non-repeating per (key, message) pair
final ciphertext = await CccCrypto.encryptAead(
algorithm: CccAeadAlgorithm.aesGcm256,
key: key,
nonce: nonce,
plaintext: message,
);
final plaintext = await CccCrypto.decryptAead(
algorithm: CccAeadAlgorithm.aesGcm256,
key: key,
nonce: nonce,
ciphertext: ciphertext, // full slice including tag
);
----
Phase M3-4 — Replace KDF Stubs
---------------------------------
API signature
~~~~~~~~~~~~~
.. code-block:: dart
Future<Uint8List> CccCrypto.deriveKey({
required CccKdfAlgorithm algorithm,
required Uint8List ikm, // input key material
Uint8List? salt, // optional; defaults to empty
Uint8List? info, // optional context; defaults to empty
required int length, // desired output length in bytes
});
Algorithm enum
~~~~~~~~~~~~~~
========================== ===== ==========
``CccKdfAlgorithm`` ID Notes
========================== ===== ==========
``sha256`` 1 HKDF-SHA256
``sha384`` 2 HKDF-SHA384
``sha512`` 3 HKDF-SHA512
``blake2b512`` 4 BLAKE2b-512 KDF
========================== ===== ==========
Example — derive a 32-byte session key via HKDF-SHA256
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: dart
final sessionKey = await CccCrypto.deriveKey(
algorithm: CccKdfAlgorithm.sha256,
ikm: sharedSecret,
salt: sessionSalt,
info: Uint8List.fromList(utf8.encode('letusmsg-session-v1')),
length: 32,
);
----
Phase M3-5 — Replace MAC Stubs
---------------------------------
API signatures
~~~~~~~~~~~~~~
.. code-block:: dart
Future<Uint8List> CccCrypto.computeMac({
required CccMacAlgorithm algorithm,
required Uint8List key,
required Uint8List data,
});
// Returns true if valid, false otherwise — never throws for tampered data
Future<bool> CccCrypto.verifyMac({
required CccMacAlgorithm algorithm,
required Uint8List key,
required Uint8List data,
required Uint8List mac,
});
Algorithm enum
~~~~~~~~~~~~~~
======================== =====
``CccMacAlgorithm`` ID
======================== =====
``hmacSha256`` 30
``hmacSha512`` 32
``blake2bMac`` 33
======================== =====
.. note::
``verifyMac`` uses a constant-time comparison in Rust to prevent
timing attacks. Do not compare MAC tags in Dart.
----
Phase M3-6 — Replace Hash Stubs
----------------------------------
API signature
~~~~~~~~~~~~~
.. code-block:: dart
Future<Uint8List> CccCrypto.hash({
required CccHashAlgorithm algorithm,
required Uint8List data,
});
Algorithm enum
~~~~~~~~~~~~~~
======================== =====
``CccHashAlgorithm`` ID
======================== =====
``sha256`` 40
``sha384`` 41
``sha512`` 42
``blake2b512`` 43
``sha3_256`` 44
======================== =====
----
Phase M3-7 — Replace KEM Stubs
---------------------------------
API signatures
~~~~~~~~~~~~~~
.. code-block:: dart
// Key generation
Future<CccKemKeyPair> CccCrypto.kemGenerateKeypair({
required CccKemAlgorithm algorithm,
});
// CccKemKeyPair { Uint8List publicKey; Uint8List privateKey; }
// Encapsulation — sender uses recipient's public key
Future<CccKemEncapResult> CccCrypto.kemEncapsulate({
required CccKemAlgorithm algorithm,
required Uint8List publicKey,
});
// CccKemEncapResult { Uint8List ciphertext; Uint8List sharedSecret; }
// Decapsulation — recipient recovers shared secret
Future<Uint8List> CccCrypto.kemDecapsulate({
required CccKemAlgorithm algorithm,
required Uint8List privateKey,
required Uint8List ciphertext,
});
Algorithm enum
~~~~~~~~~~~~~~
========================== ===== ==============================
``CccKemAlgorithm`` ID Notes
========================== ===== ==============================
``x25519`` 50 Available
``x448`` 51 Available
``mlKem768`` 52 Deferred (not compiled in v0.1)
``mlKem1024`` 53 Deferred
``classicMcEliece`` 54 Deferred
========================== ===== ==============================
.. warning::
``privateKey`` in ``CccKemKeyPair`` is Dart-side memory.
Discard it as soon as decapsulation is complete.
Do not persist or log private keys.
----
Phase M3-8 — Provider Catalog Integration
-------------------------------------------
``CccProviderCatalog`` exposes runtime algorithm availability so the
app can adapt its UI and protocol negotiation to what the provider
actually supports.
API
~~~
.. code-block:: dart
// One-shot fetch; cache the result for the session lifetime
final catalog = await CccCrypto.getCapabilities();
catalog.providerName // "wolfssl"
catalog.aead // List<CccAlgorithmInfo>
catalog.availableAead // filtered: only available == true
catalog.kdf / .availableKdf
catalog.mac / .availableMac
catalog.hash / .availableHash
catalog.kem / .availableKem
// CccAlgorithmInfo fields:
// int id (matches enum discriminant)
// String name (e.g. "AES-256-GCM")
// bool available
// bool deterministicIo
// int efficiencyScore (0–100)
// int reliabilityScore (0–100)
Also available — synchronous provider list::
final List<String> providers = CccCrypto.listProviders();
// ["wolfssl"]
Suggested app usage
~~~~~~~~~~~~~~~~~~~~
* Cache the ``CccProviderCatalog`` in a top-level service singleton
after ``CccCrypto.init()``.
* Use ``availableAead``, ``availableKem`` etc. to populate algorithm
selection UI and protocol negotiation logic.
* Use ``efficiencyScore`` / ``reliabilityScore`` to recommend a default
algorithm when the user has no preference.
----
Phase M3-9 — Self-Test Debug UI
----------------------------------
Expose ``CccCrypto.runSelfTest()`` in a developer/debug settings screen
to give field visibility into provider health.
API
~~~
.. code-block:: dart
final CccSelfTestResult result = await CccCrypto.runSelfTest();
result.providerName // "wolfssl"
result.allPassed // bool — false if any algorithm fails
result.results // List<CccAlgorithmTestResult>
result.failures // filtered: only failed results
// CccAlgorithmTestResult fields:
// int algoId
// String algoName
// bool passed
// String? errorMessage // null on pass
Known caveat
~~~~~~~~~~~~
The ``ccc_rust`` AEAD self-test vectors currently miscount the output
length (they do not account for the appended 16-byte authentication tag).
This causes ``AES-256-GCM`` and ``ChaCha20-Poly1305`` to report failures
in the self-test report even though those algorithms work correctly.
This is a known upstream bug in ``ccc_rust`` and does not affect
production encrypt/decrypt operations. The debug UI should note this
when displaying AEAD self-test failures.
----
Phase M3-10 — Exception Handling Audit
-----------------------------------------
All ``CccCrypto`` methods throw typed subclasses of ``CccException``
(a ``sealed class``). The full hierarchy:
.. code-block:: dart
sealed class CccException implements Exception {
final String message;
}
class CccUnsupportedAlgorithm extends CccException { ... }
class CccInvalidKey extends CccException { ... }
class CccInvalidNonce extends CccException { ... }
class CccAuthenticationFailed extends CccException { ... }
class CccInvalidInput extends CccException { ... }
class CccFeatureNotCompiled extends CccException { ... }
class CccInternalError extends CccException { ... }
Handling guidelines
~~~~~~~~~~~~~~~~~~~~
* Catch ``CccAuthenticationFailed`` specifically — it is the signal
for a tampered or corrupted message. Do not silently discard it.
* Catch ``CccUnsupportedAlgorithm`` at the protocol negotiation layer
to fall back gracefully.
* Catch ``CccInvalidKey`` / ``CccInvalidNonce`` at the key-management
layer — these indicate a programming error (wrong buffer size) and
should be surfaced in development, not silently swallowed.
* ``CccInternalError`` is unexpected; log it and surface a generic
"crypto failure" error to the user.
Dart 3 exhaustive switch example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: dart
try {
final ct = await CccCrypto.encryptAead(...);
} on CccException catch (e) {
switch (e) {
case CccAuthenticationFailed():
// message tampered
case CccInvalidKey():
// bad key — developer error
case CccInvalidNonce():
// bad nonce — developer error
case CccUnsupportedAlgorithm():
// negotiate fallback
case CccFeatureNotCompiled():
// algorithm not built in
case CccInvalidInput():
// bad input data
case CccInternalError():
// log and surface generic error
}
}
Audit checklist
~~~~~~~~~~~~~~~~
For every call-site that replaces an existing crypto stub, verify:
* ``CccAuthenticationFailed`` is caught and handled (not re-thrown as
a generic error)
* Key / nonce sizes match the table in Phase M3-3 (wrong sizes →
``CccInvalidKey`` / ``CccInvalidNonce``)
* No raw ``CccException`` is exposed to end-users — wrap in
app-level error types
----
Phase M3-11 — End-to-End App Testing
---------------------------------------
Run the existing LetUsMsg integration test suite after all stubs are
replaced to confirm no regressions.
Additionally verify:
* App startup completes with ``CccCrypto.init()`` — no crash or timeout
* Encrypt → transmit → decrypt roundtrip succeeds on iOS, Android, macOS
* Provider catalog loads and populates the settings UI correctly
* Self-test screen shows expected results (note AEAD caveat above)
* No ``CccException`` surfaces to end-users under normal operation
* Private key material is not logged or persisted anywhere in the app
----
Hard Boundaries for Milestone 3
---------------------------------
The following are **forbidden** during app integration:
* Modifying any file in the ``ccc_cryptography`` plugin repository
* Implementing cryptographic logic in Dart
* Calling ``ccc_rust`` or ``flutter_rust_bridge`` APIs directly
* Depending on internal generated files
(e.g. ``src/rust/api/crypto.dart``, ``frb_generated.dart``)
* Persisting or logging raw private keys (``CccKemKeyPair.privateKey``)
The app must depend **only** on the public barrel export::
import 'package:ccc_cryptography/ccc_cryptography.dart';
----
Algorithm ID Quick Reference
------------------------------
These IDs match the ``cipher_constants.dart`` integer constants in the
existing app exactly — no translation layer is needed.
========================= ===== ============================
Algorithm ID Category
========================= ===== ============================
``aesGcm256`` 12 AEAD
``chaCha20Poly1305`` 13 AEAD
``xChaCha20Poly1305`` 14 AEAD
``ascon128a`` 15 AEAD
``sha256`` (KDF) 1 KDF (HKDF-SHA256)
``sha384`` (KDF) 2 KDF (HKDF-SHA384)
``sha512`` (KDF) 3 KDF (HKDF-SHA512)
``blake2b512`` (KDF) 4 KDF
``hmacSha256`` 30 MAC
``hmacSha512`` 32 MAC
``blake2bMac`` 33 MAC
``sha256`` (Hash) 40 Hash
``sha384`` (Hash) 41 Hash
``sha512`` (Hash) 42 Hash
``blake2b512`` (Hash) 43 Hash
``sha3_256`` 44 Hash
``x25519`` 50 KEM
``x448`` 51 KEM
``mlKem768`` 52 KEM (deferred)
``mlKem1024`` 53 KEM (deferred)
``classicMcEliece`` 54 KEM (deferred)
========================= ===== ============================
----
Milestone 3 Completion Gate
----------------------------
*All items must be checked before Milestone 3 is considered complete.*
* ``[ ]`` Plugin added to LetUsMsg ``pubspec.yaml``
* ``[ ]`` ``CccCrypto.init()`` called at app startup
* ``[ ]`` All AEAD crypto stubs replaced (Phase M3-3)
* ``[ ]`` All KDF stubs replaced (Phase M3-4)
* ``[ ]`` All MAC stubs replaced (Phase M3-5)
* ``[ ]`` All Hash stubs replaced (Phase M3-6)
* ``[ ]`` All KEM stubs replaced (Phase M3-7)
* ``[ ]`` Provider catalog surface integrated (Phase M3-8)
* ``[ ]`` Self-test debug UI surface integrated (Phase M3-9)
* ``[ ]`` Exception handling audit complete (Phase M3-10)
* ``[ ]`` End-to-end app tests pass on iOS, Android, macOS (Phase M3-11)
* ``[ ]`` No raw private keys exposed, logged, or persisted
* ``[ ]`` Plugin dep pinned to ``v0.1.0`` git tag (when cut)

2
docs/ccc_fplugin_phases.rst → docs/ccc_rust_milestone2_phases.rst
View File

@ -516,7 +516,7 @@ Known upstream issue:
Phase 6 — Integration Tests & Polish
--------------------------------------
:Status: In Progress
:Status: Not Started
:Depends on: Phase 4, Phase 5
**Goal:** End-to-end validation on real devices/simulators, example

127
docs/ccc_rust_milestone2_session_state_OLD.rst Normal file
View File

@ -0,0 +1,127 @@
=====================================================
CCC Rust Milestone 2 — Session State (Planning)
=====================================================
:Status: Not started
:Date: 2026-02-26
:Repository target: ``ccc_cryptography`` (plugin repo)
:Depends on: ``ccc_rust`` Milestone 1 complete
Related Documents
=================
* Milestone 1 completion record:
``docs/ccc_rust_milestone1.rst``
Overview
========
This document tracks Milestone 2 execution state for Flutter plugin + bridge work.
Milestone 2 begins with Milestone 1 already verified and complete.
Current Gate Preconditions
==========================
* ``[x]`` Milestone 1 verification gate passed.
* ``[x]`` Conformance vectors passed in Rust workspace.
* ``[x]`` Rust target builds validated (iOS + Android).
Milestone 2 Work Checklist
==========================
Phase 1 — Repository + Scaffold
-------------------------------
* ``[ ]`` Create/confirm ``ccc_cryptography`` repository and branch strategy.
* ``[ ]`` Create Flutter plugin scaffold (``pubspec.yaml``, ``ios/``, ``android/``, ``macos/``).
* ``[ ]`` Add Rust bridge crate with ``crate-type = ["cdylib", "staticlib"]``.
* ``[ ]`` Wire dependency on ``ccc_rust`` pinned tag/revision.
Phase 2 — Bridge API Surface
----------------------------
* ``[ ]`` Define DTOs:
* ``CapabilitiesDto``
* ``KemKeyPairDto``
* ``KemEncapDto``
* ``SelfTestDto``
* ``AlgoTestResultDto``
* ``[ ]`` Implement bridge entry points:
* ``ccc_init``
* ``ccc_list_providers``
* ``ccc_capabilities`` / ``ccc_available_algorithms``
* ``ccc_aead_encrypt`` / ``ccc_aead_decrypt``
* ``ccc_kdf_derive``
* ``ccc_mac_compute`` / ``ccc_mac_verify``
* ``ccc_hash``
* ``ccc_kem_generate_keypair``
* ``ccc_kem_encapsulate`` / ``ccc_kem_decapsulate``
* ``ccc_self_test``
Phase 3 — FRB Codegen + Build Integration
-----------------------------------------
* ``[ ]`` Add ``flutter_rust_bridge`` configuration + codegen scripts.
* ``[ ]`` Run FRB codegen and commit generated artifacts.
* ``[ ]`` Verify plugin compiles for iOS.
* ``[ ]`` Verify plugin compiles for Android.
* ``[ ]`` Verify plugin compiles for macOS.
Phase 4 — Dart API Layer
------------------------
* ``[ ]`` Implement ``CccCrypto`` service API wrapper.
* ``[ ]`` Implement ``CccSelfTest`` wrapper.
* ``[ ]`` Implement runtime ``CccProviderCatalog`` population.
* ``[ ]`` Ensure algorithm ID mapping remains 1:1 with Rust discriminants.
Phase 5 — Integration + Validation
----------------------------------
* ``[ ]`` Add integration tests for AEAD roundtrip (at least AES-GCM and ChaCha20).
* ``[ ]`` Add integration tests for KEM keygen/encap/decap flow.
* ``[ ]`` Add integration tests for self-test API.
* ``[ ]`` Run on iOS simulator.
* ``[ ]`` Run on Android emulator/device.
Milestone 2 TODO Queue
======================
Immediate TODOs (next session)
------------------------------
* ``[ ]`` Decide exact Milestone 2 repository location/URL and baseline branch.
* ``[ ]`` Pin ``ccc_rust`` dependency to a reproducible reference (tag or commit hash).
* ``[ ]`` Define FRB module layout and generated file commit policy.
* ``[ ]`` Draft DTO type mapping table (Rust type -> bridge DTO -> Dart model).
Backlog TODOs
-------------
* ``[ ]`` Add CI job matrix for iOS/macOS/Android plugin builds.
* ``[ ]`` Add versioning/release policy for plugin package.
* ``[ ]`` Add troubleshooting notes for NDK/Xcode toolchains.
Milestone 2 Verification Gate
=============================
All of the following must pass before declaring Milestone 2 complete:
* ``[ ]`` FRB bridge API compiles and loads in Flutter plugin.
* ``[ ]`` Generated Dart bindings are committed and reproducible.
* ``[ ]`` ``flutter build ios`` succeeds.
* ``[ ]`` ``flutter build apk`` succeeds.
* ``[ ]`` ``flutter build macos`` succeeds.
* ``[ ]`` Integration test suite passes on iOS simulator.
* ``[ ]`` Integration test suite passes on Android emulator/device.
* ``[ ]`` Plugin package is tagged/released at ``v0.1.0`` (or agreed target version).
Notes
=====
* Milestone 2 is the first place where ``flutter_rust_bridge`` is allowed.
* Milestone 1 Rust workspace remains bridge-free and should not be modified
for Dart/plugin scaffolding.

6
docs/ccc_rust_plan_phases.rst
View File

@ -21,14 +21,10 @@ Three-Milestone Overview
Milestone Repository Status
============= =================================== ============================
**1 (this)** ``ccc_rust`` Complete
**2** ``ccc_cryptography`` In Progress
**2** ``ccc_cryptography`` Not started
**3** ``letusmsg`` (existing app) Not started
============= =================================== ============================
.. note::
Milestone 2 status updated 2026-03-16. Phases 1–5 complete;
Phase 6 in progress (macOS/iOS/Android passing; Linux + Windows deferred).
Milestone 1 Verification Gate is now passing.
Milestone 2 may begin when scheduled.
Milestone 3 does not start until the Milestone 2 gate passes.

16
pubspec.yaml
View File

@ -1,7 +1,7 @@
name: ccc_cryptography
description: "Copius Cipher Chain Cryptography"
publish_to: 'none'
version: 0.2.0
version: 0.0.1
environment:
sdk: ^3.10.1
@ -10,18 +10,18 @@ environment:
dependencies:
flutter:
sdk: flutter
plugin_platform_interface: ^2.1.8
flutter_rust_bridge: 2.11.1 # pinned to match codegen version in frb_generated.dart, 2.12.0 is not compatible at this time
freezed_annotation: ^3.1.0
meta: ^1.17.0 #1.18.2 latest not allowed because of compatibility issues with other dependencies
plugin_platform_interface: ^2.0.2
flutter_rust_bridge: 2.11.1
freezed_annotation: ^2.4.1
meta: ^1.11.0
dev_dependencies:
ffi: ^2.2.0
ffi: ^2.1.3
flutter_test:
sdk: flutter
flutter_lints: ^6.0.0
build_runner: ^2.13.1
freezed: ^3.2.5
build_runner: ^2.4.8
freezed: ^2.5.2
integration_test:
sdk: flutter

2
rust/.cargo/config.toml
View File

@ -1,2 +0,0 @@
[net]
git-fetch-with-cli = true

1020
rust/Cargo.lock generated
View File

File diff suppressed because it is too large Load Diff

14
rust/Cargo.toml
View File

@ -1,18 +1,16 @@
[package]
name = "ccc_cryptography"
version = "0.2.0"
version = "0.1.0"
edition = "2021"
[lib]
crate-type = ["cdylib", "staticlib"]
[dependencies]
ccc-crypto-core = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", branch = "trunk" }
ccc-crypto-wolfssl = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", branch = "trunk" }
# For local development, you can uncomment the following lines and comment out the git dependencies above:
# ccc-crypto-core = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-core" }
# ccc-crypto-wolfssl = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-wolfssl" }
# Local dev paths — switch to git deps for CI/release:
# ccc-crypto-core = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" }
# ccc-crypto-wolfssl = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" }
ccc-crypto-core = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-core" }
ccc-crypto-wolfssl = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-wolfssl" }
flutter_rust_bridge = "=2.11.1"
log = "0.4"