Implement Android Keystore protection for SSH unlock

Author: moha-bekh

README.md

@@ -40,7 +40,8 @@ Implemented, with local/generated-provider evidence:
 - Snapshot creation/restore, deletion and retained-definition recreation.
 - Durable operations, idempotent requests and read-only restart recovery.
 - SSH host trust, encrypted application identity and an interactive native terminal.
-- Optional Linux system key store for the application identity unlock passphrase.
+- Optional Linux Secret Service and Android Keystore protection for the identity
+  unlock passphrase (Android runtime acceptance pending).
 - API/worker execution of declared packages and an optional final disk-only snapshot.
 
 The package/final-snapshot workflow passes all create/recreate combinations against
@@ -71,9 +72,12 @@ target. Start with the [template preparation guide](docs/debian-template.md) and
 
 The optional Linux Secret Service controls pass isolated real-daemon/native SSH,
 browser and joined Linux WebView/production IPC/terminal checks. The private key
-remains encrypted in application storage; macOS Keychain/Android Keystore and
-normal deployment/platform acceptance remain open. Current delivery files predate these new vault commands. See
-[the decision and limits](docs/decisions/0087-linux-system-identity-unlock.md).
+remains encrypted in application storage. Android Keystore now compiles/packages
+for both ABIs, with scoped ciphertext and JNI checks; actual device behavior, macOS
+Keychain and normal deployment/platform acceptance remain open. Current Android
+APKs include the vault commands but have not been executed. See
+[Linux decision](docs/decisions/0087-linux-system-identity-unlock.md) and
+[Android decision and limits](docs/decisions/0088-android-keystore-identity-unlock.md).
 
 ## Install
 

STATE.md

@@ -1,28 +1,29 @@
 # VMAnyware — current state
 
-Updated: 2026-10-21. Historical evidence and decisions are in Git and docs.
+Updated: 2026-10-22. Historical evidence and decisions are in Git and docs.
 
 Naming note: historical lab resource identifiers below are normalized to the
 current VMAnyware name. External resources were not renamed; use VMIDs and
 ignored local lab records to verify actual identifiers before operations.
 
 ## Latest resume point
 
-ADR 0087 adds optional Linux Secret Service storage of the application SSH unlock
-passphrase: explicit save/unlock/forget, scoped lookup and SSH source selection.
-The private SSH key stays encrypted in the existing app file. Eighteen affected
-native SSH checks, a focused namespace check, two isolated real-daemon/vault/SSH
-cases, React/browser journeys and joined Linux WebView/production IPC/vault/terminal
-acceptance pass. No personal vault is accessed.
-Clippy strict exposes one pre-existing unrelated argument-count lint; the client
-check passes with only that lint allowed. New GUI evidence is isolated Linux
-acceptance; device/normal-deployment gates stay open.
-Next: Android Keystore implementation using the existing native platform bridge,
-with source/compilation/device evidence distinguished. Current server/Android
-delivery artifacts include ADR 0086 progress
-but predate this new vault IPC/UI. Android runtime, real Proxmox, other OS stores,
-Windows/iOS parity, host deployment and local-provider acceptance remain open.
-The previous source/delivery checkpoint is retained in the dated entries below.
+User-requested session checkpoint: finish this slice, commit/push and stop here.
+ADR 0088 implements Android Keystore wrapping for the optional application SSH
+unlock secret. ARM64/x86_64 Rust, Kotlin/JNI and both signed debug APKs compile/package;
+helper presence, native hashes, descriptors, initializer exports and existing
+manifest constraints pass. A focused scope test and affected browser journey pass.
+This is compiled/packaged implementation, not actual Android runtime acceptance.
+The SSH private key stays in its passphrase-encrypted app file. Linux Secret Service
+already has joined native UI/vault/SSH acceptance (ADR 0087). macOS Keychain,
+Windows/iOS parity, exact APK/device/Keystore behavior, real Proxmox and deployment
+acceptance remain open. No full-roadmap completion or audited percentage is claimed.
+
+Resume next with an explicitly approved owned Android runtime: save/read/restart,
+tamper/wrong-scope and missing/invalidated wrapping-key refusal, forget/read refusal,
+then host-trust-first SSH/PTY using the system source. Do not start a VM, AVD or
+personal credential operation just because source/build checks pass. All task
+processes are terminal; no pending build or test needs restarting.
 
 
 Latest source slice: production HTTP admission now has a global burst-120,
@@ -6839,3 +6840,65 @@ and initializes the platform verifier before Tauri starts. Add a narrowly scoped
 keystore bridge alongside that path without altering TLS verification or
 regenerating the reviewed Android project. Use the existing owned build toolchain;
 source/compilation never substitutes for explicit device/AVD runtime acceptance.
