ObliviOS Developer portal Project site

Home / Decisions / ADR-039

Accept the Duress Unlock keyguard integration design.

Accepted, recorded 15 August 2026.

Decision
ADR-039
Date
2026-08-15
Status
AcceptedAccepted
Part
Duress Unlock
Mentions
ADR-038
Mentioned by
ADR-040, ADR-042

1Decision

Accept the Duress Unlock keyguard integration design (docs/superpowers/specs/2026-08-15-duress-keyguard-integration-design.md), resolving all three items ADR-038 left open, and retire two pieces of the already-merged duress-unlock-core module's original scope: its PBKDF2 credential-hash matching, and its consumption as a runtime Binder-called app module.

2Why and evidence

Brainstormed through the three ADR-038 open items in order.

(1) Dispatch order/collision: resolved by always paying the real per-profile Gatekeeper check's cost on every failed real-credential attempt — a registered decoy gets a genuine verifyCredential(credential, decoyUserId) call, an unregistered one gets an equivalent-cost dummy — which closes the timing side-channel a conditional call would create, and naturally avoids the wipe/decoy hooks shadowing each other since a decoy match already returns "matched" before the wipe hook's own finally block runs.

(2) Because the real Gatekeeper check is now always paid and authoritative, duress-unlock-core's own PBKDF2 hash comparison stops mattering for the match decision — keeping it would mean maintaining two independent security-critical comparison paths for no remaining benefit, so it is retired in favor of Gatekeeper's hardware-backed, anti-hammering guarantees.

That, in turn, meant confronting where the routing logic actually runs: duress-unlock-core is a plain JVM/Gradle module built for an app process, but the hook must execute synchronously inside system_server, where an out-of-process Binder dependency on a separate app's liveness would be a reliability regression at the OS's single most security-critical hook — exactly why GrapheneOS's own DuressPasswordHelper is in-tree/in-process rather than a separate app.

Decided to port the routing logic into frameworks/base as new framework-internal Java instead, with duress-unlock-core demoted to validated-reference-implementation status.

(3) Setup UX: a new AegisOS Settings flow (not a reuse of the wipe-only DuressPasswordSetupActivity) that re-authenticates the owner, creates/selects a Private-Space-type profile, and rejects a candidate decoy PIN that collides with the configured wipe-PIN using the wipe feature's own existing DuressCredentials.verify() — real collision prevention without ever storing or comparing plaintext across the two setup flows.

3Consequences

duress-unlock-core's DuressProfileState conceptually shrinks to Off/Registered(profileId) — the credential-hash fields and DuressCredentialMatcher's comparison logic are no longer part of the runtime path; the implementation plan decides their literal fate (deleted vs. left as reference). No code changes landed from this ADR alone — it authorizes the design, not an implementation. The actual frameworks/base patch, new Settings activities, and framework-internal tests remain future implementation-plan work against the real platform source tree, which this repository does not hold.

4Review when

Revisit if the implementation plan finds the framework-internal port cannot cleanly reuse LockSettingsStorage or the DuressCredentials.verify() collision check as assumed here, or if real-hardware timing measurement (still deferred, per the design's own "Testing" section) finds the symmetric-cost dispatch is not actually symmetric in practice.

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