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