Biometric Authentication: How It Works and When It Fails You

// io.thecodeforge — System Design tutorial
// Biometric Modality Selection — Architecture Decision Record
// Scenario: Multi-channel fintech app selecting auth modality per channel

// ─────────────────────────────────────────────────────────────────────
// SYSTEM CONTEXT
// ─────────────────────────────────────────────────────────────────────
// Channels:    Mobile (iOS + Android), Web portal, IVR phone banking
// Users:       ~4M retail banking customers
// Threat model: Remote credential stuffing, stolen device, SIM swap
//               (NOT nation-state targeted physical attacks)

// ─────────────────────────────────────────────────────────────────────
// MODALITY DECISION TREE — per channel
// ─────────────────────────────────────────────────────────────────────

CHANNEL: Mobile (iOS 14+, Android 9+)
├── Primary:   On-device fingerprint OR Face (delegated to OS biometric API)
│              WHY: We never see the raw biometric — OS handles enrollment
│              and matching inside the Secure Enclave / TEE. We only get
│              a signed cryptographic assertion: "user authenticated".
│              This eliminates template storage liability entirely.
│
├── Hardware:  Apple Secure Enclave (A7+), Android StrongBox / TEE
│              REQUIREMENT: Confirm hardware-backed key storage at
│              enrollment time. Reject software-only fallbacks.
│              Android API: KeyInfo.isInsideSecureHardware() == true
│              iOS API:     SecAccessControlCreateWithFlags + .biometryAny
│
├── Fallback:  Device PIN (NOT SMS OTP — defeats SIM swap protection)
│
└── REJECT:    Raw image/template capture from custom SDK sensors.
               Legal exposure: BIPA (Illinois), GDPR Art.9 (special category).
               Operational exposure: You now own a biometric data breach.

CHANNEL: Web Portal (desktop browser)
├── Primary:   FIDO2 / WebAuthn with platform authenticator
│              WHY: Browser biometric APIs (navigator.credentials) delegate
│              to the OS — same Secure Enclave path as mobile.
│              Template never leaves the device. Ever.
│
├── Fallback:  FIDO2 hardware key (YubiKey) — for power users / ops staff
│
└── REJECT:    Browser-based face capture via WebRTC + cloud matching.
               Latency is 800ms–2s round-trip. Liveness detection requires
               server-side ML infra you have to maintain and retrain.
               Not worth it when WebAuthn gives you better security for free.

CHANNEL: IVR Phone Banking
├── Primary:   NONE — do not use voice biometrics as a security control.
│              WHY: Voice synthesis (ElevenLabs, RVC, VALL-E) clones voice
│              from publicly available audio. LinkedIn videos. Earnings calls.
│              Customer service recordings. The attack cost is ~$0.
│
├── Alternative: Step-up to mobile push notification with biometric
│               confirmation on the registered device. Forces the attacker
│               to control both the phone call AND the enrolled device.
│
└── If voice biometrics are mandated by business: treat as a single factor
    in a 2FA flow — never as the sole gate. Document the risk acceptance.

// ─────────────────────────────────────────────────────────────────────
// FAR / FRR OPERATING POINTS — what the product team needs to understand
// ─────────────────────────────────────────────────────────────────────

FAR  = False Acceptance Rate  — impostors incorrectly granted access
FRR  = False Rejection Rate   — legitimate users incorrectly denied

// These are inversely coupled. Lowering FAR raises FRR and vice versa.
// The operating point is a BUSINESS DECISION, not a technical one.

Modality          Typical FAR         Typical FRR     Notes
──────────────────────────────────────────────────────────────────────
Fingerprint       0.001% – 0.1%       0.1% – 1%       Degrades: wet/dry fingers
Face 3D (Face ID) 0.0001%             ~1–2%           Degrades: masks, sunglasses
Face 2D           1% – 5%             0.5%            NEVER use for finance
Iris              0.00008%            0.3%            Hardware cost is prohibitive
Voice             1% – 10%            1% – 5%         Synthetic audio attack: ~100% FAR

// At 4M users, even a 0.1% FRR means 4,000 locked-out customers per day.
// Your call centre cost per failed auth interaction: ~$8–12.
// That's $32,000–$48,000/day in hidden costs from a threshold decision.
// Run this number in front of your product manager before finalising thresholds.

// io.thecodeforge — System Design tutorial
// Biometric Matching Pipeline — Sequence + Data Flow
// Scenario: Mobile banking app, on-device matching via Android BiometricPrompt

// ─────────────────────────────────────────────────────────────────────
// SEQUENCE: Enrollment (one-time, at account setup)
// ─────────────────────────────────────────────────────────────────────

