Device keys and user verification
Every paired device holds two secrets of its own:
- a device token, which lets it read the inbox, requests, grants and log, make requests on behalf of its person, and revoke grants. It can't approve;
- an approval key, a private key that signs approvals and denials. It is made on the device and never leaves it.
What "user verification" means (whether someone had to prove they're the device's owner before each signature) depends on the platform and the key. This page says what the current source does, where that differs from release 0.5.6, and what the server can and can't check.
Each platform
| Platform | Where the approval key lives | What it needs before signing | Label |
|---|---|---|---|
| Android, standard key | The Android Keystore: in StrongBox (a separate security chip) when the phone has one, otherwise the main processor's trusted environment (TEE) | The phone must be unlocked. No check on each signature | platform-hw-unlocked |
| Android, biometric key | The same, with the key bound to biometrics | A strong biometric check for every signature. Adding a new fingerprint or face makes the key unusable, so it has to be replaced | platform-hw-uv |
| iOS | The Secure Enclave | Face ID or Touch ID for every signature, with no passcode fallback. Changing enrolled biometrics makes the key unusable | platform-hw-uv |
| Windows | A Windows Hello passkey, through Windows' WebAuthn API | Windows Hello (PIN or biometric) for every signature | platform-sw-uv |
Some details that matter:
- Android: biometric keys are opt-in. A person chooses them when pairing (Confirm every signature with biometrics), and the server must have
pairing.allow_user_verified_keys: true. Without that, an Android key only needs the phone to be unlocked: anyone holding an unlocked, paired phone can approve. - iOS needs
allow_user_verified_keys: trueto pair at all, because every iOS key is a biometric key. The iPhone app is in internal testing (Platforms and status). - Windows Hello keys are labelled
platform-sw-uvin every version. In 0.5.6 and earlier, Bouncer doesn't check TPM attestation. From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one and records the result separately; a verified key can then meetrequire_hardware_key, but no real PC has passed that check yet, and keys enrolled before it stay unattested. These keys needpairing.allow_webauthn_keys: true. A Windows PC without a Hello key can see requests but not approve or deny. - Weak biometrics aren't accepted as a stronger path. Android biometric keys require the strong biometric class. There is no option to allow a weaker face unlock.
What the server can prove
The server checks every signature against the key enrolled at pairing, and checks the label recorded then. But the label itself is mostly the device's own claim:
| Claim | Can the server prove it? |
|---|---|
| The signature was made by the enrolled key | Yes, always |
| An Android key is in secure hardware | Only with key attestation (below) |
| An Android or iOS key requires biometrics | Android: only with key attestation. iOS: no; it's the app's word |
| A Windows Hello key is in a TPM | 0.5.6 and earlier don't check it. From 0.5.7 the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked |
A modified app with a valid pairing code could claim a stronger key than it has, except where attestation proves it. The platform is part of that claim: a device that says it is an iPhone or a Mac is not asked for attestation, even under android_attestation: required. Keep pairing codes to the right person. In the current source (not yet released), #282 separates that claim from verified key evidence. The default UV-only rule still accepts the claim; operators must explicitly select a verified-evidence requirement to refuse it.
Android key attestation
Android phones can prove their key with key attestation: the Keystore signs a certificate for the new key that chains up to Google. The server checks the chain, that the key is the pairing key, that it was generated in hardware, that it needs the phone unlocked, that a biometric key needs a biometric (from 0.5.7, a biometric only; 0.5.6 also accepts a key that the phone's PIN can unlock instead), and that it belongs to the official Bouncer app.
pairing.android_attestation | Effect |
|---|---|
prefer (default) | A chain that verifies marks the key as attested. A phone without one still pairs, unattested |
required | A device that declares Android and claims a hardware key pairs only with a chain that verifies. It does not stop a modified app that declares iPhone or Mac, whose keys are not attested (issue #282). This remains an Android-specific requirement |
off | The phone's claim is taken as it stands |
Attestation proves facts about one key, not about the rest of the phone: no verified boot, patch level or integrity checks. Checking Google's list of revoked attestation keys isn't implemented.
Requiring biometric approval for a resource
resources:
- id: prod-db-password
# ...
require_hardware_uv: true
With this, only an enrolled platform-hw-uv key with a signed biometric verification value can approve. Standard Android keys and Windows Hello keys can still deny. It can also be set in defaults. This UV-only rule still accepts declared claims, including a modified client declaring iPhone or Mac, unless an operator opts in to verified evidence. Upgrading does not tighten it automatically.
In the current source (not yet released), require_hardware_key: true requires verified Android-key or Windows TPM evidence for the current key, plus a matching per-use verification: Android biometric or WebAuthn UV. A hardware-unlocked Android key still fails. A declared platform-hw-uv label alone fails, under every Android attestation mode. Setting both resource flags requires both verified evidence and the biometric rule; TPM + PIN does not satisfy both. Denials remain independent of these resource flags.
Key proof and the explicit server opt-in
The current source (not yet released) adds Device.key_proof beside the unchanged platform, assurance and attestation fields. bouncer-admin device list shows its status and evidence kind; JSON also shows checked_at.
| Status | What it means for the current key |
|---|---|
verified | The server verified Android-key or TPM evidence for this enrolled key and enrollment challenge |
unverified | Evidence is absent or deliberately unchecked; this includes ordinary iOS and macOS claims |
unsupported | The evidence has no verifier, or there is no approval-key proof path |
failed | Supported evidence was checked and failed |
Proof does not verify the reported platform, OS or app version, whole-device posture, or an individual biometric operation. Recognized historical Android evidence keeps an unknown check time (null); migration does not invent a date. Unknown legacy records never become verified, and stale proof cannot qualify another key or epoch.
Historical Android tee and strongbox records remain verified hardware evidence. For biometric keys recorded before 0.5.7, the verifier only checked that the allowed authentication types included biometrics, so some keys may also accept a device PIN. Re-pair those phones on 0.5.7 or later if biometric-only authentication is required.
The new pairing.require_verified_approval_keys defaults to false. When explicitly set to true, it requires verified evidence when an approval key is installed and whenever it signs, including existing keys after reload. It closes the declared-platform exemption for this key requirement. It cannot be combined with android_attestation: off. Keyless Windows pairing remains request-only; enrollment must then supply verified TPM evidence. Session/status reads, admin pairing and revocation, and self-revocation remain available for recovery.
Once this opt-in is enabled, a key without verified evidence cannot sign anything, including denials and device-settings changes.
A refusal uses 422 assurance_not_accepted with the requirement and proof status. Re-enrol with supported evidence, or ask the operator to review enrollment. Changing a platform or assurance label cannot establish proof. Existing allow_user_verified_keys, allow_webauthn_keys and software-key opt-ins still apply. Apps from this release use the same proof for approval eligibility and signing. No policy is activated on upgrade, and there is no automatic re-enrollment. In particular, an existing deployment using only allow_user_verified_keys: true and require_hardware_uv retains the declared-claim exposure until the operator opts in.
Windows keys enrolled before 0.5.7, or later without TPM evidence, stay unverified; no real PC has yet passed the TPM verifier. RS1 (RSA with SHA-1) attestations are refused. Wider platform, OS and app-version admission belongs to #293. Resources and policy explains the resource settings.
Approving from a notification
When a resource allows it (notification_approval: true, the default) and the person turns it on for their device, an Android phone can approve straight from a notification, for exactly the requested duration. It signs with the same key and the same checks. iOS and Windows don't offer it.
Viewing values on a device
Where a resource allows in-app viewing (view), each view is signed like an approval. It needs a hardware-backed Android or iPhone key, or a Windows Hello key, which Bouncer labels platform-sw-uv. The label does not prove where Windows keeps it. Viewing uses the key's normal check: a standard Android key only needs the phone unlocked; a biometric key asks for biometrics every time. The resource's own key requirements also apply. Each view is logged as secret_viewed.
How this was checked
From the source: the Android Keystore channel (KeystoreChannel.kt, BiometricSigning.kt), the iOS Secure Enclave provider (NativeAppleKeys.swift), the Windows Hello code, the config loader's pairing defaults, and the server's attestation module. These pages don't claim device testing. Testing on physical phones and PCs is separate from this guide, and parts of it haven't been done yet: no real PC has passed the Windows Hello TPM check, for example.