As Android lead on a time-clock app, should the Keystore key that encrypts the session token require user authentication, and with which setUserAuthenticationParameters mode?
answer
- who must use the token, and when
- background work cannot show a prompt
- per-use, timed, or none
- enrolment and lock-screen invalidation
- authorizations cannot change after generation
basics
~20 sIt depends on whether code needs the token while the worker is away. No authentication keeps background refresh working; a per-use biometric key ties each clock-in to a fingerprint but, by default, dies on new enrolment; a timed key sits between them.
solid answer
~50 sI start from who uses the token. If a background job refreshes or syncs with it, a key requiring authentication breaks that job, because nobody is there to answer a prompt, so the token key gets no authentication and the lock screen and hardware binding carry the protection. If the token is used only when the worker clocks in, `setUserAuthenticationParameters(0, AUTH_BIOMETRIC_STRONG)` binds every use to a strong biometric through a `CryptoObject`, at the cost of `KeyPermanentlyInvalidatedException` after each new enrolment and no use on phones without an enrolled Class 3 biometric. Adding `AUTH_DEVICE_CREDENTIAL` keeps it per-use but accepts the PIN and survives enrolment. A positive timeout lets one prompt cover a burst of work. Every authentication-bound key needs a secure lock screen to be generated and dies if it is removed. Because authorizations are fixed at generation, I decide this before release.
go deeper
Recall the three choices for a token key: no authentication, auth-per-use, or a timed window after authentication.
Explain what each setUserAuthenticationParameters mode means for background work, enrolment invalidation and the lock-screen requirement.
Plan the failure paths before shipping: KeyPermanentlyInvalidatedException after enrolment or lock-screen removal, UserNotAuthenticatedException outside a window, and the sign-in recovery each one needs.
Own the product-wide rule: which secrets get which mode, whether to split keys, and how to migrate users when the rule changes.
## What is being decided Every Android Keystore key is generated with a fixed set of **authorizations**. Whether the key that encrypts the session token requires **user authentication**, and in which mode, is one of them, and the Keystore documentation states that authorizations cannot be changed after generation. Choosing wrong means a migration to a new key later, so a lead decides it once, for the product, rather than letting each feature pick. The Android documentation frames user-authentication keys as an advanced feature that matters when a compromise of the app's process **after** key generation must not be able to use the key without the user. That is the benefit being weighed against the costs below. ## The options and what each costs | Configuration | Who can use the key | Main cost | |---|---|---| | No user authentication | The app, any time it runs | A compromised app process or an unlocked, unattended phone can use the token | | `setUserAuthenticationParameters(0, AUTH_BIOMETRIC_STRONG)` | Only an operation authorized by a strong biometric through `CryptoObject` | Invalidated on new enrolment; needs a Class 3 sensor; no background use | | `(0, AUTH_BIOMETRIC_STRONG or AUTH_DEVICE_CREDENTIAL)` | Per operation, fingerprint or PIN | No background use; a PIN holder can authorize | | `(300, AUTH_BIOMETRIC_STRONG)` or with device credential | Any operation within 300 seconds of an allowed authentication | `UserNotAuthenticatedException` outside the window; looser binding | Costs shared by **every** authentication-bound key: - **A secure lock screen is mandatory**: the key cannot be generated without one, and it is irreversibly invalidated if the user switches the lock to None or Swipe, or it is forcibly reset. - **Background work stops**: a sync job or a scheduled refresh cannot show a prompt, so it cannot decrypt the token. - **Recovery paths are required**: a dead key means signing in again, so password or server-side recovery must exist before launch. Per-use biometric-only keys add **invalidation on enrolment**: by default, enrolling a new fingerprint or removing them all makes `Cipher.init` throw `KeyPermanentlyInvalidatedException`. `setInvalidatedByBiometricEnrollment(false)` removes that cost, but lets anyone who knows the PIN enrol a finger and use the key. Timed keys and keys that accept the device credential are not invalidated on enrolment. ## Questions to settle first 1. Does any background job, a sync, a scheduled refresh or a push handler, need the token while the worker is away? 2. Are the phones personal, or shared between shifts? 3. What does a forced re-login cost a worker at the start of a shift? 4. Do the phones the workforce actually carries have an enrolled Class 3 biometric? ## Matching the mode to the token For the shift-worker time-clock app, reasonable positions include: 1. **Token used by background sync**: no authentication on its key, prefer StrongBox or the TEE, and rely on the lock screen. Adding `setUnlockedDeviceRequired(true)` (API 28) limits use to an unlocked device, but its documentation lists bugs on Android 12 to 14 and says apps avoid them by using it only on Android 15 and higher. 2. **Token used only at clock-in**: per-use with `AUTH_BIOMETRIC_STRONG`, accepting re-login after enrolment, because clocking in is exactly the moment the worker should prove presence. 3. **Mixed**: split the secret. A background-usable credential lives under a key without authentication; the clock-in action is signed or decrypted with a separate per-use key. Two keys cost more code but each mode matches its job. There is no single right answer: shared or personal phones, fraud history and support load change the balance. ## Rolling it out - Ship a version branch: `setUserAuthenticationParameters` on API 30 and later, the deprecated seconds method below it. - Moving existing users to a stricter key means generating a new key under a new alias, decrypting with the old key, re-encrypting, then `deleteEntry` on the old alias. - Count `KeyPermanentlyInvalidatedException` and `UserNotAuthenticatedException` in telemetry, so support sees invalidation waves before reviews do. Why a key-bound biometric gate is stronger than a yes/no biometric check is a design topic of its own; this decision is which Keystore authorization the token key carries.
- How do you move existing users from a key without authentication to a per-use key?Authorizations cannot be changed, so generate a new key under a new alias with the new parameters, decrypt the token with the old key, encrypt it with the new one at a moment the worker can authenticate, store the new ciphertext and call `deleteEntry` on the old alias.
- When would you accept setInvalidatedByBiometricEnrollment(false)?When forcing a re-login after every fingerprint change costs more than the risk it removes, for example on personal phones with low-value actions. The price is that anyone with the device PIN can enrol a finger and use the key, so it is a deliberate risk decision written down, not a crash fix.
- A per-use biometric key can be used by a background job after one morning unlock
- A key with a positive timeout is invalidated when a new fingerprint is enrolled
- Authentication-bound keys survive the user switching the screen lock to None
- The authentication mode can be tightened later on the same key
- Requiring authentication costs nothing for users without a strong biometric sensor
Assumes API 30 or later for setUserAuthenticationParameters and the AUTH_* constants; setUnlockedDeviceRequired exists from API 28, but its documented bugs on Android 12 to 14 are fixed only in Android 15.