User → App: "Enable biometric login"

App → OS BiometricManager:
    CHECK canAuthenticate(BIOMETRIC_STRONG)
    // BIOMETRIC_STRONG requires hardware-backed credential
    // BIOMETRIC_WEAK allows face unlock via camera (lower assurance)
    // NEVER use DEVICE_CREDENTIAL alone for financial flows

    IF result == BIOMETRIC_ERROR_NO_HARDWARE:
        // Device has no biometric hardware. Offer PIN fallback.
        // Log telemetry — useful for device support decisions.
        ABORT enrollment, present PIN setup

    IF result == BIOMETRIC_ERROR_NONE_ENROLLED:
        // Hardware exists but user hasn't enrolled a fingerprint/face.
        // Direct to system Settings — you CANNOT enroll on their behalf.
        LAUNCH Intent(Settings.ACTION_BIOMETRIC_ENROLL)

App → Android Keystore:
    // Generate an asymmetric key pair BOUND to biometric authentication.
    // This is the critical step. The private key is:
    //   - Stored in hardware-backed Keystore (TEE or StrongBox)
    //   - ONLY usable after successful biometric auth in the same session
    //   - Never exportable — cannot be read out of the hardware, ever

    KeyPairGenerator.getInstance("EC", "AndroidKeyStore")
    KeyGenParameterSpec.Builder("biometric_auth_key", PURPOSE_SIGN)
        .setAlgorithmParameterSpec(ECGenParameterSpec("secp256r1"))
        .setUserAuthenticationRequired(true)          // BOUND to biometric
        .setUserAuthenticationParameters(
            timeout = 0,                              // 0 = require fresh auth
            type = AUTH_BIOMETRIC_STRONG              // NOT weak face unlock
        )
        .setInvalidatedByBiometricEnrollment(true)   // KEY IS DELETED if new
                                                     // fingerprint is added.
                                                     // Prevents adding attacker
                                                     // fingerprint = instant access.

App → Backend API:
    POST /biometric/enroll
    PAYLOAD: { userId, publicKey (PEM), deviceId, keyAttestation }
    // keyAttestation is a certificate chain from the hardware proving the key
    // genuinely lives in hardware. Verify this server-side — DO NOT skip it.
    // An unattested key could be a software key on a rooted device.

Backend:
    VERIFY keyAttestation certificate chain against Google's root CA
    // Google publishes root certificates for hardware attestation.
    // If attestation fails: reject enrollment, flag account for review.
    STORE { userId, publicKey, deviceId, enrolledAt }
    // You are storing a PUBLIC KEY. Not a fingerprint. Not a template.
    // A breach of this table leaks nothing biometric.

// ─────────────────────────────────────────────────────────────────────
// SEQUENCE: Authentication (every login)
// ─────────────────────────────────────────────────────────────────────

User → App: "Log in with fingerprint"

App → Backend:
    GET /biometric/challenge
    RESPONSE: { challenge: "<32-byte cryptographically random nonce>" }
    // The challenge MUST be server-generated and single-use.
    // Client-generated challenges = replay attack surface.
    // Store challenge server-side with a 60-second TTL.

App → OS BiometricPrompt:
    // Show system fingerprint dialog.
    // Pass a CryptoObject wrapping a Signature initialised with private key.
    BiometricPrompt.authenticate(
        CryptoObject(signature),
        cancellationSignal,
        executor,
        authCallback
    )

OS → Secure Hardware:
    BIOMETRIC MATCHING HAPPENS HERE — entirely inside TEE/Secure Enclave
    The app NEVER sees the fingerprint image or template.
    The hardware returns: SUCCESS or FAILURE
    On SUCCESS: unlocks the private key for use within this session

OS → App (on success):
    // The Signature object is now usable — private key is unlocked.
    signature.update(challengeBytes)  // Sign the server's nonce
    signedChallenge = signature.sign() // Produces EC signature

App → Backend:
    POST /biometric/verify
    PAYLOAD: { userId, deviceId, signedChallenge, challengeId }

Backend:
    RETRIEVE challenge by challengeId — verify it's < 60 seconds old
    MARK challenge as consumed — prevents replay within TTL window
    RETRIEVE publicKey for userId + deviceId
    VERIFY ECDSA signature over challenge bytes using stored publicKey
    // Standard ECDSA verify. No biometric data ever reaches the server.
    // If signature is valid: the user's finger was on the enrolled device.
    // That's the cryptographic guarantee. Nothing more, nothing less.

    IF valid:
        ISSUE short-lived JWT (15min) + refresh token (rotated on each use)
        LOG auth event: { userId, deviceId, timestamp, ipAddress, geoHash }