+
+
+## 2026-10-22 — Android Keystore identity unlock, session checkpoint (ADR 0088)
+
+Scope/acceptance: Android implementation for the same explicit save/use/forget
+identity commands, key/directory scope binding, fixed failures/no silent fallback,
+source/native/Kotlin compilation and package checks. Implemented a narrow JNI
+helper retained via application context and initialized alongside unchanged TLS
+verification. Startup does not open a vault. Rust computes a purpose/directory/
+fingerprint SHA-256 scope, verifies the existing encrypted key/passphrase before
+save, confirms readback and retains shared busy/host/owner/session gates. Kotlin
+accepts only scoped aliases, wraps with AndroidKeyStore AES-256-GCM, binds scope as
+AAD and stores only bounded versioned ciphertext in private SharedPreferences.
+Existing backup/device-transfer exclusions cover that data. Missing/invalidated
+keys behind ciphertext cannot be silently regenerated. Explicit forget removes
+only the scoped key/ciphertext, preserving the SSH key. Fixed native exceptions
+never return Java/provider errors or plaintext to the renderer. UI labels now
+support Linux/Android and preserve separate unchecked consent. No new dependency,
+IPC command (82 total), network permission or automatic migration is added.
+
+Verification: `make package-android` passes with the existing owned SDK/JDK/NDK
+(`.lab/android-toolchain/keystore-package.log`): frontend/typecheck, ARM64/x86_64
+native compilation, Kotlin/Gradle, both signed debug APKs and signature/version/
+ABI/manifest/exact native-library checks. Initial compile errors (inner doc position
+and typed JNI byte-array signatures) were corrected; final compile/package handles
+exited successfully. An additional package check requires IdentityVault in DEX
+(`keystore-content-check.log` in that directory). Compiled Kotlin JNI descriptors
+match save/read/forget, and both new vault and unchanged TLS initializer symbols
+are exported (`keystore-jni-descriptors.log`, `keystore-jni-exports.log`).
+
+The focused Linux-host Android-scope test passes
+(`.lab/native-deps/android-keystore-scope-test.log`): stable lowercase 64-hex scope,
+changed directory and changed public identity produce independent scopes. It does
+not emulate Android cryptography. The affected React/Firefox simulated-IPC journey
+passes (`.lab/android-keystore-ui-check.log`), including explicit vault operations,
+input/consent clearing, scoped SSH selection, no automatic connection and private
+error suppression. Scoped rustfmt, Python syntax, IPC-manifest consistency and diff
+review pass. No unrelated server/Linux native suite or Clippy reran for Android
+conditional branches/UI copy changes.
+
+Current local test artifacts (`.lab/packages/android/`):
+- ARM64 SHA-256 `5a6554b8e32c54d39321fb99c1d2b274be73ca0c6a75397c067793d7277d2166`, 485011736 bytes.
+- x86_64 SHA-256 `0aa58facc6a8d659e76f64cdcc738c44ac2072ddac55c3429c9643d3a072ab47`, 492984213 bytes.
+- `releaseCandidate=false`, `runtimeValidatedForTheseApks=false`; updated INSTALL
+  instructions match repository documentation. No device/AVD was started/installed,
+  personal credential/key store touched, real VM contacted or host service changed.
+
+Limits: no actual Keystore save/decrypt, process/activity restart, ciphertext tamper,
+wrapping-key invalidation/loss, OEM transfer behavior, physical security-level or
+Android system-source SSH/PTY runtime evidence yet. No biometric/StrongBox claim:
+the wrapping key has no user-authentication requirement, and a compromised app can
+use it. The SSH key remains encrypted application storage. Forgetting saved unlock
+does not revoke an already selected key/session. Source compilation cannot close
+platform/phase acceptance. Existing Linux acceptance remains independently recorded.
+
+Next task after resuming: use an approved owned Android target and current exact APK
+for the acceptance sequence above; keep package provenance and no silent fallback.
+If no runtime target is authorized, prepare its opt-in fixture without launching it,
+then continue other source/platform work. User asked to stop at this checkpoint;
+do not start another slice in this session. Website remains at the accepted Linux
+checkpoint `11dcb6c`; Android source/package evidence is now in this repo and should
+be synchronized on the next publication pass, without claiming device validation.

apps/client/src-tauri/gen/android/app/proguard-rules.pro

@@ -25,3 +25,6 @@
 -keepclassmembers class dev.vmanyware.client.MainActivity {
     native <methods>;
 }
+
+# Fixed native identity bridge methods must retain their JNI names.
+-keep class dev.vmanyware.client.IdentityVault { *; }

apps/client/src-tauri/gen/android/app/src/main/java/dev/vmanyware/client/IdentityVault.kt

