diff --git a/docs/ccc_fplugin_build_linux.rst b/docs/ccc_fplugin_build_linux.rst new file mode 100644 index 0000000..d13d570 --- /dev/null +++ b/docs/ccc_fplugin_build_linux.rst @@ -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//src/lum_ccc_rust/crates/ccc-crypto-core" } + ccc-crypto-wolfssl = { path = "/home//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. diff --git a/docs/ccc_rust_app_integration_phases.rst b/docs/ccc_rust_app_integration_phases.rst new file mode 100644 index 0000000..6411a10 --- /dev/null +++ b/docs/ccc_rust_app_integration_phases.rst @@ -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 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 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 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 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 CccCrypto.computeMac({ + required CccMacAlgorithm algorithm, + required Uint8List key, + required Uint8List data, + }); + + // Returns true if valid, false otherwise — never throws for tampered data + Future 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 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 CccCrypto.kemGenerateKeypair({ + required CccKemAlgorithm algorithm, + }); + // CccKemKeyPair { Uint8List publicKey; Uint8List privateKey; } + + // Encapsulation — sender uses recipient's public key + Future CccCrypto.kemEncapsulate({ + required CccKemAlgorithm algorithm, + required Uint8List publicKey, + }); + // CccKemEncapResult { Uint8List ciphertext; Uint8List sharedSecret; } + + // Decapsulation — recipient recovers shared secret + Future 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 + 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 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 + 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)