.. include:: ../Includes.rst.txt .. _security: ======== Security ======== This chapter documents the security model and countermeasures implemented by the extension. WebAuthn security model ======================= WebAuthn (Web Authentication) is a W3C standard that uses public-key cryptography for authentication: - During **registration**, the authenticator generates a key pair. The private key stays on the device; the public key is sent to the server. - During **authentication**, the server sends a random challenge. The authenticator signs it with the private key. The server verifies the signature with the stored public key. This provides inherent protection against: - **Phishing** -- The credential is bound to the origin (domain). It cannot be used on a different domain, even if the user is tricked into visiting one. - **Credential theft** -- The private key never leaves the authenticator device. Even if the server database is compromised, attackers cannot impersonate users. - **Replay attacks** -- Each authentication uses a unique challenge, and the signature counter detects cloned authenticators. HMAC-signed challenge tokens ============================= Challenge tokens are the core mechanism preventing unauthorized authentication attempts. Each token contains: 1. A **32-byte random challenge** generated by ``random_bytes(32)`` 2. An **expiration timestamp** (configurable TTL, default 120 seconds) 3. A **single-use nonce** (32 hex characters from ``random_bytes(16)``) These components are concatenated and signed with **HMAC-SHA256** using the TYPO3 encryption key as the signing secret. The final token is base64-encoded. Security properties: - **Integrity** -- The HMAC ensures the token cannot be tampered with. Verification uses ``hash_equals()`` for constant-time comparison, preventing timing side-channel attacks. - **Freshness** -- The expiration timestamp prevents use of stale tokens. - **Single-use** -- The nonce is stored in a TYPO3 cache and consumed on first use. Subsequent uses of the same token are rejected. - **Signing key requirements** -- The TYPO3 encryption key must be at least 32 characters. The extension throws a clear error if this requirement is not met. Nonce replay protection ======================= Each challenge token contains a nonce that is stored in a TYPO3 cache (``SimpleFileBackend``) upon creation. During verification: 1. The nonce is looked up in the cache. 2. If found, it is immediately invalidated (removed from cache). 3. If not found (already used or expired), the verification fails. This ensures each challenge token can only be used exactly once, even if an attacker intercepts and replays it. The nonce cache has a TTL slightly longer than the challenge TTL (extra 60 seconds buffer) to handle clock skew. Rate limiting ============= Per-endpoint rate limiting -------------------------- Each API endpoint tracks request counts per IP address. When the configured threshold (:confval:`rateLimitMaxAttempts`, default: 10) is exceeded within the time window (:confval:`rateLimitWindowSeconds`, default: 300 seconds), the endpoint returns HTTP 429 (Too Many Requests). This limits automated attacks against the login and registration endpoints. Account lockout --------------- Failed authentication attempts are counted per username/IP combination. When the failure count reaches the configured threshold (:confval:`lockoutThreshold`, default: 5), the account is locked for the configured duration (:confval:`lockoutDurationSeconds`, default: 900 seconds / 15 minutes). Lockout entries are tagged with the username, enabling administrators to unlock specific users via the admin API without affecting other users. On successful authentication, the lockout counter is reset. User enumeration prevention ============================ The login endpoints return identical error responses regardless of whether a username exists. Additionally, requests for non-existent users include a randomized delay (50--150ms via ``usleep(random_int(50000, 150000))``) to normalize response timing and prevent timing-based enumeration. The authentication service logs only hashed usernames (``hash('sha256', $username)``) for unknown user attempts. Credential ownership verification ================================== Before any credential mutation (rename, remove), the extension verifies that the credential belongs to the requesting user. This prevents unauthorized users from modifying other users' credentials, even if they know the credential UID. Admin operations verify admin status via ``BackendUserAuthentication::isAdmin()`` and record the admin's UID in audit trails. Last credential protection ========================== When :confval:`disablePasswordLogin` is enabled, users cannot remove their last remaining passkey. This prevents users from accidentally locking themselves out of the system when password login is disabled. Signature counter validation ============================ The WebAuthn signature counter (``sign_count``) is updated after each successful authentication. The ``web-auth/webauthn-lib`` validates that the counter is strictly increasing, which helps detect cloned authenticators. Soft delete and revocation ========================== The extension supports two credential removal mechanisms: - **Soft delete** (user-initiated): Sets ``deleted = 1``. The credential record is preserved in the database but excluded from all queries. - **Revocation** (admin-initiated): Sets ``revoked_at`` and ``revoked_by`` without setting the delete flag. Revoked credentials are explicitly checked and rejected during authentication, providing a clear audit trail of who revoked the credential and when. Label sanitization ================== User-provided passkey labels are sanitized: - Trimmed of leading/trailing whitespace - Truncated to 128 characters maximum (``mb_substr``) - Empty labels default to "Passkey"