diff --git a/.planning/phases/01-architecture-threat-modeling/dfd.md b/.planning/phases/01-architecture-threat-modeling/dfd.md new file mode 100644 index 0000000..82f8597 --- /dev/null +++ b/.planning/phases/01-architecture-threat-modeling/dfd.md @@ -0,0 +1,314 @@ +# System Data Flow Diagram (DFD) with Trust Boundaries + +**Created:** 2026-02-14 +**Based on:** ARCH-01, 01-RESEARCH.md +**Confidence:** HIGH + +--- + +## Overview + +This document provides a comprehensive Data Flow Diagram (DFD) for Linux Hello, a Rust-based biometric authentication system. The DFD identifies all external entities, processes, data stores, and trust boundaries to establish the security context for threat modeling. + +--- + +## External Entities + +### Entry Points to the System + +| Entity | Description | Trust Level | Connection Method | +|--------|-------------|-------------|-------------------| +| **User (Face)** | End-user's face for biometric authentication | Untrusted | Physical camera capture | +| **PAM Module** | pam_linux_hello.so for system login | Untrusted | Unix socket IPC | +| **CLI Client** | linux-hello command-line tool | Untrusted | Unix socket IPC | +| **GNOME Settings** | GNOME Control Center integration | Untrusted | D-Bus (org.linuxhello) | +| **KDE Settings** | KDE System Settings module | Untrusted | D-Bus (org.linuxhello) | + +--- + +## Processes + +### Core Process: linux-hello-daemon + +The central authentication service comprising the following internal modules: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ linux-hello-daemon │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Core Service │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ +│ │ │ Camera │ │ Detection │ │ Matching │ │ │ +│ │ │ Module │──│ Module │──│ Service │ │ │ +│ │ │ (V4L2) │ │ (ONNX/Hybrid)│ │ (Cosine Sim) │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │ +│ │ │ │ │ │ │ +│ │ └────────────────┼──────────────────┘ │ │ +│ │ ▼ │ │ +│ │ ┌─────────────────────────────────────────────────┐ │ │ +│ │ │ Anti-Spoofing / PAD │ │ │ +│ │ │ (IR Liveness, Depth, Texture, Blink, Move) │ │ │ +│ │ └─────────────────────────────────────────────────┘ │ │ +│ │ │ │ │ +│ │ ┌─────────────────────────────────────────────────┐ │ │ +│ │ │ Secure Memory / IPC Handler │ │ │ +│ │ │ (mlock, zeroize, SO_PEERCRED, rate limit) │ │ │ +│ │ └─────────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ IPC Server (Unix Socket) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Data Stores + +### 1. Template Storage + +- **Location:** `~/.local/share/linux-hello/` +- **Contents:** Encrypted face templates (AES-256-GCM) +- **Trust Level:** Trusted (encrypted at rest) +- **Access:** Daemon only (user-level) + +### 2. TPM Key Storage + +- **Location:** TPM 2.0 hardware (or software fallback) +- **Contents:** Encryption keys bound to TPM +- **Trust Level:** Trusted (hardware security) +- **Access:** Via tpm2-tss library + +### 3. Configuration Files + +- **Location:** `/etc/linux-hello/` +- **Contents:** System configuration, policies +- **Trust Level:** Admin-only (0o600) +- **Access:** Root/Daemon + +--- + +## Trust Boundaries + +### TB1: Unix Socket IPC + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ External Entities │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────┐ │ +│ │ User │ │ PAM │ │ CLI │ │ GNOME │ │ KDE │ │ +│ │ (Face) │ │ Module │ │ Client │ │Settings │ │Settings│ │ +│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └───┬───┘ │ +└───────┼────────────┼────────────┼────────────┼────────────┼─────┘ + │ │ │ │ │ + │ │ │ │ │ + ▼ ▼ ▼ ▼ ▼ +┌───────────────────────────────────────────────────────────────────┐ +│ TRUST BOUNDARY 1 │ +│ Unix Socket IPC │ +│ (/run/linux-hello/auth.sock) │ +│ │ +│ Controls: │ +│ - SO_PEERCRED for UID verification │ +│ - Socket permissions: 0o600 (owner only) │ +│ - Rate limiting: 10 requests/second │ +│ - Message size limit: 64KB │ +└────────────────────────────┬──────────────────────────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ IPC Handler │ + │ (Validates, │ + │ authorizes) │ + └────────┬────────┘ +``` + +### TB2: Encrypted Storage / TPM Interface + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ Daemon Internal │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ TRUST BOUNDARY 2 │ │ +│ │ Encrypted Storage / TPM Interface │ │ +│ │ │ │ +│ │ Controls: │ │ +│ │ - AES-256-GCM template encryption │ │ +│ │ - PBKDF2-HMAC-SHA256 (600k iterations) │ │ +│ │ - TPM key binding (or software fallback) │ │ +│ │ - Secure memory: mlock + zeroize │ │ +│ └──────────────────────────┬──────────────────────────────────┘ │ +└─────────────────────────────┼────────────────────────────────────┘ + │ + ┌─────────────────────┼─────────────────────┐ + ▼ ▼ ▼ +┌───────────────┐ ┌───────────────┐ ┌─────────────────┐ +│ Template │ │ TPM │ │ Config │ +│ Storage │ │ Key │ │ Files │ +│ (AES-256-GCM) │ │ Storage │ │ (/etc/) │ +└───────────────┘ │ (Hardware) │ └─────────────────┘ + └───────────────┘ +``` + +### TB3: Hardware Interfaces + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ Hardware Layer │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ TRUST BOUNDARY 3 │ │ +│ │ Hardware Interfaces │ │ +│ │ │ │ +│ │ Controls: │ │ +│ │ - V4L2 frame validation │ │ +│ │ - IR emitter control │ │ +│ │ - TPM command validation │ │ +│ │ - Device permissions │ │ +│ └──────────────────────────┬──────────────────────────────────┘ │ +└─────────────────────────────┼────────────────────────────────────┘ + ┌─────────────────────┼─────────────────────┐ + ▼ ▼ +┌───────────────┐ ┌───────────────┐ +│ V4L2 │ │ TPM2 │ +│ Camera │ │ Device │ +│ (IR + RGB) │ │ (Hardware) │ +└───────────────┘ └───────────────┘ +``` + +### TB4: D-Bus Interface + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ Settings Applications │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ GNOME │ │ KDE │ │ +│ │ Settings │ │ Settings │ │ +│ └──────┬──────┘ └──────┬──────┘ │ +└─────────┼────────────────┼───────────────────────────────────────┘ + │ │ + ▼ ▼ +┌───────────────────────────────────────────────────────────────────┐ +│ TRUST BOUNDARY 4 │ +│ D-Bus │ +│ (org.linuxhello) │ +│ │ +│ Controls: │ +│ - D-Bus policy configuration │ +│ - Method call validation │ +│ - No secrets exposed via D-Bus │ +└────────────────────────────┬──────────────────────────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ D-Bus Service │ + │ Handler │ + └────────┬────────┘ +``` + +### TB5: System Integration + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ System Layer │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ TRUST BOUNDARY 5 │ │ +│ │ System Integration │ │ +│ │ │ │ +│ │ Components: │ │ +│ │ - systemd service (linux-hello-daemon.service) │ │ +│ │ - PAM module execution context │ │ +│ │ - Privilege separation │ │ +│ │ - Session management │ │ +│ │ │ │ +│ │ Controls: │ │ +│ │ - Service user: linux-hello (unprivileged) │ │ +│ │ - PAM conversation validation │ │ +│ │ - systemd security features │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +└───────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Data Flows + +### Authentication Flow + +``` +1. User presents face to camera + │ + ▼ +2. V4L2 captures frame (IR + RGB) + │ TB3: Hardware Interface + ▼ +3. Detection module processes frame (ONNX) + │ TB2: Internal processing + ▼ +4. Anti-spoofing validates liveness + │ TB2: PAD checks + ▼ +5. Embedding extraction (or placeholder) + │ TB2: Internal processing + ▼ +6. Template matching (cosine similarity) + │ TB2: Secure comparison + ▼ +7. IPC response via Unix socket + │ TB1: IPC boundary + ▼ +8. Result returned to PAM/CLI +``` + +### Template Storage Flow + +``` +1. Enrollment triggered (Settings app via D-Bus) + │ TB4: D-Bus + ▼ +2. IPC call to daemon + │ TB1: IPC + ▼ +3. Capture face template + │ TB2: Processing + ▼ +4. Encrypt template (AES-256-GCM) + │ TB2: Encryption boundary + ▼ +5. Store in ~/.local/share/linux-hello/ + │ TB2: Storage boundary + ▼ +6. Optional: Bind to TPM + │ TB2: TPM boundary +``` + +--- + +## Trust Boundary Summary + +| Boundary | Location | Trust Transition | Key Controls | +|----------|----------|------------------|---------------| +| TB1 | Unix Socket IPC | Untrusted → Daemon | SO_PEERCRED, rate limit, 0o600 | +| TB2 | Encrypted Storage/TPM | Daemon → Trusted Storage | AES-256-GCM, PBKDF2, TPM | +| TB3 | Hardware Interfaces | Kernel → Hardware | V4L2 validation, device perms | +| TB4 | D-Bus | Untrusted → Daemon | D-Bus policy, caller validation | +| TB5 | System Integration | System → Service | systemd, PAM context | + +--- + +## References + +- Architecture: CLAUDE.md sections "Architecture" and "Communication Flow" +- IPC Security: `linux-hello-daemon/src/ipc.rs` +- Template Storage: `linux-hello-daemon/src/secure_template_store.rs` +- TPM Integration: `linux-hello-daemon/src/tpm.rs` +- ONNX Models: `linux-hello-daemon/src/onnx/` + +--- + +*This DFD follows OWASP Threat Dragon methodology and supports STRIDE threat analysis.*