docs(01-02): map security controls to threats

- Created comprehensive security control mapping document - Documented IPC, cryptographic, memory, authorization, and PAD controls - Each control includes implementation location and effectiveness rating - Included gap analysis identifying missing mitigations - Links STRIDE threats to corresponding security controls
2026-02-14 10:16:17 +01:00
parent 0f018ba4fe
commit 8cbb5adc2a
1 changed files with 384 additions and 0 deletions
--- a/.planning/phases/01-architecture-threat-modeling/security-controls.md
+++ 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.*