# Windows Hello × Android Companion Authentication

## Project Synopsis

The goal is to create a custom Windows Hello authentication source that delegates biometric verification to an Android device. When Windows requests user authentication (login, UAC, in-app identity checks), a background Android app surfaces a fingerprint prompt via an overlay. Upon successful biometric verification, the Android device completes a cryptographic handshake with the Windows host, satisfying the Windows Hello authentication ceremony.

This effectively turns any Android phone with a fingerprint sensor into a wireless biometric authenticator for Windows.

---

## Architecture Overview

```
Windows Logon / Auth Request
        │
        ▼
Credential Provider / CDF App (Windows)
        │
        ▼  (BLE / local network)
Background Service (Android)
        │
        ▼
BiometricPrompt overlay
        │
        ▼  (sign challenge with Android Keystore)
Signed response → Windows
        │
        ▼
Windows Hello completes auth
```

---

## Component Breakdown

### 1. Windows — Authentication Hook

There are two viable approaches for hooking into Windows Hello:

#### Option A: Companion Device Framework (CDF)

- **Namespace:** `Windows.Security.Authentication.Identity.Provider`
- **App type:** UWP / WinUI packaged app
- Registers as a Companion Device provider so Windows Hello delegates auth to it.
- Lower complexity; purpose-built for this exact scenario.
- **Caveat:** Under-documented by Microsoft, limited third-party adoption, and sparse official samples.

#### Option B: Custom Credential Provider

- **Interface:** COM DLL implementing `ICredentialProvider` / `ICredentialProviderCredential`
- Plugs directly into `LogonUI.exe` and `CredUI`.
- Runs on the secure desktop (Session 0) — no managed code, no standard UI frameworks. C/C++ only.
- Full control over the logon tile UI and authentication flow.
- Battle-tested pattern used by Duo, YubiKey, and other enterprise auth products.
- **Caveat:** Significantly more complex to develop and debug.

**Recommendation:** Start with CDF for prototyping. Move to a custom Credential Provider if CDF limitations become blockers (e.g., needing secure desktop support or finer-grained control).

### 2. Android — Biometric Service

- A **foreground service** runs persistently in the background, listening for auth challenges from the Windows host.
- On receiving a challenge, it surfaces the system `BiometricPrompt` via an overlay window.
- Requires `SYSTEM_ALERT_WINDOW` permission to draw over other apps (overdraw / display overlay).
- On successful fingerprint match, the app signs the auth challenge nonce using a key stored in the **Android Keystore** (TEE/Strongbox-backed).
- The signed response is sent back to the Windows host.

**Key APIs:**
- `androidx.biometric.BiometricPrompt` — fingerprint / face prompt
- `android.security.keystore` — hardware-backed key storage and signing
- `SYSTEM_ALERT_WINDOW` — overlay permission for surfacing the prompt from the background

### 3. Transport Layer

Communication between Windows and Android for the challenge-response exchange. Options:

| Transport        | Pros                                  | Cons                                  |
|------------------|---------------------------------------|---------------------------------------|
| **BLE**          | No shared network required, low power | Higher latency, pairing complexity    |
| **Local Wi-Fi**  | Fast, simple sockets/gRPC             | Requires same network                 |
| **USB (ADB)**    | Very fast, no wireless config         | Wired only, requires dev mode or MTP  |

BLE is the most natural fit for a wireless companion device experience. Local Wi-Fi is simpler for prototyping.

### 4. Cryptographic Flow

1. Windows generates a **challenge nonce** and sends it to Android over the transport layer.
2. Android verifies the user's fingerprint via `BiometricPrompt`.
3. On success, Android **signs the nonce** with an asymmetric key pair stored in the Android Keystore (private key never leaves TEE).
4. The signed nonce is returned to Windows.
5. Windows verifies the signature against the enrolled public key and completes the Hello ceremony.

The fingerprint template never leaves the Android device. Authentication is proven cryptographically, not by transmitting biometric data.

---

## Security Considerations

- **Android Keystore attestation** can be used to prove the signing key is hardware-bound (TEE/Strongbox), adding a layer of device trust.
- The transport layer should use **mutual TLS or an authenticated encrypted channel** to prevent MITM attacks.
- A **device enrollment / pairing step** is needed to exchange public keys and establish trust between the Windows host and the Android device.
- Consider **proximity verification** (BLE signal strength or challenge timeout) to prevent relay attacks.
- The Credential Provider secure desktop environment has strict isolation — any IPC to a user-mode companion app needs careful design.

---

## Prior Art / Reference Implementations

- **Samsung Flow** — unlocks Windows PCs via Samsung phone biometrics (uses CDF).
- **Intel Unison** — phone-to-PC companion features including unlock.
- **Microsoft Phone Link** — has explored companion unlock features.
- **Duo Security** — custom Credential Provider with push-based MFA to a phone.
- **YubiKey** — custom Credential Provider using hardware FIDO keys.

---

## Development Phases (Suggested)

### Phase 1 — Proof of Concept
- Android app with `BiometricPrompt` + overlay, simple socket server.
- Windows console app that sends a challenge over local Wi-Fi, receives signed response.
- Validate the crypto round-trip works end to end.

### Phase 2 — Windows Integration
- Build a CDF companion app (UWP) that hooks into Windows Hello.
- Verify it triggers on lock screen and UAC prompts.

### Phase 3 — Transport Hardening
- Move to BLE or encrypted Wi-Fi transport.
- Implement mutual authentication and device enrollment pairing flow.

### Phase 4 — Polish & Credential Provider (Optional)
- If CDF is insufficient, implement a full custom Credential Provider (COM DLL).
- Add proximity checks, timeout handling, and fallback to PIN/password.

---

## Open Questions

- Does the current CDF API surface still work reliably on Windows 11 24H2+? Needs validation.
- Should the Android app support face biometrics in addition to fingerprint (`BiometricPrompt` supports both)?
- What is the acceptable auth latency budget? BLE round-trip may add 500ms–2s.
- Is there a need to support multiple enrolled Android devices per Windows user?