// ─────────────────────────────────────────────────────────────────────
// WHAT HAPPENS WHEN SOMEONE ADDS A NEW FINGERPRINT TO THE DEVICE
// ─────────────────────────────────────────────────────────────────────

// setInvalidatedByBiometricEnrollment(true) means:
// → Android deletes biometric_auth_key from Keystore automatically
// → Next login attempt: KeyPermanentlyInvalidatedException thrown
// → App detects this, prompts: "Your biometric login was reset.
//   Please log in with your password to re-enrol."
// → Requires password re-authentication before new biometric enrolment
//
// WHY THIS MATTERS: Without this, an attacker who has brief physical
// access to an unlocked phone can add THEIR fingerprint to the device
// and immediately gain access to the banking app with their own finger.
// This flag closes that attack vector.

// io.thecodeforge — System Design tutorial
// Biometric Failure Mode Catalogue — Production Incident Patterns
// Scenario: High-availability fintech app, 4M users, 99.9% auth SLA

// ─────────────────────────────────────────────────────────────────────
// FAILURE MODE 1: KeyPermanentlyInvalidatedException
// ─────────────────────────────────────────────────────────────────────

SYMPTOM:
    User taps "Login with fingerprint"
    App throws: KeyPermanentlyInvalidatedException
    User sees: generic error screen or app crash (if unhandled)

CAUSE:
    A) User added/removed a fingerprint on their device
    B) User changed/removed screen lock (depending on key config)
    C) Device was enrolled with setInvalidatedByBiometricEnrollment(true)
       — which is correct behaviour, not a bug

HANDLING:
    catch (KeyPermanentlyInvalidatedException e) {
        // Do NOT show a generic error. The user isn't broken.
        // Their security configuration changed. That's expected.

        // 1. Delete the invalidated key from local Keystore
        keyStore.deleteEntry("biometric_auth_key")

        // 2. Revoke the associated public key on the server
        //    POST /biometric/revoke { userId, deviceId }
        //    This prevents the old public key being used in a confused deputy attack
        apiClient.revokeBiometricKey(userId, deviceId)

        // 3. Present clear UX: "Your biometric login needs to be reset"
        //    Require password authentication before re-enrollment
        //    This is intentional friction — it's the security checkpoint
        navigator.navigate(Route.BiometricReenrollment)
    }

// ─────────────────────────────────────────────────────────────────────
// FAILURE MODE 2: Biometric lockout after failed attempts
// ─────────────────────────────────────────────────────────────────────

SYMPTOM:
    After 5 failed fingerprint attempts, Android locks biometric auth.
    App receives: BiometricPrompt.ERROR_LOCKOUT (error code 7)
    After extended failures: ERROR_LOCKOUT_PERMANENT (error code 9)
    User is stuck — biometric is disabled until device PIN is entered.

CAUSE:
    OS-enforced anti-brute-force protection. This is correct.
    But apps that don't handle it gracefully strand the user.

HANDLING:
    onAuthenticationError(errorCode, errString) {
        when (errorCode) {
            BIOMETRIC_ERROR_LOCKOUT -> {
                // Temporary lockout (30 seconds typically)
                // Guide user to verify with device PIN/password
                // This unlocks biometric after successful PIN entry
                showMessage("Too many attempts. Verify with your PIN to continue.")
                // Offer explicit "Use PIN instead" button — don't just show error
            }
            BIOMETRIC_ERROR_LOCKOUT_PERMANENT -> {
                // Requires device PIN. Cannot be unlocked programmatically.
                // Offer password-based app login as parallel path
                showMessage("Biometric locked. Log in with your password.")
                // Log this event — spike in LOCKOUT_PERMANENT is an
                // indicator of a targeted brute-force campaign on physical devices
            }
            BIOMETRIC_ERROR_NO_BIOMETRICS -> {
                // User removed all enrolled biometrics since last session
                // Treat same as KeyPermanentlyInvalidatedException path
            }
        }
    }

// ─────────────────────────────────────────────────────────────────────
// FAILURE MODE 3: Template aging / demographic degradation
// ─────────────────────────────────────────────────────────────────────

SYMPTOM:
    FRR rises gradually over months. Support tickets:
    "My fingerprint doesn't work anymore" — user hasn't changed anything.
    Affects specific cohorts disproportionately: manual workers,
    elderly users, users with skin conditions.

CAUSE:
    Enrolled template no longer matches aged/changed biometric closely enough
    to exceed the matching threshold. This is a physics problem, not a bug.

