0032: Windows: Windows Hello through the Passport key storage provider, DPAPI without Hello
- Status: accepted (pending verification on Windows hardware); amended (see "Amendment: PKCS#1 v1.5 for the Windows Hello wrap" below)
- Date: 2026-10-03
Context
ADR 0009's tier 2 on Windows is "Windows Hello / DPAPI". The daemon needs a wrapping key for each os-keychain identity that Windows releases only after a Hello gesture where Hello is set up, a machine key that never prompts, approval dialogs, and lock triggers, all from pure Go (no cgo on Windows, ADR 0031). No Windows host was reachable while group 7 of add-agent-daemon was built, so the scheme is written against seams that are tested on every OS, and only the thin layer that calls Windows is cross-compiled and vetted without having run.
Decision
- One backend, two kinds of identity, told apart by the identity
file's item reference:
ngc1:(Windows Hello) anddpapi1:(DPAPI). Unlocking dispatches on the prefix and never crosses over. - Windows Hello scheme. Each identity gets its own persisted RSA key
(at least 2048 bits) in the Microsoft Passport key storage provider,
named
vaultfold/identity/<32 random hex>, created decrypt-only withNgcCacheTypeset so that every private-key use prompts. A random 32-byte wrapping key is encrypted to it in software with RSA-OAEP and SHA-256 (empty label), so creating needs no decryption by the key store; it is then decrypted once through the key store (one Hello prompt) and compared before the identity file is written, and any failure deletes the key. So an identity whose wrapping key the provider cannot give back, for example because it refuses OAEP with SHA-256, is never written. Unlocking compares the key's public key with the recorded one before any prompt (a key deleted and recreated under the name is "no such item"), then decrypts with one Hello prompt naming the identity. The prompt is parented to the prompter's window, else the foreground window. NCrypt is callable from pure Go, so it was chosen over the WinRTKeyCredentialManager, which uses the same Hello keys. - DPAPI only where Hello is definitely not set up. Creating an
identity uses Hello when it is available, DPAPI
(
CryptProtectDatain the user scope, no UI, entropyvaultfold/os-keychain/dpapi/v1) only when the probe definitively says Hello is not configured (the components or the export are missing, the provider is absent, or the user has no Hello container), and otherwise fails with the Hello error. Any other probe failure (access denied, RPC, no interactive desktop, as over SSH) never downgrades, so a machine with Windows Hello never silently gets an ungated identity. The probe usesNgcGetDefaultDecryptionKeyNamefromcryptngc.dll, which is not documented. A DPAPI identity unlocks with no prompt; its touch policy degrades to a confirmation dialog, anddoctorwarns that it has no biometric gate. - The machine key is always DPAPI (entropy
vaultfold/machine-key/dpapi/v1, sealed into<Data>/machine.key.sealedwith the same migration as on macOS), never Hello, because it must not prompt. - Approvals and presence. An approval is a
MessageBoxWwith OK (allow once) and Cancel (deny), Cancel the default; "allow for this session" is not offered, because a message box has no third button that is safe to press by mistake (the desktop app will offer it).TaskDialogIndirectis not used: it needs comctl32 version 6, which needs an activation-context manifest the CLI does not carry. A touch re-prompt signs a fresh random challenge with a per-user presence keyvaultfold/presence/v1through Windows Hello, refusing a presence key whose cache policy is not "always prompt"; without Hello set up it is an OK/Cancel box; with Hello set up but unusable it is unavailable, never a plain box. Dialogs are shown only on the interactive window station, so a daemon in an SSH or service session never blocks on an invisible box. Rate-limit notices are a plain OK box that cannot answer an allow. - Lock triggers. A message-only window registered with
WTSRegisterSessionNotificationlocks on session lock and on console or remote disconnect;GetLastInputInfogives system idle;RegisterSuspendResumeNotificationgives suspend. The window acts only on a close message it posted itself, and a message loop that ends early reports the trigger unavailable, which locks every vault.
Consequences
- Verification pending on real hardware: that the Passport provider
accepts OAEP with SHA-256 and signs with PKCS#1 SHA-256 (if it does not,
every Hello create fails at its check and the scheme must move), that
NgcCacheTypecan be set and read back and makes every use prompt, that the Hello prompt appears in front for a background daemon (design.md Open Question 2), the probe's answers with and without Hello and over SSH, and the lock triggers. The full list is in the group 7 PR (#113). Until then the Windows code is cross-compiled, vetted and linted only. - Over SSH no os-keychain identity can be created (Hello cannot be ruled out there); existing DPAPI identities still unlock.
- Resetting the Windows Hello PIN deletes the Passport container and with it every Hello identity on the device, unrecoverably on that device. Rotate to another identity or keep another member device first.
- A Hello create interrupted inside the provider may leave an orphan key when the late delete also fails; it protects nothing.
- The threat model lists the same-user limits of the message box and of Modern Standby.
Alternatives considered
- DPAPI everywhere. Rejected: no user gesture; any process of the user can unprotect the blob.
- Fall back to DPAPI whenever Hello fails. Rejected after review: it turned any transient or SSH failure into a silent downgrade.
- WinRT
KeyCredentialManager. Not chosen: NCrypt reaches the same keys from pure Go (above). CredRead/Credential Manager entries. Rejected: no user gesture, readable by any process of the user.- A TaskDialog with three buttons. Rejected for the manifest reason above.
Amendment: PKCS#1 v1.5 for the Windows Hello wrap
- Date: 2026-10-25
- Context: the first use on real hardware (Windows 11 x64, Windows Hello
set up, build 02c55b0) failed every Hello create with "Windows Hello
decryption: status 0x80090027: The parameter is incorrect", agentboard
ticket 01M5S6DQW03A87YR54QKZKEBGV and its research report; OpenSpec
change
fix-windows-hello-padding.
The Microsoft Passport key storage provider does not accept
NCRYPT_PAD_OAEP_FLAG on NCryptDecrypt: it answers
NTE_INVALID_PARAMETER after the gesture, as an independent project
also found on Windows 11, while PKCS#1 v1.5 on the same kind of key
decrypts, prompts every time and refuses silent use. Every established
NCrypt client of this provider found uses PKCS#1 v1.5. The risk named in
Consequences above therefore happened, and the scheme moves as follows.
Everything else in the Decision above is unchanged.
- The wrap is RSAES-PKCS1-v1_5. The 32-byte wrapping key is encrypted
in software with
rsa.EncryptPKCS1v15and decrypted by the key store withNCRYPT_PAD_PKCS1_FLAGand no padding info. The key stays decrypt-only, 2048 bits, withNgcCacheTypeauth-mandatory; creation still decrypts once and compares before writing the identity file; unlocking still compares the public key before any prompt. - The
ngc1:item map is version 2, meaning PKCS#1 v1.5. Version 1 (OAEP) is refused as a format error. No version 1 item can exist: the only writer encodes the item after the check decrypt succeeded, and that decrypt never succeeded on hardware.dpapi1:items and the sealed machine key keep version 1. - A failed cleanup is reported. When a create fails after the key
was made and the key cannot be deleted, the error names the key
instead of the delete failure being discarded; this holds for the
check-decrypt cleanup and for the delete after a failed public-key
export inside the provider call. A create abandoned when its request
ends names the key in its error, since the late delete of the
Consequences above has no caller left to report to. An orphan from an
earlier build is listed with
certutil -user -csp "Microsoft Passport Key Storage Provider" -keyand removed with-delkey. - Lint. Go 1.26 deprecates
rsa.EncryptPKCS1v15andrsa.DecryptPKCS1v15; each use carries a justified//nolint:staticcheckrather than a hand-rolled padding or a path exclusion. Since Go 1.26 the random source argument of RSA encryption is ignored, so tests do not rely on it for reproducible ciphertexts.
Why PKCS#1 v1.5 is safe here. Its known weakness is Bleichenbacher's padding oracle, which needs on the order of 10^4 to 10^6 adaptive decryption queries that each reveal whether the padding was valid. Here every query needs its own Windows Hello gesture (auth-mandatory), the private key exists only in the local Passport container, anyone who gets one gesture approved can simply have the real ciphertext decrypted (already the threat model's boundary), and the plaintext is a random key whose only use is to open the AEAD-sealed identity, so a malleated ciphertext gains nothing. The properties claimed above for OAEP hold unchanged.
Alternatives considered for this amendment:
- Derive the wrapping key from a signature. Rejected: a sign-only
Passport key signs a fixed per-identity challenge with deterministic
PKCS#1 v1.5 and the wrapping key is an HKDF of the signature, as
Bitwarden desktop does through
KeyCredentialManager. The wrapping key would no longer be independent random material (one approved signature over the challenge discloses it forever), every rotation would need a new key or challenge, it relies on signatures staying deterministic, and it is a larger format change. It remains only the fallback to propose in a new change if PKCS#1 v1.5 decrypt also fails on hardware. - OAEP with SHA-1. Rejected: no evidence that the provider accepts any OAEP.
The status stays "pending verification on Windows hardware" until the change's hardware checklist (its tasks.md group 3) passes.