Security Model

​

Trust Boundaries

┌─────────────────────────────────────────┐
│  TRUSTED (on device)                   │
│  - Platform authenticator              │
│  - WebAuthn API + PRF extension        │
│  - HKDF derivation (V1 fallback only)  │
│  - Identity Key storage (localStorage) │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  UNTRUSTED (server-side)               │
│  - Only public keys stored             │
│  - Challenge issuance and verification │
│  - No biometric data, ever             │
└─────────────────────────────────────────┘

​

On-Device (Trusted Zone)

• Secure enclave or trusted execution environment (TEE)
• Biometric sensor (fingerprint, Face ID, iris)
• Credential private keys stored in hardware
• PRF computation (V2) happens in secure element

• Browser-provided cryptographic primitives
• Mediates access to platform authenticator
• Enforces origin and RP ID binding
• Returns public credential data and PRF outputs

• V2 (PRF): Hardware-backed, never exposed
• V1 (HKDF): Computed in browser via Web Crypto API
• Identity Key stored in localStorage (or IndexedDB)

​

Server-Side (Untrusted Zone)

• Public Identity Keys (64-char hex strings)
• User IDs (for account linking)
• Device IDs (for multi-device tracking)
• Challenge nonces (time-limited, single-use)

• Biometric data (never leaves device)
• Credential private keys (stored in device secure element)
• PRF secrets (computed in hardware, never exposed)
• Ability to authenticate without user’s biometric

​

What BioKey Protects Against

​

✅ Credential Theft via Server Breach

Server breach → Hashed passwords stolen → Offline cracking → Account takeover

Server breach → Public keys stolen → Useless without biometric → No account takeover

​

✅ Vendor Lock-In

Fingerprint → Unlocks → Private key in iCloud Keychain/Google Password Manager
                     → Vendor controls your identity

Fingerprint → Derives → Identity Key (deterministic, client-side)
                     → No vendor custody, no cloud sync required

​

✅ Replay Attacks

1. Server issues challenge: crypto.getRandomValues(32 bytes)
2. Challenge properties:
   - Single-use (deleted after first verification)
   - Time-limited (5-minute expiration)
   - Cryptographically random
3. Client authenticates with challenge
4. Server validates and invalidates challenge

• Challenge is already consumed (single-use)
• Challenge expires after 5 minutes
• Challenge tied to specific authentication flow

​

✅ Cross-Origin Abuse

const credential = await navigator.credentials.create({
  publicKey: {
    rp: { id: 'example.com' }, // Must match current hostname
    // ...
  }
})

• Browser enforces origin matching
• Credential is origin-bound at creation
• Prevents phishing via credential reuse

​

What BioKey Does NOT Protect Against

​

❌ Compromised Device

Compromised device → Malware intercepts WebAuthn API
                  → Malware exfiltrates Identity Key from localStorage
                  → Attacker may authenticate while device is unlocked

• Use device attestation (checks device integrity)
• Require biometric re-authentication for sensitive operations
• Implement anomaly detection (unusual IP, device fingerprint changes)
• Revoke compromised device’s public key server-side

​

❌ PIN Fallback

authenticatorSelection: {
  userVerification: 'required' // Can be satisfied by PIN
}

• Android: BiometricPrompt with BIOMETRIC_STRONG (blocks PIN)
• iOS: LAContext with biometryOnly policy

​

❌ Cross-Sensor Attacks

Sensor A (Device 1): Fingerprint → credentialId_A → Identity Key A
Sensor B (Device 2): Same finger → credentialId_B → Identity Key B

  Identity Key A ≠ Identity Key B

• User must enroll each device separately
• Lost device requires re-enrollment on new device
• No “bring your biometric to any device” portability

​

❌ Biometric Compromise

Password compromised → Change password → Security restored
Fingerprint compromised → Cannot change fingerprint → Permanent risk

• High-resolution photo of fingerprint (lifted from surface)
• 3D-printed finger (requires sophisticated attack)
• Deepfake face (for Face ID, requires liveness detection bypass)
• Coerced authentication (physical duress)

1. Liveness detection: Platform authenticators implement liveness checks (e.g., Face ID requires attention, fingerprints detect conductivity)
2. Multi-finger enrollment: Enroll backup fingers, revoke compromised finger’s credential
3. Server-side revocation: Delete public key from server to permanently invalidate compromised identity
4. Anomaly detection: Monitor authentication patterns (location, device, time)
5. Hybrid authentication: Require additional factor for high-risk operations (email OTP, recovery code)

​

V2 (PRF) vs V1 (rawId-HKDF) Security Comparison

// rawId is transmitted in WebAuthn responses
const credential = await navigator.credentials.create({...})

console.log(credential.rawId) // ArrayBuffer visible to client
// Server receives rawId during enrollment (in authenticatorAttestationResponse)

​

Challenge Security

​

Challenge Properties

​

Challenge Flow

Client                          Server
  |
  |-- GET /challenge ----------->| Generate challenge
  |                              | Store {challenge, timestamp}
  |<-- {challenge} --------------||
  |
  | [User scans fingerprint]
  |
  |-- POST /verify ------------->| Lookup challenge
  |   {userId, challenge}        | Check timestamp < 5 min
  |                              | Check not already used
  |                              | Lookup publicKey by userId
  |<-- {verified: true} ----------| Delete challenge

​

Server-Side Challenge Storage

// In-memory or database
const challenges = new Map()

app.get('/challenge', (req, res) => {
  const challenge = bufToHex(crypto.getRandomValues(new Uint8Array(32)))
  challenges.set(challenge, { createdAt: Date.now() })
  res.json({ challenge })
})

app.post('/verify', (req, res) => {
  const { userId, challenge } = req.body
  const stored = challenges.get(challenge)
  
  if (!stored) {
    return res.status(401).json({ error: 'Invalid or expired challenge' })
  }
  
  if (Date.now() - stored.createdAt > 5 * 60 * 1000) {
    challenges.delete(challenge)
    return res.status(401).json({ error: 'Challenge expired' })
  }
  
  challenges.delete(challenge) // Single-use
  
  // Verify user identity...
})

​

Data Privacy

​

What is Stored Where?

​

GDPR & Privacy Compliance

// Server-side
DELETE FROM identities WHERE userId = :userId

// Client-side
localStorage.removeItem('biokey_identity')

• Server stores only public keys (not biometrics, not private keys)
• No PII required (user ID can be pseudonymous)
• No tracking of authentication attempts (optional audit logs)

• Biometric used exclusively for authentication
• Identity Key derived for single purpose (user verification)
• No cross-service tracking (RP ID bound to origin)

​

Secure Implementation Checklist

• Always attempt V2 (PRF) first, fall back to V1 only if PRF unsupported
• Verify re-derived key matches stored publicKey before sending challenge to server
• Use HTTPS everywhere — BioKey requires secure context for WebAuthn
• Implement challenge expiration (5 minutes recommended)
• Enforce single-use challenges (delete after first verification)
• Validate RP ID matches your domain (prevents cross-origin abuse)
• Store Identity Key in localStorage (or IndexedDB), not sessionStorage
• Implement public key revocation (delete from server to disable identity)
• Monitor authentication anomalies (unusual IP, device changes, frequency)
• Consider device attestation for high-security applications
• Test on multiple platforms (Android, iOS, macOS, Windows)
• Handle PRF unavailability gracefully (clear fallback UX)
• Document multi-device enrollment for users
• Implement account recovery (email OTP, recovery codes for device loss)

​

Threat Model Summary

​

Next Steps