Security Model

IDToken’s security model is designed to resist the most common attack vectors against authentication systems while providing strong identity assurance through cryptographic and biometric verification.

Threat Model

Threat	Mitigation
OTP phishing	OTP is presented by the service — fake services cannot generate a matching OTP without the server HKDF master secret
Replay attack	Single-use sessions; timestamp checked within ±30s; session deleted after resolution
Brute force OTP	Max 3 verify attempts per session; session invalidated after 3 failures
Stolen mobile device	id3 face verification prevents unauthorized use (thief’s face won’t match VDS photo); tokenId revoked on loss report
Fake IDToken VDS	ECDSA P-256 signature + full PKI chain verification (VDSIC Governance to CA)
Compromised issuance station	Stations never call BioSeal directly — the IDToken server verifies ICAO SOD + Active Auth proof before forwarding to BioSeal; BioSeal credentials held only by the server. See Issuance Integrity.
Expired credential	exp field checked on every enroll and auth; CRL checked at enrollment
Man-in-the-middle	TLS mandatory; FCM data channel E2E encrypted; mutual authentication via OTP
Server response forgery	HMAC-SHA256 hash over response data (X.1280 §3.3 anti-forgery); relying party verifies hash and random nonce
JWT forgery	ECDSA P-256 signed; relying services verify with server public key via JWKS
OTP on lock screen	FCM uses data field only — OTP never rendered as a system notification
Private key extraction	iOS Secure Enclave / Android Keystore — hardware-bound, non-exportable
Revoked VDS	VDS fingerprint checked against VRL (VDS Revocation List) from Trust Service List
Scope inflation	Granted scopes cryptographically bound to ECDSA signature — cannot be modified after user approval

Cryptographic Design

Algorithms

Purpose	Algorithm	Key Size
VDS signatures	ECDSA P-256 (raw r|s)	256-bit
JWT signing	ES256 (ECDSA P-256)	256-bit
OTP derivation	HKDF-SHA256 + HMAC-SHA256	256-bit
Response verification	HMAC-SHA256	256-bit
Mobile device key	ECDSA P-256 (Secure Enclave / Keystore)	256-bit
SAML assertion signing	RSA-SHA256 or ECDSA-SHA256	2048-bit / 256-bit
SAML encryption	AES-256-CBC + RSA-OAEP	256-bit / 2048-bit
VDS payload encoding	MessagePack	—
VDS hash	SHA-256	256-bit

OTP Derivation

The OTP is session-scoped (not a global TOTP) to prevent phishing and replay:

1. Derive session key:
   session_key = HKDF-SHA256(
     ikm  = master_secret,
     salt = tokenId,
     info = sessionId
   )

2. Generate OTP:
   window = floor(now / 30_000)    // 30-second window
   raw    = HMAC-SHA256(session_key, window + sessionId)
   otp    = (parseInt(raw[0:8], "hex") % 10^6).padStart(6, "0")

3. Verification accepts window ±1 (±30s clock skew)

Signature Verification

The mobile app signs: sessionId|otp|timestamp|grantedScopes

The server verifies using the public key stored at enrollment. The granted scopes are part of the signed message, so they cannot be modified after biometric approval.

Non-Negotiable Rules

These rules apply across all components — server, mobile app, and BioSeal issuance:

• OTP is never stored in plaintext — only SHA-256(otp) is persisted
• OTP is never included in audit log details
• Server private key is never logged or returned in any API response
• App private key never leaves the secure element
• Sessions are invalidated immediately after first resolution
• POST /revoke requires a valid admin-scoped JWT
• All API traffic uses HTTPS / TLS 1.2+ in production
• Push notifications are delivered as silent data messages — never shown on lock screen
• CORS restricted to allowlisted origins
• Security headers enforced: CSP, HSTS, X-Frame-Options
• WebSocket connections authenticated via wsToken (HMAC-SHA256)

Rate Limiting

Endpoint	Limit	Window	Scope
POST /auth/initiate	10	1 minute	Per IP
POST /enroll	5	1 hour	Per IP
POST /auth/verify	3	Per session	Per sessionId

Audit Trail

All security-relevant events are logged to an immutable audit table in PostgreSQL:

• INSERT-only (UPDATE/DELETE blocked by PostgreSQL rules)
• Indexed on token_id, event_type, occurred_at
• OTP values never stored in plaintext
• Client IP and user agent captured per event
• Events include: ENROLL, AUTH_INITIATE, AUTH_APPROVE, AUTH_REJECT, REVOKE, VDS_VERIFY_OK/FAIL, SAML events, consent decisions, admin actions

Deployment Security

Layer	Mechanism
Edge	Reverse proxy with TLS termination, DDoS protection, and WebSocket proxying
Transport	TLS 1.3 (HTTPS + WSS)
Secrets	Private keys and master secrets injected at runtime — never baked into images
Key rotation	OTP master secret supports dual-active secrets during transition
Logging	Structured JSON logs piped to a log aggregator
Monitoring	Health endpoint polled by orchestrator and external uptime monitor