MOD: more docs for phases and progress
This commit is contained in:
JohnE
parent
2576080ed1
commit
f9b9dbe6a0
|
|
@ -0,0 +1,483 @@
|
||||||
|
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.
|
||||||
|
|
@ -0,0 +1,593 @@
|
||||||
|
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)
|
||||||
Loading…
Reference in New Issue