{"id":167,"date":"2026-09-16T09:00:00","date_gmt":"2026-09-16T07:00:00","guid":{"rendered":"https:\/\/grindloop.io\/blog\/?p=167"},"modified":"2026-09-27T01:18:40","modified_gmt":"2026-09-26T23:18:40","slug":"encryptedsharedpreferences-keypermanentlyinvalidatedexception","status":"publish","type":"post","link":"https:\/\/grindloop.ai\/blog\/encryptedsharedpreferences-keypermanentlyinvalidatedexception\/","title":{"rendered":"Why EncryptedSharedPreferences Throws KeyPermanentlyInvalidatedException After a New Fingerprint"},"content":{"rendered":"
\n

An app stores a login token encrypted with a biometric-bound Keystore key. Everything works until a user adds a new fingerprint. On the next launch, the app crashes in onResume()<\/code> with a KeyPermanentlyInvalidatedException<\/code> from cipher.init()<\/code>. A teammate adds a try<\/code>\/catch<\/code>, and the crash stops. But the user still can’t sign in with biometrics. What’s wrong?<\/p>\n<\/blockquote>\n

class BiometricTokenVault(context: Context) {\n\n    private val keyStore = KeyStore.getInstance(ANDROID_KEYSTORE).apply { load(null) }\n\n    private val prefs: SharedPreferences by lazy {\n        val masterKey = MasterKey.Builder(context)\n            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)\n            .build()\n\n        EncryptedSharedPreferences.create(\n            context,\n            \"vault_prefs\",\n            masterKey,\n            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,\n            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM\n        )\n    }\n\n    fun getInitializedCipherForDecryption(): Cipher {\n        val secretKey = keyStore.getKey(KEY_NAME, null) as SecretKey\n        val cipher = Cipher.getInstance(TRANSFORMATION)\n        val ivBytes = Base64.decode(prefs.getString(KEY_IV, null), Base64.DEFAULT)\n        cipher.init(Cipher.DECRYPT_MODE, secretKey, GCMParameterSpec(128, ivBytes))\n        return cipher\n    }\n\n    fun decryptToken(cipher: Cipher): String {\n        val encrypted = Base64.decode(prefs.getString(KEY_TOKEN, null), Base64.DEFAULT)\n        return String(cipher.doFinal(encrypted))\n    }\n\n    private fun getOrCreateSecretKey(): SecretKey {\n        (keyStore.getKey(KEY_NAME, null) as? SecretKey)?.let { return it }\n        val keyGenerator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, ANDROID_KEYSTORE)\n        keyGenerator.init(\n            KeyGenParameterSpec.Builder(KEY_NAME, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)\n                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)\n                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)\n                .setUserAuthenticationRequired(true)\n                .setInvalidatedByBiometricEnrollment(true)\n                .build()\n        )\n        return keyGenerator.generateKey()\n    }\n\n    companion object {\n        private const val ANDROID_KEYSTORE = \"AndroidKeyStore\"\n        private const val KEY_NAME = \"vault_key\"\n        private const val TRANSFORMATION = \"AES\/GCM\/NoPadding\"\n        private const val KEY_IV = \"vault_iv\"\n        private const val KEY_TOKEN = \"vault_token\"\n    }\n}<\/pre>\n
override fun onResume() {\n    super.onResume()\n    val cipher = vault.getInitializedCipherForDecryption()   \/\/ crashes here\n    biometricPrompt.authenticate(promptInfo, BiometricPrompt.CryptoObject(cipher))\n}<\/pre>\n
This KeyPermanentlyInvalidatedException isn’t a bug in the decryption code. It’s documented Android Keystore behavior. The key was built with setUserAuthenticationRequired(true)<\/code> and setInvalidatedByBiometricEnrollment(true)<\/code>. A key like that is permanently invalidated when a new fingerprint is enrolled. After that, cipher.init()<\/code> throws instead of returning a cipher. There are two bugs. First, nothing catches the exception, so the app crashes before the biometric prompt appears. Second, the common fix only catches it. The dead key alias and the token encrypted with it are still stored. No future key can decrypt that token, so the user stays locked out. The real fix treats the exception as data loss. Delete the Keystore entry and the stored ciphertext together. Then have the user sign in again and encrypt a fresh token with a new key.<\/p>\n
A real crash in Google’s own sample<\/h2>\n
This exact crash was reported against Google’s BiometricLoginSample<\/code> in a March 2021 GitHub issue<\/a>. The reporter signed in with a fingerprint, then added a new fingerprint to the device. After that, they could no longer log in. The stack trace shows KeyPermanentlyInvalidatedException: Key permanently invalidated<\/code>.<\/p>\n
Bug 1: nothing catches KeyPermanentlyInvalidatedException<\/h2>\n
Android’s reference page for KeyPermanentlyInvalidatedException<\/code><\/a> describes when it fires. Keys that require user authentication for every use are permanently invalidated once a new fingerprint is enrolled. They’re also invalidated when no fingerprints remain.<\/p>\n
So this isn’t a device quirk. It’s the contract of the two builder flags. cipher.init(Cipher.DECRYPT_MODE, ...)<\/code> throws the exception, a subclass of InvalidKeyException<\/code>. The code calls it from onResume()<\/code> with no try<\/code>\/catch<\/code>, so the app crashes on every launch.<\/p>\n
Bug 2: a catch alone still locks the user out<\/h2>\n
The usual first fix looks like this.<\/p>\n
\/\/ Common wrong answer: stops the crash, doesn't fix anything\nfun getInitializedCipherForDecryption(): Cipher? {\n    return try {\n        val secretKey = keyStore.getKey(KEY_NAME, null) as SecretKey\n        val cipher = Cipher.getInstance(TRANSFORMATION)\n        val ivBytes = Base64.decode(prefs.getString(KEY_IV, null), Base64.DEFAULT)\n        cipher.init(Cipher.DECRYPT_MODE, secretKey, GCMParameterSpec(128, ivBytes))\n        cipher\n    } catch (e: KeyPermanentlyInvalidatedException) {\n        Log.e(\"Vault\", \"Biometric key invalidated\", e)\n        null\n    }\n}<\/pre>\n
The crash stops. But the invalidated key is still in the Keystore under the same alias. Every future call finds it and fails the same way. getOrCreateSecretKey()<\/code> also finds it and never makes a new key. The token was encrypted with that dead key, so nothing can ever decrypt it. The user is locked out. The app doesn’t tell them why.<\/p>\n
The fix<\/h2>\n
fun getInitializedCipherForDecryption(): Cipher? {\n    return try {\n        val secretKey = keyStore.getKey(KEY_NAME, null) as SecretKey\n        val cipher = Cipher.getInstance(TRANSFORMATION)\n        val ivBytes = Base64.decode(prefs.getString(KEY_IV, null), Base64.DEFAULT)\n        cipher.init(Cipher.DECRYPT_MODE, secretKey, GCMParameterSpec(128, ivBytes))\n        cipher\n    } catch (e: KeyPermanentlyInvalidatedException) {\n        \/\/ The key is gone for good, so is anything encrypted with it.\n        \/\/ Clear both, then make the caller re-enroll the user from scratch.\n        keyStore.deleteEntry(KEY_NAME)\n        prefs.edit().remove(KEY_IV).remove(KEY_TOKEN).apply()\n        null\n    }\n}<\/pre>\n
The caller checks for null<\/code> and tells the user their biometric sign-in needs to be set up again. Then it signs them in another way and generates a new key with getOrCreateSecretKey()<\/code>. A freshly issued token gets encrypted with that key. The old ciphertext is unrecoverable by design. That’s the point of setInvalidatedByBiometricEnrollment(true)<\/code>.<\/p>\n
The rule to remember<\/h2>\n
KeyPermanentlyInvalidatedException<\/code> doesn’t mean retry. It means the key and everything encrypted with it are gone. Delete both, then re-enroll.<\/strong><\/p>\n