Biometric Auth — Why BIOMETRIC_WEAK Accepts a Printed Photo

// 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.