MITIGATION:
    // Monitor per-cohort FRR in your auth analytics pipeline
    // Alert threshold: FRR rising above 2% in any user segment

    // Build proactive re-enrollment:
    IF (daysSinceEnrollment > 365) AND (recentAuthSuccessRate < 0.95):
        PROMPT user on next successful login:
        "Update your biometric for better reliability" (not security framing)
        // Users accept re-enrollment when framed as convenience, not security

    // On-device matching note: you can't query match scores directly from
    // Android BiometricPrompt — it's binary success/failure.
    // Infer quality from FRR trends in your server-side auth event log.

// ─────────────────────────────────────────────────────────────────────
// FAILURE MODE 4: Weak fallback path undermining biometric security
// ─────────────────────────────────────────────────────────────────────

SYMPTOM (SECURITY):
    Biometric auth is bypassed entirely by attackers who target the fallback.
    App has Face ID → fallback is SMS OTP → SIM swap = full account takeover.
    The biometric layer added zero net security.

ANTI-PATTERN:
    Biometric → SMS OTP fallback      (SIM swap defeats it)
    Biometric → 4-digit PIN fallback  (brute-forceable offline if device stolen)
    Biometric → Security question     (social engineering / data breach defeats it)

CORRECT PATTERN:
    Biometric → Device PIN/Password fallback (OS-enforced, hardware-encrypted)
    WHY: If an attacker has the device and the PIN, they already have physical
         possession. The threat model at that point is device loss, not remote
         compromise. Device-level encryption handles that — not your app.

    For step-up actions (transfers > $5,000, change of registered device):
    NEVER accept biometric OR fallback alone.
    REQUIRE: biometric + separate OTP to registered email or authenticator app.
    Make fallback paths trigger step-up re-verification, not bypass it.

// io.thecodeforge — System Design tutorial
// FIDO2 / WebAuthn Biometric Auth — Full System Architecture
// Scenario: Web + mobile banking portal, replacing password + SMS 2FA

// ─────────────────────────────────────────────────────────────────────
// COMPONENTS
// ─────────────────────────────────────────────────────────────────────

[Client: Browser / Mobile App]
    ↕  WebAuthn API / CTAP2
[Authenticator: Platform (Secure Enclave) or Roaming (YubiKey)]
    ↕  HTTPS
[Relying Party Server: Your backend]
    ↕  Internal
[Credential Store: Database — public keys ONLY]

// ─────────────────────────────────────────────────────────────────────
// REGISTRATION (FIDO2 Enrollment)
// ─────────────────────────────────────────────────────────────────────

STEP 1 — Server generates registration challenge:
    POST /webauthn/register/begin
    INPUT:  { userId, username }

    Server creates PublicKeyCredentialCreationOptions:
    {
        challenge: crypto.randomBytes(32),      // Single-use, 5-min TTL
        rp: {
            id:   "bank.example.com",           // Relying Party ID — MUST match origin
            name: "Example Bank"
        },
        user: {
            id:          userId (Buffer),
            name:        "user@example.com",
            displayName: "Jane Smith"
        },
        pubKeyCredParams: [
            { type: "public-key", alg: -7  },   // ES256 (ECDSA P-256) — prefer this
            { type: "public-key", alg: -257 }   // RS256 — fallback for older YubiKeys
        ],
        authenticatorSelection: {
            authenticatorAttachment: "platform",  // Use built-in biometric (Touch ID etc.)
            // "cross-platform" = YubiKey; omit to allow both
            userVerification: "required",          // MUST verify user (biometric or PIN)
            // "preferred" is NOT sufficient for financial auth — attacker device
            // without biometric enrolled would skip verification entirely
            residentKey: "required"               // Passkey: credential stored on device
        },
        attestation: "direct",
        // "direct": get the authenticator's attestation statement
        // Lets you verify the credential came from genuine Apple/Google hardware
        // vs a software authenticator on a rooted device
        // Note: Apple anonymises attestation by default ("apple" format)
        // — you get authenticity proof without tracking individual devices

        timeout: 300000   // 5 minutes for registration flow
    }

STEP 2 — Browser calls navigator.credentials.create():
    OS shows biometric prompt (Touch ID, Face ID, Windows Hello, etc.)
    User verifies with biometric or device PIN
    Platform Authenticator generates:
        - New EC key pair (private key stays in Secure Enclave FOREVER)
        - credentialId: random identifier for this credential
        - attestationObject: signed proof of hardware origin
        - clientDataJSON: includes challenge + origin (phishing protection)