@@ -0,0 +1,78 @@
+package dev.vmanyware.client
+
+import android.content.Context
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+// Reached only by the fixed native identity commands, never by WebView Javascript.
+// Retain application context; constructing this helper does not open the vault.
+class IdentityVault(context: Context) {
+  private val context = context.applicationContext
+  private fun preferences() = context.getSharedPreferences("ssh-unlock-v1", Context.MODE_PRIVATE)
+  private fun alias(scope: String): String {
+    require(scope.matches(Regex("[0-9a-f]{64}")))
+    return "dev.vmanyware.client.ssh-unlock.v1.$scope"
+  }
+  private fun store() = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
+  private fun key(store: KeyStore, name: String): SecretKey =
+    store.getKey(name, null) as? SecretKey ?: error("Unlock key unavailable")
+
+  @Synchronized
+  fun save(scope: String, secret: ByteArray) {
+    try {
+      require(secret.isNotEmpty() && secret.size <= 1024)
+      val name = alias(scope)
+      val preferences = preferences()
+      val store = store()
+      // Never silently replace an invalidated/missing key behind retained ciphertext.
+      check(!preferences.contains(scope) || store.containsAlias(name))
+      if (!store.containsAlias(name)) {
+        KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore").apply {
+          init(KeyGenParameterSpec.Builder(name, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+            .setKeySize(256).setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+            .setRandomizedEncryptionRequired(true).setUserAuthenticationRequired(false).build())
+          generateKey()
+        }
+      }
+      val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+      cipher.init(Cipher.ENCRYPT_MODE, key(store, name))
+      cipher.updateAAD(scope.toByteArray(Charsets.US_ASCII))
+      check(cipher.iv.size == 12)
+      val encoded = Base64.encodeToString(byteArrayOf(1) + cipher.iv + cipher.doFinal(secret), Base64.NO_WRAP)
+      check(preferences.edit().putString(scope, encoded).commit())
+    } finally {
+      secret.fill(0)
+    }
+  }
+
+  @Synchronized
+  fun read(scope: String): ByteArray {
+    val name = alias(scope)
+    val encoded = preferences().getString(scope, null) ?: error("Saved unlock secret absent")
+    require(encoded.length <= 1500)
+    val bytes = Base64.decode(encoded, Base64.NO_WRAP)
+    require(bytes.size in 30..1053 && bytes[0] == 1.toByte())
+    val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+    cipher.init(Cipher.DECRYPT_MODE, key(store(), name), GCMParameterSpec(128, bytes.copyOfRange(1, 13)))
+    cipher.updateAAD(scope.toByteArray(Charsets.US_ASCII))
+    val secret = cipher.doFinal(bytes, 13, bytes.size - 13)
+    if (secret.isEmpty() || secret.size > 1024) { secret.fill(0); error("Invalid unlock secret") }
+    return secret
+  }
+
+  @Synchronized
+  fun forget(scope: String) {
+    val name = alias(scope)
+    val store = store()
+    if (store.containsAlias(name)) store.deleteEntry(name)
+    check(!store.containsAlias(name))
+    check(preferences().edit().remove(scope).commit())
+  }
+}

apps/client/src-tauri/gen/android/app/src/main/java/dev/vmanyware/client/MainActivity.kt

