keep-mobile: add Rust-side integrity verification over the foreign SecureStorage

[kwsantiago]

Problem

The SecureStorage trait (keep-mobile/src/storage.rs) is #[uniffi::export(with_foreign)], so mobile platforms provide the implementation. The Rust core trusts that implementation to preserve integrity: there is no Rust-side integrity check (MAC/HMAC) over stored blobs. A buggy or compromised foreign implementation could return different data than was stored, silently corrupt FROST share material, or fail to protect it, and the Rust core would not detect it.

Mitigating context

The Android implementation is Keystore-backed AES-GCM (AEAD), so stored data already has authenticated-encryption integrity at the platform layer. This is therefore defense-in-depth against a broken/compromised foreign impl, not a plaintext-integrity gap today.

Design decision needed

1. Where the integrity key lives — it must be in a separate keystore slot; if it lives in the same SecureStorage, a compromised store compromises it too.
2. Format + migration — adding a Rust-side MAC changes the stored blob format and requires migrating existing FROST share blobs. This is highly security-critical (a bug risks bricking access to shares), so it needs a versioned, backward-compatible migration.
3. Whether it is worth it over the platform AEAD already present.

Acceptance criteria

• Rust core verifies an integrity tag over stored share material on load, keyed independently of the foreign store.
• Backward-compatible with existing blobs (no data loss on upgrade).

[kwsantiago]

Status update after investigating the trust model; re-scoping p0 → p2.

Verified: keep-mobile stores FROST shares as raw JSON through the foreign SecureStorage (Android Keystore / iOS Keychain), delegating confidentiality and integrity to the platform by design. There is no Rust-held secret independent of that store (biometric-gated Keystore model, no vault password at the Rust layer).

The originally-proposed fix (Rust-side HMAC) is not viable against a malicious/replaced storage impl: any HMAC key would have to live in that same foreign store, so a compromised store holds the key too and can forge the MAC. A Rust-layer MAC therefore adds no protection against the stated threat.

What was achievable and is shipped (#814): a load-time cryptographic identity check. load_share_package now derives the group key from the share's public-key package (via SharePackage::verified_group_pubkey, not the forgeable metadata field) and fails closed unless it matches the storage key the share was requested under. This detects a store that returns a different or corrupted share, one of the concrete concerns here ("return different shares than stored"), without needing a Rust-held secret.

Residuals (rest on the platform-storage contract, by design): confidentiality, tamper of a same-identity share, rollback to an old-but-valid share, and the non-signing metadata/display load paths (get_active_share_metadata / load_stored_share_info) which don't yet apply the identity check.

Disposition: the load-time identity check closes the achievable defense; the remaining items are the accepted platform-trust boundary plus minor display-path coverage, tracked under the keep-mobile hardening backlog (#792).

[kwsantiago]

Started (PR #871). Research confirmed keep-mobile holds no app-level key of its own, so the integrity MAC key must come from the platform Keystore/Keychain — mirroring the shipped nip55_audit keyed-HMAC pattern (the platform layer owns storage + the hardware key and calls Rust primitives to MAC/verify).

PR #871 ships the Rust-verifiable core: UniFFI-exported storage_entry_mac/storage_verify_entry_mac (per-entry HMAC, TLV-framed, key-bound, fail-closed, constant-time) and storage_tip_mac/storage_verify_tip_mac (whole-set MAC binding count + all entries, so drop/add/tamper is caught and a strip-the-MAC downgrade is defeated because the tip lives in the Keystore slot the KV store cannot reach). 8 deterministic tamper-detection tests. Non-breaking (no SecureStorage trait change — keep-android keeps building).

Follow-up (cross-repo, emulator-gated): provision the Keystore HMAC alias + tip slot and wire these into AndroidKeystoreStorage/iOS Keychain load-store paths, with the TOFU-seed migration (mirroring keep-android AuditAnchor). Two residuals for maintainer sign-off: a fully-malicious in-process foreign impl is outside any Rust-only boundary, and the tip has no monotonic epoch so a full (set, tip) rollback still validates (mobile TEEs lack a monotonic counter; same documented limitation as the audit chain).

[kwsantiago]

Evidence bearing on the third design question, "whether it is worth it over the platform AEAD already present". Recent work on the Android storage wrapper turned that from a judgement call into something with concrete failure cases, so recording them here rather than leaving the question open on intuition.

The mitigating context in the description holds that the Android side is Keystore-backed AES-GCM, so stored data already has authenticated-encryption integrity. That is true of each value in isolation, and it is not sufficient, for two reasons found while hardening that layer.

Authenticated encryption binds the value, not which key it belongs to. Values are encrypted with no associated data, so nothing ties a ciphertext to the name it is stored under. Any surviving ciphertext is transplantable between entries and replayable across time: an attacker able to write to the app's data directory can copy one entry's ciphertext onto another entry's name, and every authentication check still passes because the value itself is intact and correctly signed. No forgery is required. This needs root, a debuggable build, or physical access, and backups are disabled, but it is exactly the class the acceptance criteria describe as "returns different data than was stored", and the platform AEAD does not detect it.

The foreign implementation demonstrably could return data other than what was stored. Over the past few changes this layer was found to swallow write failures and report success, to return the default value on a decrypt or key-derivation failure so an unreadable entry was indistinguishable from an absent one, and to strand entries under a previous key-derivation epoch where they became invisible to lookup. Each of those has since been fixed, but they were live, and they are the shape of misbehaviour a Rust-side tag would have caught generically rather than one fix at a time.

On the second design question, migration: note that share material and the ordinary settings live in the same wrapper. keep_secure_prefs holds the share blob and its metadata alongside everything else, so any change to the stored format has to migrate share blobs, which is the bricking risk already flagged. That argues for the Rust-side tag being versioned and additive, verified on load but written alongside the existing format until every blob carries one, rather than a format change to the value encoding.

Not proposing to start this without a decision, given the blast radius. The narrower alternative, binding the key name into the value encryption on the Android side, addresses the transplant case but carries the same migration risk over share blobs and protects only this one client.