Add KeystorePasswordTransformer for Android Keystore-backed encryption

jkmassel · claude · jkmassel · commit a8684c9d68a2 · 2026-02-25T16:39:33.000-07:00
Hardware-backed PasswordTransformer for Android using the Android
Keystore with AES-256-GCM. Prefers StrongBox (API 28+) and falls
back to TEE. Exposes isHardwareBacked property for callers to check
the security level.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/native/kotlin/api/android/src/androidTest/kotlin/rs/wordpress/api/android/KeystorePasswordTransformerTest.kt b/native/kotlin/api/android/src/androidTest/kotlin/rs/wordpress/api/android/KeystorePasswordTransformerTest.kt
@@ -0,0 +1,153 @@
+package rs.wordpress.api.android
+
+import android.util.Base64
+import org.junit.After
+import org.junit.Test
+import uniffi.wp_mobile.PasswordTransformerException
+import java.security.KeyStore
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertNotEquals
+import kotlin.test.assertTrue
+
+class KeystorePasswordTransformerTest {
+
+    private val testNames = mutableListOf<String>()
+
+    private fun createTransformer(
+        applicationName: String = "test-key-${System.nanoTime()}"
+    ): KeystorePasswordTransformer {
+        testNames.add(applicationName)
+        return KeystorePasswordTransformer(applicationName)
+    }
+
+    @After
+    fun tearDown() {
+        val keyStore = KeyStore.getInstance("AndroidKeyStore")
+        keyStore.load(null)
+        for (name in testNames) {
+            if (keyStore.containsAlias(name)) {
+                keyStore.deleteEntry(name)
+            }
+        }
+    }
+
+    @Test
+    fun roundTripEncryptDecrypt() {
+        val transformer = createTransformer()
+        val plaintext = "my-secret-password"
+
+        val encrypted = transformer.encrypt(plaintext)
+        val decrypted = transformer.decrypt(encrypted)
+
+        assertEquals(plaintext, decrypted)
+    }
+
+    @Test
+    fun encryptedOutputDiffersFromPlaintext() {
+        val transformer = createTransformer()
+        val plaintext = "my-secret-password"
+
+        val encrypted = transformer.encrypt(plaintext)
+
+        assertNotEquals(plaintext, encrypted)
+    }
+
+    @Test
+    fun samePlaintextProducesDifferentCiphertext() {
+        val transformer = createTransformer()
+        val plaintext = "my-secret-password"
+
+        val encrypted1 = transformer.encrypt(plaintext)
+        val encrypted2 = transformer.encrypt(plaintext)
+
+        assertNotEquals(encrypted1, encrypted2)
+    }
+
+    @Test
+    fun emptyStringRoundTrip() {
+        val transformer = createTransformer()
+
+        val encrypted = transformer.encrypt("")
+        val decrypted = transformer.decrypt(encrypted)
+
+        assertEquals("", decrypted)
+    }
+
+    @Test
+    fun unicodeRoundTrip() {
+        val transformer = createTransformer()
+        val plaintext = "p\u00e4ssw\u00f6rd-\u2603-\ud83d\udd11-\u4f60\u597d"
+
+        val encrypted = transformer.encrypt(plaintext)
+        val decrypted = transformer.decrypt(encrypted)
+
+        assertEquals(plaintext, decrypted)
+    }
+
+    @Test
+    fun longPasswordRoundTrip() {
+        val transformer = createTransformer()
+        val plaintext = "a".repeat(10_000)
+
+        val encrypted = transformer.encrypt(plaintext)
+        val decrypted = transformer.decrypt(encrypted)
+
+        assertEquals(plaintext, decrypted)
+    }
+
+    @Test
+    fun wrongKeyAliasFailsToDecrypt() {
+        val transformer1 = createTransformer()
+        val transformer2 = createTransformer()
+
+        val encrypted = transformer1.encrypt("secret")
+
+        assertFailsWith<PasswordTransformerException.DecryptionFailed> {
+            transformer2.decrypt(encrypted)
+        }
+    }
+
+    @Test
+    fun isHardwareBackedReturnsBooleanWithoutCrashing() {
+        val transformer = createTransformer()
+
+        // Just verify it returns without throwing — actual value depends on device
+        val result = transformer.isHardwareBacked
+        assertTrue(result || !result)
+    }
+
+    @Test
+    fun reusingNameLoadsExistingKey() {
+        val name = "reuse-test-${System.nanoTime()}"
+        testNames.add(name)
+
+        val transformer1 = KeystorePasswordTransformer(name)
+        val encrypted = transformer1.encrypt("secret")
+
+        val transformer2 = KeystorePasswordTransformer(name)
+        val decrypted = transformer2.decrypt(encrypted)
+
+        assertEquals("secret", decrypted)
+    }
+
+    @Test
+    fun decryptInvalidBase64Fails() {
+        val transformer = createTransformer()
+
+        assertFailsWith<PasswordTransformerException.DecryptionFailed> {
+            transformer.decrypt("not-valid-base64!!!")
+        }
+    }
+
+    @Test
+    fun decryptTruncatedCiphertextFails() {
+        val transformer = createTransformer()
+
+        val tooShort = Base64.encodeToString(ByteArray(10), Base64.NO_WRAP)
+
+        assertFailsWith<PasswordTransformerException.DecryptionFailed> {
+            transformer.decrypt(tooShort)
+        }
+    }
+}
diff --git a/native/kotlin/api/android/src/main/kotlin/rs/wordpress/api/android/KeystorePasswordTransformer.kt b/native/kotlin/api/android/src/main/kotlin/rs/wordpress/api/android/KeystorePasswordTransformer.kt
@@ -0,0 +1,166 @@
+package rs.wordpress.api.android
+
+import android.os.Build
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyInfo
+import android.security.keystore.KeyProperties
+import android.security.keystore.StrongBoxUnavailableException
+import android.util.Base64
+import uniffi.wp_mobile.PasswordTransformer
+import uniffi.wp_mobile.PasswordTransformerException
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.SecretKeyFactory
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * A [PasswordTransformer] implementation that uses the Android Keystore for
+ * hardware-backed AES-256-GCM encryption.
+ *
+ * The AES key is generated and stored inside the Android Keystore — it never
+ * leaves the secure hardware (TEE or StrongBox). On devices that support
+ * StrongBox (API 28+), the key is stored in the dedicated secure element for
+ * stronger isolation. Check [isHardwareBacked] to determine the security level.
+ *
+ * Keys are addressed by application name. If a key with the given name already
+ * exists in the Keystore it is loaded; otherwise a new one is created. Use
+ * distinct names to maintain separate keys per account or context.
+ *
+ * ## Usage
+ *
+ * ```kotlin
+ * // Create a transformer with the default application name
+ * val transformer = KeystorePasswordTransformer()
+ *
+ * // Or use a custom name for per-account keys
+ * val transformer = KeystorePasswordTransformer("account-42")
+ *
+ * // Encrypt a password
+ * val encrypted: String = transformer.encrypt("hunter2")
+ *
+ * // Decrypt it back
+ * val decrypted: String = transformer.decrypt(encrypted)
+ * assert(decrypted == "hunter2")
+ *
+ * // Check hardware backing
+ * if (transformer.isHardwareBacked) {
+ *     // Key is in TEE or StrongBox
+ * }
+ * ```
+ */
+class KeystorePasswordTransformer(applicationName: String = DEFAULT_ALIAS) : PasswordTransformer {
+
+    private val key: SecretKey
+
+    val isHardwareBacked: Boolean
+        get() {
+            val factory = SecretKeyFactory.getInstance(key.algorithm, KEYSTORE_PROVIDER)
+            val keyInfo = factory.getKeySpec(key, KeyInfo::class.java) as KeyInfo
+            return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                keyInfo.securityLevel >= KeyProperties.SECURITY_LEVEL_TRUSTED_ENVIRONMENT
+            } else {
+                @Suppress("DEPRECATION")
+                keyInfo.isInsideSecureHardware
+            }
+        }
+
+    init {
+        val keyStore = KeyStore.getInstance(KEYSTORE_PROVIDER)
+        keyStore.load(null)
+
+        key = if (keyStore.containsAlias(applicationName)) {
+            keyStore.getKey(applicationName, null) as SecretKey
+        } else {
+            generateKey(applicationName)
+        }
+    }
+
+    @Suppress("TooGenericExceptionCaught", "SwallowedException")
+    override fun encrypt(password: String): String {
+        try {
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            cipher.init(Cipher.ENCRYPT_MODE, key)
+
+            val iv = cipher.iv
+            val ciphertext = cipher.doFinal(password.toByteArray(Charsets.UTF_8))
+
+            val combined = ByteArray(iv.size + ciphertext.size)
+            System.arraycopy(iv, 0, combined, 0, iv.size)
+            System.arraycopy(ciphertext, 0, combined, iv.size, ciphertext.size)
+
+            return Base64.encodeToString(combined, Base64.NO_WRAP)
+        } catch (e: Exception) {
+            val reason = "${e.javaClass.simpleName}: " +
+                (e.message ?: "Unknown encryption error")
+            throw PasswordTransformerException.EncryptionFailed(reason)
+        }
+    }
+
+    @Suppress("TooGenericExceptionCaught", "SwallowedException")
+    override fun decrypt(password: String): String {
+        try {
+            val combined = Base64.decode(password, Base64.NO_WRAP)
+
+            require(combined.size >= GCM_IV_SIZE + GCM_TAG_SIZE) { "Ciphertext too short" }
+
+            val iv = combined.copyOfRange(0, GCM_IV_SIZE)
+            val ciphertext = combined.copyOfRange(GCM_IV_SIZE, combined.size)
+
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            cipher.init(Cipher.DECRYPT_MODE, key, GCMParameterSpec(GCM_TAG_SIZE_BITS, iv))
+
+            val plaintext = cipher.doFinal(ciphertext)
+            return String(plaintext, Charsets.UTF_8)
+        } catch (e: PasswordTransformerException) {
+            throw e
+        } catch (e: Exception) {
+            val reason = "${e.javaClass.simpleName}: " +
+                (e.message ?: "Unknown decryption error")
+            throw PasswordTransformerException.DecryptionFailed(reason)
+        }
+    }
+
+    companion object {
+        private const val DEFAULT_ALIAS = "wordpress-rs-password-transformer"
+        private const val KEYSTORE_PROVIDER = "AndroidKeyStore"
+        private const val TRANSFORMATION = "AES/GCM/NoPadding"
+        private const val GCM_IV_SIZE = 12
+        private const val GCM_TAG_SIZE_BITS = 128
+        private const val GCM_TAG_SIZE = GCM_TAG_SIZE_BITS / 8
+        private const val AES_KEY_SIZE = 256
+
+        private fun generateKey(applicationName: String): SecretKey {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+                try {
+                    return generateKeyWithSpec(applicationName, strongBox = true)
+                } catch (_: StrongBoxUnavailableException) {
+                    // StrongBox not available on this device, fall back to TEE
+                }
+            }
+            return generateKeyWithSpec(applicationName, strongBox = false)
+        }
+
+        private fun generateKeyWithSpec(applicationName: String, strongBox: Boolean): SecretKey {
+            val builder = KeyGenParameterSpec.Builder(
+                applicationName,
+                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+            )
+                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                .setKeySize(AES_KEY_SIZE)
+
+            if (strongBox && Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+                builder.setIsStrongBoxBacked(true)
+            }
+
+            val keyGenerator = KeyGenerator.getInstance(
+                KeyProperties.KEY_ALGORITHM_AES,
+                KEYSTORE_PROVIDER
+            )
+            keyGenerator.init(builder.build())
+            return keyGenerator.generateKey()
+        }
+    }
+}