@@ -13,10 +13,12 @@ import androidx.core.view.WindowInsetsCompat
 
 class MainActivity : TauriActivity() {
   private external fun initializePlatformVerifier(context: Context)
+  private external fun initializeIdentityVault(helper: IdentityVault)
 
   override fun onCreate(savedInstanceState: Bundle?) {
     System.loadLibrary("vmanyware_client_lib")
     initializePlatformVerifier(applicationContext)
+    initializeIdentityVault(IdentityVault(applicationContext))
     enableEdgeToEdge(
       statusBarStyle = SystemBarStyle.dark(Color.TRANSPARENT),
       navigationBarStyle = SystemBarStyle.dark(Color.TRANSPARENT)

apps/client/src-tauri/src/android_identity.rs

@@ -0,0 +1,96 @@
+//! Narrow application-context JNI bridge. Initialization does not access secrets.
+use jni::{
+    errors::ThrowRuntimeExAndDefault,
+    jni_mangle, jni_sig, jni_str,
+    objects::{Global, JByteArray, JObject, JValue},
+    EnvUnowned, JavaVM,
+};
+use std::sync::OnceLock;
+use zeroize::Zeroizing;
+struct Bridge {
+    vm: JavaVM,
+    helper: Global<JObject<'static>>,
+}
+static BRIDGE: OnceLock<Bridge> = OnceLock::new();
+const ERROR: &str = "Android system key store unavailable or unable to open this identity. Use the passphrase or explicitly forget the saved secret before saving again.";
+#[allow(non_snake_case)]
+#[jni_mangle("dev.vmanyware.client.MainActivity")]
+pub fn initializeIdentityVault<'caller>(
+    mut env: EnvUnowned<'caller>,
+    _activity: JObject<'caller>,
+    helper: JObject<'caller>,
+) {
+    env.with_env(|env| -> jni::errors::Result<()> {
+        if BRIDGE.get().is_none() {
+            let bridge = Bridge {
+                vm: env.get_java_vm()?,
+                helper: env.new_global_ref(helper)?,
+            };
+            let _ = BRIDGE.set(bridge);
+        }
+        Ok(())
+    })
+    .resolve::<ThrowRuntimeExAndDefault>();
+}
+pub(crate) fn save(scope: &str, secret: &[u8]) -> Result<(), String> {
+    let bridge = BRIDGE.get().ok_or(ERROR)?;
+    bridge
+        .vm
+        .attach_current_thread_for_scope(|env| -> jni::errors::Result<()> {
+            let scope = env.new_string(scope)?;
+            let bytes = env.byte_array_from_slice(secret)?;
+            let result = env.call_method(
+                &bridge.helper,
+                jni_str!("save"),
+                jni_sig!("(Ljava/lang/String;[B)V"),
+                &[
+                    JValue::Object(scope.as_ref()),
+                    JValue::Object(bytes.as_ref()),
+                ],
+            );
+            // Java clears this argument in finally, including encryption/storage failure.
+            result?.v()
+        })
+        .map_err(|_| ERROR.into())
+}
+pub(crate) fn read(scope: &str) -> Result<Zeroizing<Vec<u8>>, String> {
+    let bridge = BRIDGE.get().ok_or(ERROR)?;
+    bridge
+        .vm
+        .attach_current_thread_for_scope(|env| -> jni::errors::Result<_> {
+            let scope = env.new_string(scope)?;
+            let object = env
+                .call_method(
+                    &bridge.helper,
+                    jni_str!("read"),
+                    jni_sig!("(Ljava/lang/String;)[B"),
+                    &[JValue::Object(scope.as_ref())],
+                )?
+                .l()?;
+            let bytes = env.cast_local::<JByteArray>(object)?;
+            let len = bytes.len(env)?;
+            if len > 1024 {
+                return Err(jni::errors::Error::NullPtr("Invalid unlock secret"));
+            }
+            let result = Zeroizing::new(env.convert_byte_array(&bytes)?);
+            bytes.set_region(env, 0, &[0i8; 1024][..len])?;
+            Ok(result)
+        })
+        .map_err(|_| ERROR.into())
+}
+pub(crate) fn forget(scope: &str) -> Result<(), String> {
+    let bridge = BRIDGE.get().ok_or(ERROR)?;
+    bridge
+        .vm
+        .attach_current_thread_for_scope(|env| -> jni::errors::Result<()> {
+            let scope = env.new_string(scope)?;
+            env.call_method(
+                &bridge.helper,
+                jni_str!("forget"),
+                jni_sig!("(Ljava/lang/String;)V"),
+                &[JValue::Object(scope.as_ref())],
+            )?
+            .v()
+        })
+        .map_err(|_| ERROR.into())
+}

apps/client/src-tauri/src/lib.rs

@@ -1,4 +1,6 @@
 #[cfg(target_os = "android")]
+mod android_identity;
+#[cfg(target_os = "android")]
 mod android_tls;
 mod control_plane;
 mod remote_connection;

apps/client/src-tauri/src/ssh/agent.rs

@@ -217,7 +217,7 @@ impl AgentManager {
         self.list_application_inner(owner, host, port, username, Some(password))
             .await
     }
-    #[cfg(target_os = "linux")]
+    #[cfg(any(target_os = "linux", target_os = "android"))]
     pub async fn list_system_application(
         &self,
         owner: &str,
@@ -261,9 +261,9 @@ impl AgentManager {
                 ensure_active(&unlocking)?;
                 match password {
                     Some(password) => store.signing_key(password),
-                    #[cfg(target_os = "linux")]
+                    #[cfg(any(target_os = "linux", target_os = "android"))]
                     None => store.signing_system(),
-                    #[cfg(not(target_os = "linux"))]
+                    #[cfg(not(any(target_os = "linux", target_os = "android")))]
                     None => {
                         Err("System SSH identity storage is unavailable on this platform".into())
                     }

apps/client/src-tauri/src/ssh/identity.rs

@@ -1,4 +1,7 @@
 //! Fixed app-owned encrypted Ed25519 identity. Never imports user key files.
+#[cfg(any(target_os = "android", all(test, target_os = "linux")))]
+#[path = "identity_android.rs"]
+mod android;
 #[cfg(target_os = "linux")]
 #[path = "identity_vault.rs"]
 pub(super) mod vault;