ObliviOS Developer portal Project site

Home / Decisions / ADR-217

One enrolled finger of the owner, chosen in Settings, opens the Duress Unlock decoy in place of the decoy PIN.

Proposed, recorded 4 November 2026.

Decision
ADR-217
Date
2026-11-04
Status
ProposedProposed (owner request 2026-11-04, chat; landed on the build server as ce630046aa54 and f9920122fdf, not compiled, not run on a device)
Part
Duress Unlock
Mentions
ADR-088
Mentioned by
ADR-260

1Decision

One enrolled finger of the owner, chosen in Settings, opens the Duress Unlock decoy in place of the decoy PIN. AuthenticationClient.onAuthenticated asks LockSettingsInternal.routeDecoyFinger about every fingerprint match before a token reaches the keystore.

The duress finger at the keyguard routes to the decoy through the mint and switch of DecoyProfileHelper, with the decoy credential kept by DecoyFingerHelper (wrapped under a key derived from the real user's synthetic password, unwrapped into system_server memory when the real credential is verified), and reaches the keyguard as a success for no user, which it ignores.

The duress finger anywhere else, or when the decoy cannot be reached, is an unrecognised finger and never opens the real session or authenticates the real keystore. Settings gets a chooser behind the Duress Unlock screen. Patches frameworks-base/0008 and packages-apps-settings/0004.

2Why and evidence

Owner 2026-11-04 (chat): use the other hand's finger as the duress credential. A finger carries no credential and the decoy's storage opens only with a credential, so the decoy credential is kept for the finger.

Rejected: an escrow token (the unmanaged decoy loses its escrow data at its first credential verification, activateEscrowTokens -> destroyEscrowData, and keeping it needs a divergence in a security-critical gate); a keystore key bound to biometric authentication (using it needs the real user's hardware token in the keystore); interception in SystemUI (the token and the strong-auth state are already the real user's); allowing the duress finger in a BiometricPrompt (it would release the real user's auth-bound keys).

Read in the build tree: AuthenticationClient, KeyguardUpdateMonitor.handleFingerprintAuthenticated (a success for another user is ignored), DecoyProfileHelper, LockSettingsService.

3Consequences

The finger works after the first PIN unlock following a boot only (the cache is empty before it). A changed decoy credential is relinked by Settings in the same operation; a stale link fails closed. authorizeDecoySwitchKeyguardSkip has two call sites, both in DecoyProfileHelper. The decoy credential is in system_server memory while the real user has been unlocked since boot. The switch time is the one of the PIN route (ADR-088, DUR-019); the finger does not change it. The decoy session has no fingers of its own (spec section 7). Rows DUR-020 to DUR-029.

4Review when

Any of DUR-020 to DUR-029 failing; a real-session frame visible during the switch; a deadlock between the biometric and lock-settings stacks; a stock change of AuthenticationClient or of the keyguard fingerprint callback.

Read from docs/governance/decision-log.md, entry ADR-217.