diff --git a/.planning/phases/01-architecture-threat-modeling/security-controls.md b/.planning/phases/01-architecture-threat-modeling/security-controls.md new file mode 100644 index 0000000..6a081cb --- /dev/null +++ b/.planning/phases/01-architecture-threat-modeling/security-controls.md @@ -0,0 +1,384 @@ +# Security Control Mapping + +**Created:** 2026-02-14 +**Based on:** ARCH-04, STRIDE Threats, DFD +**Confidence:** HIGH + +--- + +## Overview + +This document maps existing and planned security controls to the threats identified in the STRIDE threat analysis. Each control is documented with its implementation location, threats mitigated, and effectiveness rating. + +--- + +## 1. IPC Security Controls + +### 1.1 SO_PEERCRED Credential Validation + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Authentication | +| **Implementation** | `linux-hello-daemon/src/ipc.rs` | +| **Threats Mitigated** | UID spoofing via socket, Spoofing threats | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Uses `SO_PEERCRED` socket option to retrieve peer credentials +- Validates UID/GID before processing any request +- Rejects connections from untrusted UIDs + +### 1.2 Unix Socket Permissions + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Access Control | +| **Implementation** | systemd service, socket activation | +| **Threats Mitigated** | Socket injection, unauthorized access | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Socket path: `/run/linux-hello/auth.sock` +- Permissions: `0o600` (owner read/write only) +- Ownership: `root:linux-hello` + +### 1.3 Rate Limiting + +| Attribute | Value | +|-----------|-------| +| **Control Type** | DoS Prevention | +| **Implementation** | `linux-hello-daemon/src/ipc.rs` | +| **Threats Mitigated** | Rate limit exhaustion, DoS threats | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Limit: 10 requests per second per UID +- Implements token bucket algorithm +- Gradual backoff on limit exceeded + +### 1.4 Message Size Limits + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Input Validation | +| **Implementation** | `linux-hello-daemon/src/ipc.rs` | +| **Threats Mitigated** | Buffer overflow, memory exhaustion | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Maximum message size: 64KB +- Validated before processing + +--- + +## 2. Cryptographic Controls + +### 2.1 AES-256-GCM Template Encryption + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Data at Rest Encryption | +| **Implementation** | `linux-hello-daemon/src/secure_template_store.rs` | +| **Threats Mitigated** | Template exposure, template tampering | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- AES-256-GCM authenticated encryption +- Unique IV per template +- Authenticated decryption (detects tampering) + +### 2.2 PBKDF2-HMAC-SHA256 Key Derivation + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Key Derivation | +| **Implementation** | `linux-hello-daemon/src/tpm.rs`, secure_template_store.rs | +| **Threats Mitigated** | Brute-force attacks on stored keys | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Iterations: 600,000 +- Salt: Unique per installation +- Output: 256-bit key + +### 2.3 TPM Key Binding + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Hardware Security | +| **Implementation** | `linux-hello-daemon/src/tpm.rs` | +| **Threats Mitigated** | Template extraction, key compromise | +| **Effectiveness** | VERY HIGH (hardware) | +| **Status** | Implemented (with software fallback) | + +**Details:** +- Keys bound to TPM 2.0 hardware +- Requires TPM auth value for operations +- Software fallback available (reduced security) + +### 2.4 Constant-Time Comparison + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Timing Attack Prevention | +| **Implementation** | `linux-hello-daemon/src/matching.rs` | +| **Threats Mitigated** | Timing attacks on template matching | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Uses `subtle` crate for constant-time operations +- Fixed comparison duration regardless of match + +--- + +## 3. Memory Security Controls + +### 3.1 mlock for Sensitive Data + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Memory Protection | +| **Implementation** | `linux-hello-daemon/src/secure_memory.rs` | +| **Threats Mitigated** | Swapping sensitive data to disk | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Uses `mlock()` to lock sensitive pages in RAM +- Prevents paging to swap + +### 3.2 zeroize for Automatic Wiping + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Memory Protection | +| **Implementation** | `linux-hello-daemon/src/secure_memory.rs` | +| **Threats Mitigated** | Sensitive data left in memory | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Uses `zeroize` crate for automatic memory wiping +- `SecureBytes` and `SecureEmbedding` types auto-zeroize on drop + +### 3.3 SecureBytes Type + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Data Handling | +| **Implementation** | `linux-hello-daemon/src/secure_memory.rs` | +| **Threats Mitigated** | Memory exposure, data leakage | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Wraps byte vectors with secure handling +- Automatic zeroization +- No `Debug` or `Display` implementations (prevents accidental logging) + +### 3.4 SecureEmbedding Type + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Data Handling | +| **Implementation** | `linux-hello-daemon/src/secure_memory.rs` | +| **Threats Mitigated** | Embedding data leakage in memory | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Specialized type for biometric embeddings +- Automatic secure memory handling + +--- + +## 4. Authorization Controls + +### 4.1 D-Bus Policy Enforcement + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Access Control | +| **Implementation** | `dist/linux-hello.conf` (D-Bus policy) | +| **Threats Mitigated** | D-Bus method injection, unauthorized settings | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- D-Bus policy configuration in `dist/` +- Restricts method calls to authorized callers +- No secrets exposed via D-Bus + +### 4.2 PAM Session Validation + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Access Control | +| **Implementation** | `pam-module/pam_linux_hello.c` | +| **Threats Mitigated** | PAM bypass, unauthorized login | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Validates PAM conversation +- Returns proper error codes +- Secure error message handling + +### 4.3 Peer Credential Verification + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Authentication | +| **Implementation** | `linux-hello-daemon/src/ipc.rs` | +| **Threats Mitigated** | UID spoofing, unauthorized access | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Verifies peer credentials on every request +- Maps UIDs to authorized users + +--- + +## 5. Anti-Spoofing / PAD Controls + +### 5.1 IR Liveness Detection + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Presentation Attack Detection | +| **Implementation** | `linux-hello-daemon/src/anti_spoofing.rs` | +| **Threats Mitigated** | Photo attacks, video replay, fake camera | +| **Effectiveness** | MEDIUM-HIGH | +| **Status** | Implemented | + +**Details:** +- Validates IR signature from camera +- Requires IR camera hardware +- Combined with other PAD signals + +### 5.2 Frame Format Validation + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Input Validation | +| **Implementation** | `linux-hello-daemon/src/camera/` | +| **Threats Mitigated** | Malformed frames, injection attacks | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Validates V4L2 frame format +- Checks resolution, color space +- Rejects malformed frames + +### 5.3 Texture Analysis + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Presentation Attack Detection | +| **Implementation** | `linux-hello-daemon/src/anti_spoofing.rs` | +| **Threats Mitigated** | 3D mask attacks, silicone faces | +| **Effectiveness** | MEDIUM | +| **Status** | Implemented (ONNX feature) | + +**Details:** +- Analyzes surface texture +- Detects artificial materials +- Requires ONNX model + +### 5.4 Blink/Movement Detection + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Presentation Attack Detection | +| **Implementation** | `linux-hello-daemon/src/anti_spoofing.rs` | +| **Threats Mitigated** | Static photo attacks | +| **Effectiveness** | MEDIUM | +| **Status** | Implemented (ONNX feature) | + +**Details:** +- Requires multiple frames +- Detects eye movement/blinking +- Liveness indicator + +--- + +## 6. Configuration Security Controls + +### 6.1 Config File Permissions + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Access Control | +| **Implementation** | Installation scripts, systemd | +| **Threats Mitigated** | Config tampering, privilege escalation | +| **Effectiveness** | HIGH | +| **Status** | Implemented | + +**Details:** +- Location: `/etc/linux-hello/` +- Permissions: `0o600` (root only) +- No secrets stored + +### 6.2 Environment Variable Validation + +| Attribute | Value | +|-----------|-------| +| **Control Type** | Input Validation | +| **Implementation** | `linux-hello-daemon/src/config.rs` | +| **Threats Mitigated** | Environment injection | +| **Effectiveness** | MEDIUM | +| **Status** | Implemented | + +**Details:** +- Validates all environment variables +- Sanitizes input +- No direct use in security-critical paths + +--- + +## Gap Analysis + +### Identified Gaps + +| Gap | Severity | Recommended Action | Priority | +|-----|----------|-------------------|----------| +| Immutable audit logging | MEDIUM | Implement append-only logging with syslog | Future | +| Model file integrity verification | MEDIUM | Add file hash verification at load time | Future | +| Anti-replay for templates | LOW | Add freshness checks to templates | Future | +| Hardware security key requirement | LOW | Make TPM mandatory for production | Future | + +### Controls by STRIDE Category + +| STRIDE Category | Controls Applied | Coverage | +|-----------------|------------------|----------| +| Spoofing | SO_PEERCRED, socket permissions, D-Bus policy | HIGH | +| Tampering | AES-256-GCM, file permissions, frame validation | HIGH | +| Repudiation | Logging (partial), syslog integration | MEDIUM | +| Information Disclosure | Secure memory, encryption, constant-time | HIGH | +| Denial of Service | Rate limiting, resource limits, timeouts | HIGH | +| Elevation of Privilege | Privilege separation, PAM validation | HIGH | + +--- + +## References + +- STRIDE Analysis: `.planning/phases/01-architecture-threat-modeling/stride-threats.md` +- DFD: `.planning/phases/01-architecture-threat-modeling/dfd.md` +- Attack Surface: `.planning/phases/01-architecture-threat-modeling/attack-surface.md` +- IPC Implementation: `linux-hello-daemon/src/ipc.rs` +- Secure Memory: `linux-hello-daemon/src/secure_memory.rs` +- Anti-Spoofing: `linux-hello-daemon/src/anti_spoofing.rs` +- TPM: `linux-hello-daemon/src/tpm.rs` + +--- + +*This security control mapping supports ARCH-04 and identifies gaps for future enhancement.*