STEP 3 — Client sends registration response to server:
    POST /webauthn/register/complete
    PAYLOAD: {
        id:       credentialId (base64url),
        response: {
            clientDataJSON:    "<base64url>",
            attestationObject: "<base64url>"
        }
    }

STEP 4 — Server verifies registration:
    // USE A WELL-MAINTAINED FIDO2 LIBRARY. Do NOT parse this manually.
    // Java: webauthn4j | Node: @simplewebauthn/server | Python: py_webauthn

    a) Parse clientDataJSON:
       - Verify type == "webauthn.create"
       - Verify challenge matches stored challenge (and consume it)
       - Verify origin == "https://bank.example.com"  ← phishing protection
       - Verify rpIdHash == SHA256("bank.example.com")

    b) Parse attestationObject:
       - Verify authenticator data flags:
         bit 0 (UP): User Present — MUST be set
         bit 2 (UV): User Verified — MUST be set (we required userVerification)
         bit 6 (AT): Attested Credential Data — MUST be set for registration
       - Extract credentialPublicKey and credentialId
       - Verify attestation signature against attestation certificate

    c) Store in database:
       { userId, credentialId, publicKey(COSE format), signCount: 0,
         createdAt, deviceName: user-supplied, lastUsed: null }
       // signCount is a monotonic counter — the authenticator increments it
       // each authentication. If server receives a count <= stored count:
       // the credential was CLONED. Flag immediately.

// ─────────────────────────────────────────────────────────────────────
// AUTHENTICATION (FIDO2 Login)
// ─────────────────────────────────────────────────────────────────────

STEP 1 — Server issues authentication challenge:
    GET /webauthn/auth/begin?userId=<id>
    RESPONSE: PublicKeyCredentialRequestOptions:
    {
        challenge:        crypto.randomBytes(32),
        rpId:             "bank.example.com",
        allowCredentials: [{ type: "public-key", id: credentialId }],
        userVerification: "required",
        timeout:          120000
    }

STEP 2 — Browser calls navigator.credentials.get():
    OS shows biometric prompt
    User verifies
    Platform Authenticator:
        - Unlocks private key
        - Increments signCount
        - Signs: SHA256(clientDataJSON) + authenticatorData

STEP 3 — Verify on server:
    a) Verify clientDataJSON (same checks as registration)
    b) Verify rpIdHash + flags (UP + UV must be set)
    c) Verify signCount > storedSignCount
       IF signCount <= storedSignCount:
           // Authenticator cloning detected — this is serious.
           // Revoke credential. Force re-enrollment.
           // Alert security team. This is a P1 incident.
           REVOKE credential
           REQUIRE fresh authentication via alternative channel
    d) Verify ECDSA/EdDSA signature using stored public key
    e) Update stored signCount
    f) Issue session token

// ─────────────────────────────────────────────────────────────────────
// WHAT MAKES THIS PHISHING-RESISTANT
// ─────────────────────────────────────────────────────────────────────

// The credential is bound to rpId = "bank.example.com" at creation time.
// When an attacker proxies the user to "b4nk.example.com":
//   - Browser computes rpIdHash of "b4nk.example.com"
//   - No matching credential exists (enrolled for "bank.example.com")
//   - navigator.credentials.get() returns empty — auth fails
//   - Attacker cannot forward to real site — they don't have the signature
//     (the private key never left the user's device)
// AitM proxy attacks that work against TOTP / SMS OTP: BLOCKED at protocol level.

// ─────────────────────────────────────────────────────────────────────
// ACCOUNT RECOVERY STRATEGY — don't skip this
// ─────────────────────────────────────────────────────────────────────

OPTION A: Multi-device passkeys (iCloud Keychain / Google Password Manager)
    PRO:  Survives device loss — credential synced across user's Apple/Google account
    CON:  Biometric is now also protected by iCloud/Google account security
          If their Google account is compromised, so is the passkey
    SUITABLE FOR: Consumer apps, lower-risk transactions

OPTION B: Recovery codes (printed, one-time use)
    PRO:  No dependency on third-party account
    CON:  Users lose them, store them insecurely, screenshot them
    SUITABLE FOR: Power users, developer tools, internal tooling

OPTION C: Identity re-verification gate
    PRO:  Strongest — requires proof of identity to re-enrol
    CON:  Highest friction. 48-72 hour manual review process.
    SUITABLE FOR: High-value financial accounts, regulated identities

DO NOT: Allow password reset to bypass FIDO2 credential management.
    If a password reset can add a new device credential without biometric,
    your entire FIDO2 security model collapses to password security.