ObliviOS Developer portal Project site

Home / Decisions / ADR-228

The Duress unlock matches the ordinary unlock in time and in every animation and movement, by PIN and by finger.

Proposed, recorded 12 November 2026.

Decision
ADR-228
Date
2026-11-12
Status
ProposedProposed (owner, 2026-11-12: margin 0.0, every animation, the fingerprint route included; a resident decoy key declined, "rather not"; the spike approved, and its landing and build approved). Spike frameworks-base/0021 landed on the build tree and built (lynx 2026111201, IMG-032; the owner overruled the closed round gate, 20 DUR rows, for this one build), not signed, not flashed, not run. The pale fill, the exit clock, the loading state and the fingerprint route are not designed. Partly superseded by ADR-229 (2026-11-13): the warm launcher and its spike frameworks-base/0021 are no longer the mechanism.
Part
Duress Unlock
Mentions
ADR-088, ADR-222, ADR-229
Mentioned by
ADR-229

1Decision

The Duress unlock matches the ordinary unlock in time and in every animation and movement, by PIN and by finger, with a margin of 0.0 (owner, 2026-11-12, replacing the margin that DUR-019 left open). The decoy home may load late, as a home screen does after a software update (1 to 1.5 s until the apps and the UI are loaded), so that the keyguard exit of both routes runs on the same clock.

The decoy's credential-encrypted storage is not kept open while the device is locked: the decoy's CE key stays evicted at an owner unlock, and the lock-time warm start starts only what needs no CE storage, the decoy's Launcher3 process (design B of 2026-11-12-duress-unlock-timing-design.md). frameworks-base/0017 (stop with delayed locking, a resident key) is not landed.

The owner's brightness, screen timeout, rotation, lock-screen toggles and built-in quick-settings tiles are copied to the decoy when the keyguard locks (frameworks-base/0018 to 0020).

Corrects ADR-222: its statement that the stop of an owner unlock leaves the decoy's storage open is false, so its mechanism for a warm launcher is replaced; its other parts (BOOT_COMPLETED held back, the stop at every unlock, the unlock before the switch, the early pre-hide) stay.

2Why and evidence

[measured 2026-11-12, lynx 2026111101, logcat of the unlocks and a rolling screen recording read frame by frame] Ordinary unlock, 10 runs: 0.77 to 0.79 s from the credential check to the end of the keyguard exit. Duress, 8 runs: 2.57, 2.75 and 2.96 s when the decoy was RUNNING_LOCKED with a cold launcher (after an owner unlock), 1.30 to 1.50 s with the launcher running.

Cause of the cold case: vold logs Evicted fscrypt key 0.2 s after each stop of 0015 (the plain stop), so the next lock-time start stays RUNNING_LOCKED; the key comes back at the duress credential (fscrypt_unlock_ce_storage, 0.36 s after the check) and the launcher process starts 0.54 s after the check and draws at +3.1 s; the stop on the return from the decoy is the stock delayed-locking stop and keeps the key.

A locked decoy resolves only com.android.settings/.FallbackHome as home (cmd package query-activities --user), so Launcher3 is not direct-boot aware. Video: 3 s of a black screen with no movement on a cold duress unlock; about 0.6 s of one flat pale colour between the bouncer and the dark decoy home on a warm one; the return to the real session is smooth. SystemUI logs Skipped 46 to 94 frames after each of 11 screen wakes, in the real session too.

The decoy differs from the owner in screen_brightness (9 against 6), screen_off_timeout (30000 against 1800000), accelerometer_rotation, three lock-screen toggles and the quick-settings tiles. Source: ActivityManagerService.stopUserWithDelayedLocking is the only stop that keeps the key; ActivityManagerInternal.startProcess has nine parameters; ProcessList.startProcessLocked has no locked-user check at its start.

Rejected, each with its reason: a resident decoy key (0017: the owner declined an open decoy storage while the device is locked; an automated review named it credential-bound storage left unlocked); evicting the key at lock and keeping the decoy running (a process of the decoy cannot read its files); a warm start on screen-on (the finger route starts from a dark screen with no lead time); a decoy running at all times (ADR-222: 2.0 GB, or 0.6 GB); perfetto for the frame analysis (lynx has no tracefs, every ftrace source returned about 1 KB); copying the settings at the switch (it adds binder calls to a time that has to equal the ordinary one) and a prefix check on custom( tiles (a leading space, capitals or an intent( entry pass it, and a tile names an app of the owner).

3Consequences

A decoy that cannot read its storage while locked has to pay the CE unlock (0.36 s) at the credential; design B hides it behind the exit animation and the loading state, which is not yet built. [assumption] Launcher3's Application.onCreate survives a locked user and continues after the unlock, and the pre-started process holds an acceptable amount of memory (266 MB RSS when unlocked); the spike measures both.

ADR-088 found a pre-started decoy launcher unsafe because its window composites over the real session; 0021 starts the process only, with no activity and no window, which the spike has to confirm (no decoy window while the real session is on screen). 0021 is a throwaway: it has no test and no abstraction, and the wiring of 0018 to 0021 was type-checked against the jars of the previous build (0 errors, one control error) and compiled, nothing more.

Brightness changed from the lock screen's quick settings after the lock is not copied (DUR-037). The decoy's wallpaper and home differ from the owner's (black with six icons against a red wallpaper): whether that is intended is open. Whether the stall at each wake is stock behaviour is not known.

4Review when

The spike shows the launcher process does not survive, or crashes after the unlock (DUR-035); the duress unlock after design B is still more than the loading state can hide (DUR-019); the owner accepts an open decoy storage after all; the cause of the pale fill is not in the keyguard (task 3 of 2026-11-12-duress-unlock-timing.md).

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