feat(01-01): create system DFD with trust boundaries
- Documents all external entities: User (face), PAM module, CLI, GNOME/KDE settings - Describes linux-hello-daemon internal modules: camera, detection, matching, anti-spoofing, secure memory - Enumerates data stores: template storage, TPM key storage, config files - Defines 5 trust boundaries: Unix Socket IPC, Encrypted Storage/TPM, Hardware Interfaces, D-Bus, System Integration - Includes ASCII diagrams following OWASP Threat Dragon methodology
This commit is contained in:
314
.planning/phases/01-architecture-threat-modeling/dfd.md
Normal file
314
.planning/phases/01-architecture-threat-modeling/dfd.md
Normal file
@@ -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.*
|
||||
Reference in New Issue
Block a user