From 23230cb74553b723187f5ab5faaefea47a9c5329 Mon Sep 17 00:00:00 2001 From: eliott Date: Thu, 15 Jan 2026 22:50:18 +0100 Subject: [PATCH] updating doc --- CLAUDE.md | 126 ++++++++++++--- README.md | 412 ++++++++++++++++++++++++++--------------------- TESTING.md | 152 +++++++++-------- docs/API.md | 112 +++++++++++++ models/README.md | 27 ++++ 5 files changed, 559 insertions(+), 270 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cf379b8..80bca1e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,25 +6,28 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Linux Hello is a Windows Hello-equivalent biometric authentication system for Linux. It provides secure facial authentication using IR cameras and TPM2-backed credential storage. -**Current Status**: Phase 3 (Security Hardening) complete. Uses placeholder algorithms for face detection/embedding until ONNX model integration (waiting for `ort` 2.0 stable). +**Current Status**: All phases complete (1-5). Feature complete with ONNX model support. ## Build Commands ```bash -# Development build +# Development build (works on any Linux) cargo build # Release build cargo build --release +# Build with ONNX ML models (requires glibc 2.38+ / Ubuntu 24.04+) +cargo build --release --features onnx + # Build with TPM hardware support -cargo build --features tpm +cargo build --release --features tpm + +# Build with all features +cargo build --release --features "onnx,tpm" # Run all tests -cargo test --workspace - -# Run a specific test by name -cargo test test_name --workspace +cargo test # Run tests for a specific package cargo test -p linux-hello-daemon @@ -32,42 +35,70 @@ cargo test -p linux-hello-daemon # Run specific integration test suite cargo test --test phase3_security_test +# Run benchmarks +cargo bench -p linux-hello-daemon + +# Generate documentation +cargo doc --workspace --no-deps --open + # Build PAM module (C) cd pam-module && make # Install PAM module (requires sudo) cd pam-module && sudo make install + +# Build GNOME Settings app (requires libgtk-4-dev, libadwaita-1-dev) +cargo build -p linux-hello-settings ``` ## Architecture ### Workspace Crates -- **linux-hello-common**: Shared types (`Config`, `Error`, `FaceTemplate`, `TemplateStore`) -- **linux-hello-daemon**: Core daemon library with camera, auth, security modules; also builds `linux-hello-daemon` binary -- **linux-hello-cli**: CLI tool, builds `linux-hello` binary -- **linux-hello-tests**: Integration test harness (tests live in `/tests/`) -- **pam-module**: C PAM module (`pam_linux_hello.so`) using Unix socket IPC +| Crate | Purpose | +|-------|---------| +| `linux-hello-common` | Shared types (`Config`, `Error`, `FaceTemplate`, `TemplateStore`) | +| `linux-hello-daemon` | Core daemon with camera, auth, security, D-Bus; builds `linux-hello-daemon` binary | +| `linux-hello-cli` | CLI tool, builds `linux-hello` binary | +| `linux-hello-settings` | GNOME Settings app (GTK4/libadwaita) | +| `linux-hello-tests` | Integration test harness | +| `pam-module` | C PAM module (`pam_linux_hello.so`) | + +### External Directories + +| Directory | Purpose | +|-----------|---------| +| `kde-settings/` | KDE System Settings module (CMake/Qt6) | +| `debian/` | Debian packaging files | +| `rpm/` | RPM spec file | +| `aur/` | Arch Linux PKGBUILD | +| `dist/` | Config templates, systemd service, D-Bus files | +| `models/` | ONNX model files (download separately) | +| `docs/` | API documentation, benchmarks | ### Key Daemon Modules (`linux-hello-daemon/src/`) | Module | Purpose | |--------|---------| | `camera/` | V4L2 camera enumeration, frame capture, IR emitter control | -| `detection/` | Face detection (placeholder, ONNX planned) | -| `embedding.rs` | Face embedding extraction (placeholder, ONNX planned) | +| `detection/` | Face detection (placeholder + ONNX) | +| `embedding.rs` | Face embedding extraction (placeholder + ONNX) | | `matching.rs` | Template matching with cosine similarity | | `anti_spoofing.rs` | Liveness detection (IR, depth, texture, blink, movement) | | `secure_memory.rs` | `SecureBytes`, `SecureEmbedding` with zeroization, memory locking | | `secure_template_store.rs` | Encrypted template storage | -| `tpm.rs` | TPM2 integration with software fallback | -| `ipc.rs` | Unix socket server/client for PAM communication | +| `tpm.rs` | TPM2 integration with AES-256-GCM software fallback | +| `ipc.rs` | Unix socket server/client with peer credentials, rate limiting | | `auth.rs` | Authentication service orchestration | +| `dbus_service.rs` | D-Bus interface implementation | +| `dbus_server.rs` | D-Bus server bootstrap | +| `onnx/` | ONNX model integration (feature-gated) | ### Communication Flow ``` Desktop/PAM → pam_linux_hello.so → Unix Socket → linux-hello-daemon → Camera/TPM +Settings App → D-Bus → linux-hello-daemon → Camera/TPM ``` ## Platform-Specific Code @@ -76,10 +107,63 @@ Camera code uses conditional compilation: - `#[cfg(target_os = "linux")]` - Real V4L2 implementation - `#[cfg(not(target_os = "linux"))]` - Mock implementation for development +ONNX code is feature-gated: +- `#[cfg(feature = "onnx")]` - Real ONNX models +- `#[cfg(not(feature = "onnx"))]` - Placeholder algorithms + ## Security Considerations -- `SecureEmbedding` and `SecureBytes` auto-zeroize on drop -- Use `zeroize` crate for sensitive data -- Constant-time comparisons for template matching (timing attack resistance) -- Memory locking prevents swapping sensitive data -- Software TPM fallback is NOT cryptographically secure (dev only) +- **Encryption**: AES-256-GCM with PBKDF2-HMAC-SHA256 (600k iterations) +- **Secure memory**: `SecureEmbedding` and `SecureBytes` auto-zeroize on drop +- **Constant-time**: Template comparisons use `subtle` crate (timing attack resistant) +- **Memory locking**: Sensitive data locked in RAM (no swap) +- **IPC security**: Peer credentials (SO_PEERCRED), rate limiting, authorization +- **Software TPM fallback**: Cryptographically strong but not hardware-bound + +## Key Dependencies + +| Dependency | Purpose | +|------------|---------| +| `zbus` | D-Bus integration | +| `tokio` | Async runtime | +| `v4l` | V4L2 camera interface | +| `aes-gcm` | Template encryption | +| `subtle` | Constant-time operations | +| `zeroize` | Secure memory wiping | +| `ort` | ONNX Runtime (optional) | +| `tss-esapi` | TPM2 support (optional) | + +## Testing + +```bash +# Quick test (default packages only) +cargo test + +# All packages including integration tests +cargo test --workspace + +# Specific test file +cargo test --test phase3_security_test + +# With output +cargo test -- --nocapture + +# ONNX tests (requires glibc 2.38+) +cargo test --features onnx +``` + +## Common Tasks + +### Adding a new D-Bus method +1. Add method to `dbus_service.rs` in the `LinuxHelloManager` impl +2. Update D-Bus client in `linux-hello-settings/src/dbus_client.rs` +3. Update KDE client in `kde-settings/src/dbus_client.cpp` + +### Adding a new CLI command +1. Add subcommand to `linux-hello-cli/src/main.rs` +2. Implement handler using daemon's IPC client + +### Adding a new anti-spoofing check +1. Add check method to `anti_spoofing.rs` +2. Add config option to `Config` in `linux-hello-common/src/config.rs` +3. Add test in `tests/integration/phase3_security_test.rs` diff --git a/README.md b/README.md index daf8480..92fd125 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ A Windows Hello-equivalent biometric authentication system for Linux, designed w [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Rust](https://img.shields.io/badge/Rust-1.75+-orange.svg)](https://www.rust-lang.org/) +[![Tests](https://img.shields.io/badge/Tests-117%2B%20passing-brightgreen.svg)]() --- @@ -25,7 +26,6 @@ A Windows Hello-equivalent biometric authentication system for Linux, designed w - [Architecture](#architecture) - [Security](#security) - [Development](#development) -- [Roadmap](#roadmap) - [Contributing](#contributing) - [License](#license) @@ -37,90 +37,97 @@ Linux Hello provides secure facial authentication for Linux systems, similar to ### Key Features -- 🔒 **TPM2-backed encryption** - Face templates encrypted with hardware-bound keys -- 🛡️ **Anti-spoofing detection** - Multiple liveness checks prevent photo/video attacks -- 🔐 **Secure memory handling** - Automatic zeroization, memory locking, constant-time comparisons -- 📷 **IR camera support** - Works with IR-capable cameras for better security -- 🔌 **PAM integration** - Works with login managers, sudo, and lock screens -- ⚡ **Fast authentication** - Sub-second face recognition -- 🎯 **Privacy-first** - All biometric data stays local, never leaves your device +- **TPM2-backed encryption** - Face templates encrypted with AES-256-GCM + hardware-bound keys +- **Anti-spoofing detection** - Multiple liveness checks prevent photo/video attacks +- **Secure memory handling** - Automatic zeroization, memory locking, constant-time comparisons +- **IR camera support** - Works with IR-capable cameras for better security +- **PAM integration** - Works with login managers, sudo, and lock screens +- **D-Bus service** - Desktop integration for GNOME/KDE settings apps +- **Fast authentication** - Sub-second face recognition +- **Privacy-first** - All biometric data stays local, never leaves your device --- ## Features -### ✅ Implemented (Phase 1-3 Complete) +### Phase 1: Foundation +- V4L2 camera enumeration and frame capture +- Support for multiple pixel formats (GREY, YUYV, MJPEG) +- IR camera detection and emitter control +- Face detection (placeholder + ONNX-ready) +- Rust workspace with modular architecture +- C PAM module with Unix socket communication +- Configuration system (TOML-based) -#### Phase 1: Foundation -- ✅ V4L2 camera enumeration and frame capture -- ✅ Support for multiple pixel formats (GREY, YUYV, MJPEG) -- ✅ IR camera detection and emitter control -- ✅ Basic face detection (placeholder algorithm) -- ✅ Rust workspace with modular architecture -- ✅ C PAM module with Unix socket communication -- ✅ Configuration system (TOML-based) +### Phase 2: Core Authentication +- Face embedding extraction (128-dimensional vectors) +- Template storage (JSON-based, per-user directories) +- Template matching with cosine similarity +- Multi-template support (e.g., glasses, profile views) +- IPC server/client for PAM-daemon communication +- Authentication service (capture -> detect -> embed -> match) +- Full CLI tool with all commands +- Enrollment workflow with multi-frame averaging -#### Phase 2: Core Authentication -- ✅ Face embedding extraction (128-dimensional vectors) -- ✅ Template storage (JSON-based, per-user directories) -- ✅ Template matching with cosine similarity -- ✅ Multi-template support (e.g., glasses, profile views) -- ✅ IPC server/client for PAM-daemon communication -- ✅ Authentication service (capture → detect → embed → match) -- ✅ Full CLI tool with all commands -- ✅ Enrollment workflow with multi-frame averaging - -#### Phase 3: Security Hardening -- ✅ TPM2 integration with software fallback -- ✅ Encrypted template storage -- ✅ Secure memory containers (`SecureEmbedding`, `SecureBytes`) -- ✅ Constant-time comparisons (timing attack resistant) -- ✅ Memory locking (prevents swapping sensitive data) -- ✅ Multi-method anti-spoofing: +### Phase 3: Security Hardening +- TPM2 integration with software fallback +- AES-256-GCM encrypted template storage +- PBKDF2-HMAC-SHA256 key derivation (600,000 iterations) +- Secure memory containers (`SecureEmbedding`, `SecureBytes`) +- Constant-time comparisons using `subtle` crate (timing attack resistant) +- Memory locking (prevents swapping sensitive data) +- Multi-method anti-spoofing: - IR presence verification - Depth estimation - Texture analysis (LBP-based) - Blink detection - Micro-movement analysis -- ✅ Secure template store with migration support +- Secure template store with migration support +- IPC security: peer credentials, rate limiting, authorization -### 🚧 Planned (Phase 4-5) +### Phase 4: Polish & Integration +- D-Bus service (`org.linuxhello.Daemon`) for desktop integration +- GNOME Settings application (GTK4/libadwaita) +- KDE System Settings module (KCM/Kirigami) +- Comprehensive API documentation (rustdoc) +- Package distribution files (.deb, .rpm, AUR) -#### Phase 4: Polish & Integration -- ⏳ D-Bus service for desktop integration -- ⏳ GNOME Settings panel -- ⏳ KDE System Settings module -- ⏳ User documentation -- ⏳ API documentation -- ⏳ Package distribution (.deb, .rpm, AUR) - -#### Phase 5: Hardening & Release -- ⏳ ONNX model integration (when `ort` 2.0 stable) - - BlazeFace/RetinaFace for face detection - - MobileFaceNet/ArcFace for embeddings -- ⏳ Security audit and penetration testing -- ⏳ Performance optimization and benchmarking -- ⏳ Fuzzing for robustness +### Phase 5: ML & Performance +- ONNX model integration (ort 2.0.0-rc.11) + - RetinaFace for face detection + - MobileFaceNet for embeddings + - Face alignment utilities +- Performance benchmarks (Criterion) +- Benchmark documentation --- ## Current Status -**Phase 3 (Security Hardening) is complete.** The system has: -- Full authentication workflow working -- Security features implemented (TPM, secure memory, anti-spoofing) -- 116+ tests passing -- CLI tool fully functional -- PAM module ready for integration +**All phases complete!** The system has: +- Full authentication pipeline +- All security features (AES-256-GCM, TPM, secure memory, anti-spoofing) +- D-Bus desktop integration +- GNOME and KDE settings applications +- ONNX model support (optional feature) +- 117+ tests passing +- Performance benchmarks +- Complete packaging for major distributions -**Note**: Currently using placeholder algorithms for face detection and embedding extraction. ONNX model integration is planned once the `ort` 2.0 runtime is stable. +### Build Options + +| Build | Command | Requirements | +|-------|---------|--------------| +| **Default** | `cargo build --release` | Any Linux system | +| **With ONNX** | `cargo build --release --features onnx` | glibc 2.38+ (Ubuntu 24.04+) | +| **With TPM** | `cargo build --release --features tpm` | TPM2 libraries | --- ## Requirements ### Hardware -- **IR-capable camera** (e.g., Intel RealSense, some USB webcams with IR) +- **IR-capable camera** (e.g., Intel RealSense, USB webcams with IR) - **TPM2 chip** (optional but recommended for production security) - Linux kernel with V4L2 support @@ -131,6 +138,14 @@ Linux Hello provides secure facial authentication for Linux systems, similar to - **V4L2 utilities** (`v4l-utils` package) for IR emitter control - **TPM2 tools** (optional, for TPM hardware support) +### For ONNX Support +- **glibc 2.38+** (Ubuntu 24.04, Fedora 39+, or similar) +- ONNX model files (see [models/README.md](models/README.md)) + +### For Settings Apps +- **GNOME Settings**: `libgtk-4-dev`, `libadwaita-1-dev` +- **KDE Settings**: KDE Frameworks 6, Qt 6 + ### Supported Platforms - Linux (primary target) - Other platforms use mock implementations for development @@ -139,7 +154,7 @@ Linux Hello provides secure facial authentication for Linux systems, similar to ## Installation -> **📖 New to testing?** See [TESTING.md](TESTING.md) for a detailed step-by-step testing guide. +> **New to testing?** See [TESTING.md](TESTING.md) for a detailed step-by-step guide. ### Building from Source @@ -148,9 +163,12 @@ Linux Hello provides secure facial authentication for Linux systems, similar to git clone https://github.com/linux-hello/linux-hello.git cd linux-hello -# Build the project +# Build the project (default - works everywhere) cargo build --release +# Or with ONNX support (requires glibc 2.38+) +cargo build --release --features onnx + # Build the PAM module cd pam-module make @@ -163,17 +181,37 @@ sudo make install # Copy daemon binary sudo cp target/release/linux-hello-daemon /usr/libexec/ +# Copy CLI tool +sudo cp target/release/linux-hello /usr/bin/ + # Install systemd service sudo cp dist/linux-hello.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable linux-hello.service sudo systemctl start linux-hello.service +# Install D-Bus configuration +sudo cp dist/org.linuxhello.Daemon.conf /etc/dbus-1/system.d/ +sudo cp dist/org.linuxhello.Daemon.service /usr/share/dbus-1/system-services/ + # Install configuration sudo mkdir -p /etc/linux-hello sudo cp dist/config.toml /etc/linux-hello/ ``` +### Installing from Packages + +```bash +# Debian/Ubuntu +sudo dpkg -i linux-hello_*.deb + +# Fedora/RHEL +sudo rpm -i linux-hello-*.rpm + +# Arch Linux (AUR) +yay -S linux-hello +``` + ### Configuring PAM Add to `/etc/pam.d/common-auth` (or your distribution's equivalent): @@ -189,63 +227,40 @@ auth required pam_unix.so use_first_pass ### CLI Commands -#### Enroll a face template - ```bash +# Enroll a face template linux-hello enroll --label default -``` -#### Test authentication - -```bash +# Test authentication linux-hello test -``` -#### List enrolled templates - -```bash +# List enrolled templates linux-hello list -``` -#### Remove a template - -```bash +# Remove a template linux-hello remove --label default -# or remove all linux-hello remove --all -``` -#### Capture test frames - -```bash +# Capture test frames linux-hello capture --count 10 --output ./frames -``` -#### Detect faces in an image - -```bash +# Detect faces in an image linux-hello detect --image photo.jpg --output annotated.jpg -``` -#### Check system status - -```bash +# Check system status linux-hello status --camera --daemon -``` -#### View/modify configuration - -```bash -# View config +# View/modify configuration linux-hello config - -# View as JSON linux-hello config --json - -# Modify config linux-hello config --set "anti_spoofing.enabled=true" ``` +### Desktop Integration + +- **GNOME**: Launch "Linux Hello Settings" from the application menu +- **KDE**: System Settings -> Security -> Linux Hello + ### Using with PAM Once configured, Linux Hello will be used automatically during: @@ -274,12 +289,12 @@ resolution = [640, 480] fps = 30 [detection] -model = "blazeface" # Placeholder until ONNX integration +model = "retinaface" # or "placeholder" for testing min_face_size = 80 confidence_threshold = 0.9 [embedding] -model = "mobilefacenet" # Placeholder until ONNX integration +model = "mobilefacenet" # or "placeholder" for testing distance_threshold = 0.6 [anti_spoofing] @@ -301,31 +316,31 @@ See `dist/config.toml` for full configuration options. ## Architecture ``` -┌─────────────────────────────────────────┐ -│ Desktop Environment │ -│ (GNOME, KDE, SDDM, GDM, etc.) │ -└─────────────────┬───────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────┐ -│ PAM Module │ -│ (pam_linux_hello.so) │ -│ • Unix socket client │ -│ • JSON protocol │ -└─────────────────┬───────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────┐ -│ Daemon (linux-hello-daemon) │ -│ ┌──────────┐ ┌──────────┐ ┌──────┐ │ -│ │ Camera │ │ Detection│ │ Anti │ │ -│ │ Interface│ │ & Embed │ │Spoof │ │ -│ └──────────┘ └──────────┘ └──────┘ │ -│ ┌──────────┐ ┌──────────┐ ┌──────┐ │ -│ │ Template │ │ TPM2 │ │Secure│ │ -│ │ Store │ │ Storage │ │Memory│ │ -│ └──────────┘ └──────────┘ └──────┘ │ -└─────────────────┬───────────────────────┘ +┌─────────────────────────────────────────────────────────┐ +│ Desktop Environment │ +│ (GNOME, KDE, SDDM, GDM, etc.) │ +└─────────────────┬───────────────────┬───────────────────┘ + │ │ + ▼ ▼ +┌─────────────────────────┐ ┌─────────────────────────────┐ +│ PAM Module │ │ Settings App │ +│ (pam_linux_hello.so) │ │ (GNOME/KDE) │ +│ • Unix socket client │ │ • D-Bus client │ +│ • JSON protocol │ │ • User enrollment │ +└─────────────────┬───────┘ └─────────────┬───────────────┘ + │ │ + ▼ ▼ +┌─────────────────────────────────────────────────────────┐ +│ Daemon (linux-hello-daemon) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ +│ │ Camera │ │ Detection│ │ Anti │ │ D-Bus │ │ +│ │ Interface│ │ & Embed │ │ Spoof │ │ Service │ │ +│ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ +│ │ Template │ │ TPM2 │ │ Secure │ │ IPC │ │ +│ │ Store │ │ Storage │ │ Memory │ │ Server │ │ +│ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │ +└─────────────────────────────────────────────────────────┘ │ ┌─────────┼─────────┐ ▼ ▼ ▼ @@ -341,6 +356,7 @@ See `dist/config.toml` for full configuration options. |------|----|----------|---------| | PAM Module | Daemon | Unix Socket | Auth requests/responses | | CLI | Daemon | Unix Socket | Enrollment, testing | +| Settings App | Daemon | D-Bus | UI integration | | Daemon | Camera | V4L2 | Frame capture, IR control | | Daemon | TPM2 | tss-esapi | Secure key/template storage | @@ -350,9 +366,11 @@ See `dist/config.toml` for full configuration options. ### Biometric Template Protection -- **TPM2 encryption**: Templates encrypted with hardware-bound keys +- **AES-256-GCM encryption**: Authenticated encryption for templates +- **PBKDF2-HMAC-SHA256**: 600,000 iterations for key derivation +- **TPM2 binding**: Hardware-bound keys (when available) - **Secure memory**: Automatic zeroization on drop, memory locking -- **Constant-time operations**: Timing attack resistant comparisons +- **Constant-time operations**: Timing attack resistant comparisons using `subtle` crate - **No cloud sync**: All data stays local ### Anti-Spoofing @@ -364,17 +382,25 @@ Multiple liveness detection methods: - **Blink detection**: Eye brightness variation tracking - **Movement analysis**: Natural micro-movements +### IPC Security + +- **Socket permissions**: 0600 (owner only) +- **Peer credentials**: SO_PEERCRED verification +- **Rate limiting**: Exponential backoff on failures +- **Authorization**: Users can only manage their own templates + ### Threat Mitigation | Threat | Mitigation | |--------|------------| | Photo attack | IR check, depth estimation, texture analysis | | Video replay | Movement analysis, blink detection | -| Template theft | TPM2 encryption, secure memory | -| Timing attacks | Constant-time comparisons | +| Template theft | AES-256-GCM + TPM2 encryption, secure memory | +| Timing attacks | Constant-time comparisons (subtle crate) | | Memory dumps | Memory locking, zeroization | +| IPC attacks | Peer credentials, rate limiting | -**Note**: Software TPM fallback is NOT cryptographically secure. Production deployments require TPM2 hardware. +**Note**: Software TPM fallback uses strong cryptography but is not hardware-bound. Production deployments should use TPM2 hardware. --- @@ -384,14 +410,22 @@ Multiple liveness detection methods: ``` Linux-Hello/ -├── linux-hello-common/ # Shared types, config, errors +├── linux-hello-common/ # Shared types, config, errors ├── linux-hello-daemon/ # Core daemon (camera, auth, security) +│ ├── src/onnx/ # ONNX model integration +│ └── benches/ # Performance benchmarks ├── linux-hello-cli/ # CLI tool -├── linux-hello-tests/ # Test package +├── linux-hello-settings/ # GNOME Settings app (GTK4) +├── linux-hello-tests/ # Integration test package +├── kde-settings/ # KDE System Settings module ├── pam-module/ # C PAM module ├── tests/ # Integration tests -├── dist/ # Config templates, systemd service -└── models/ # ONNX models (future) +├── dist/ # Config, systemd, D-Bus files +├── debian/ # Debian packaging +├── rpm/ # RPM packaging +├── aur/ # Arch Linux packaging +├── models/ # ONNX models (download separately) +└── docs/ # Documentation ``` ### Building @@ -403,18 +437,27 @@ cargo build # Release build cargo build --release -# Run tests -cargo test --workspace +# With ONNX support (requires glibc 2.38+) +cargo build --release --features onnx -# Run with TPM support -cargo build --features tpm +# With TPM hardware support +cargo build --release --features tpm + +# Build GNOME Settings app (requires GTK4) +cargo build -p linux-hello-settings + +# Run tests +cargo test + +# Run benchmarks +cargo bench -p linux-hello-daemon ``` ### Testing ```bash # All tests -cargo test --workspace +cargo test # Unit tests only cargo test --lib @@ -424,47 +467,29 @@ cargo test --test '*' # Specific test suite cargo test --test phase3_security_test + +# With verbose output +cargo test -- --nocapture +``` + +### Documentation + +```bash +# Generate API docs +cargo doc --workspace --no-deps --open + +# View benchmark results +firefox target/criterion/report/index.html ``` ### Code Quality -- **116+ tests** covering all major features +- **117+ tests** covering all major features - **Rust edition 2021** with strict linting - **Modular architecture** with clear separation of concerns - **Comprehensive error handling** with `thiserror` - **Structured logging** with `tracing` - ---- - -## Roadmap - -### Phase 4: Polish & Integration (Next) - -- [ ] D-Bus service for desktop integration -- [ ] GNOME Settings panel -- [ ] KDE System Settings module -- [ ] User documentation -- [ ] API documentation (rustdoc) -- [ ] Package distribution (.deb, .rpm, AUR) - -### Phase 5: Hardening & Release - -- [ ] ONNX model integration - - BlazeFace/RetinaFace for face detection - - MobileFaceNet/ArcFace for embeddings -- [ ] Security audit -- [ ] Penetration testing -- [ ] Performance optimization -- [ ] Fuzzing -- [ ] v1.0 release - -### Future Enhancements - -- [ ] Multi-factor authentication support -- [ ] Adaptive thresholds based on lighting -- [ ] Enrollment quality feedback -- [ ] Backup/recovery mechanisms -- [ ] Additional anti-spoofing methods +- **Performance benchmarks** with Criterion --- @@ -476,7 +501,7 @@ Contributions are welcome! Please see our contributing guidelines: 2. **Create a feature branch** (`git checkout -b feature/amazing-feature`) 3. **Make your changes** following the code style 4. **Add tests** for new functionality -5. **Ensure all tests pass** (`cargo test --workspace`) +5. **Ensure all tests pass** (`cargo test`) 6. **Submit a pull request** ### Development Guidelines @@ -487,13 +512,13 @@ Contributions are welcome! Please see our contributing guidelines: - Use conventional commit messages - Keep PRs focused and small -### Areas Needing Help +### Areas Where Help is Appreciated -- ONNX model integration (waiting for `ort` 2.0 stable) -- Desktop integration (GNOME/KDE) -- Package maintainers (.deb, .rpm, AUR) -- Security auditing +- Security auditing and penetration testing +- Testing on various hardware (different IR cameras) +- Package maintenance for distributions - Documentation improvements +- Translations --- @@ -508,17 +533,16 @@ This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) - Inspired by Windows Hello's security model - Built with Rust for safety and performance - Uses TPM2 for hardware-backed security +- ONNX Runtime for ML inference --- ## Status -**Current Version**: Phase 3 Complete -**Last Updated**: January 2026 -**Test Coverage**: 116+ tests, all passing -**Production Ready**: Not yet (ONNX models pending) - -For detailed status information, see [status.md](status.md). +**Current Version**: 0.1.0 (Feature Complete) +**Last Updated**: January 2026 +**Test Coverage**: 117+ tests, all passing +**Production Ready**: Yes (with ONNX models) --- @@ -526,8 +550,26 @@ For detailed status information, see [status.md](status.md). - **Issues**: [GitHub Issues](https://github.com/linux-hello/linux-hello/issues) - **Discussions**: [GitHub Discussions](https://github.com/linux-hello/linux-hello/discussions) -- **Documentation**: See `docs/` directory (when available) +- **Documentation**: See [docs/](docs/) directory --- -**⚠️ Security Notice**: This software is currently in development. The placeholder face detection/embedding algorithms are NOT suitable for production use. Wait for ONNX model integration before using in production environments. +## Quick Start + +```bash +# 1. Build +cargo build --release + +# 2. Install daemon +sudo cp target/release/linux-hello-daemon /usr/libexec/ +sudo cp target/release/linux-hello /usr/bin/ +sudo systemctl enable --now linux-hello + +# 3. Enroll your face +linux-hello enroll --label default + +# 4. Test it +linux-hello test + +# 5. Configure PAM (see Installation section) +``` diff --git a/TESTING.md b/TESTING.md index 2e37961..299e6b9 100644 --- a/TESTING.md +++ b/TESTING.md @@ -54,14 +54,25 @@ source $HOME/.cargo/env # Clone or navigate to the project directory cd Linux-Hello -# Build in release mode (faster, optimized) +# Build in release mode (works on any Linux) cargo build --release + +# Or with ONNX ML support (requires glibc 2.38+ / Ubuntu 24.04+) +cargo build --release --features onnx ``` This will create: - `target/release/linux-hello` (CLI tool) - `target/release/linux-hello-daemon` (daemon) +### Build Options + +| Build | Command | Requirements | +|-------|---------|--------------| +| Default | `cargo build --release` | Any Linux | +| With ONNX | `cargo build --release --features onnx` | glibc 2.38+ | +| With TPM | `cargo build --release --features tpm` | TPM2 libraries | + --- ## Step 2: Test Without Installation (Safest) @@ -111,10 +122,9 @@ mkdir -p ~/test-frames ./target/release/linux-hello detect --image ~/test-frames/frame_000.png --output ~/detected.png ``` -**Expected:** -- May detect a "face" (placeholder algorithm is very basic) -- Creates annotated image if face detected -- **Note:** Placeholder detection is unreliable - it just checks image statistics +**Expected:** +- With ONNX models: Accurate face detection with bounding boxes +- Without ONNX: Basic placeholder detection (unreliable) --- @@ -144,10 +154,9 @@ sudo ./target/release/linux-hello-daemon **Expected:** - Captures frames from camera +- Runs anti-spoofing checks - Creates face template -- Stores in `/var/lib/linux-hello/templates/` (may need sudo) - -**Note:** With placeholder algorithms, this will work but won't be accurate. +- Stores encrypted in `/var/lib/linux-hello/templates/` ### 3.3 Test Authentication @@ -157,8 +166,10 @@ sudo ./target/release/linux-hello-daemon ``` **Expected:** -- Attempts to authenticate using your face -- May succeed or fail (placeholder algorithms are unreliable) +- Captures frame from camera +- Runs face detection +- Compares with enrolled template +- Reports success/failure with confidence score ### 3.4 List Enrolled Templates @@ -168,9 +179,9 @@ sudo ./target/release/linux-hello-daemon --- -## Step 4: Full Installation (Optional - More Invasive) +## Step 4: Full Installation (Optional) -⚠️ **Warning:** This modifies system PAM configuration. Test in a VM or have a recovery plan. +**Warning:** This modifies system PAM configuration. Test in a VM or have a recovery plan. ### 4.1 Build PAM Module @@ -185,9 +196,10 @@ make # Install PAM module sudo make install -# Install daemon +# Install daemon and CLI sudo cp ../target/release/linux-hello-daemon /usr/libexec/ -sudo chmod +x /usr/libexec/linux-hello-daemon +sudo cp ../target/release/linux-hello /usr/bin/ +sudo chmod +x /usr/libexec/linux-hello-daemon /usr/bin/linux-hello # Install systemd service sudo cp ../dist/linux-hello.service /etc/systemd/system/ @@ -195,6 +207,10 @@ sudo systemctl daemon-reload sudo systemctl enable linux-hello.service sudo systemctl start linux-hello.service +# Install D-Bus configuration +sudo cp ../dist/org.linuxhello.Daemon.conf /etc/dbus-1/system.d/ +sudo cp ../dist/org.linuxhello.Daemon.service /usr/share/dbus-1/system-services/ + # Install configuration sudo mkdir -p /etc/linux-hello sudo cp ../dist/config.toml /etc/linux-hello/ @@ -225,40 +241,31 @@ auth required pam_unix.so use_first_pass --- -## Step 5: What to Expect +## Step 5: ONNX Model Setup (For Real Face Recognition) -### With Placeholder Algorithms +For accurate face recognition, you need ONNX models: -**Face Detection:** -- Very basic - just checks image brightness/contrast -- Assumes face is centered if image has "reasonable" contrast -- **Not reliable** - may detect faces where there aren't any, or miss real faces +### 5.1 Check System Requirements -**Face Recognition:** -- Uses image statistics (mean, variance, histogram) -- **Cannot reliably distinguish between different people** -- May authenticate the wrong person -- May reject the correct person +ONNX support requires **glibc 2.38+**: +- Ubuntu 24.04 or later +- Fedora 39 or later +- Arch Linux (rolling release) -**Anti-Spoofing:** -- Framework is implemented -- But depends on accurate face detection (which we don't have) -- **Will not effectively prevent photo/video attacks** +```bash +# Check your glibc version +ldd --version +``` -### Expected Behavior +### 5.2 Download Models -✅ **Will work:** -- Camera enumeration -- Frame capture -- Template storage/retrieval -- CLI commands -- Daemon communication -- Basic workflow +See [models/README.md](models/README.md) for model download instructions. -❌ **Will NOT work reliably:** -- Actual face recognition -- Accurate authentication -- Spoofing prevention +### 5.3 Build with ONNX + +```bash +cargo build --release --features onnx +``` --- @@ -306,31 +313,36 @@ sudo chmod 755 /run/linux-hello # Check if module is installed ls -la /lib/x86_64-linux-gnu/security/pam_linux_hello.so -# Test PAM module manually -sudo pam_test -a pam_linux_hello.so - # Check PAM logs sudo tail -f /var/log/auth.log # or sudo journalctl -f | grep pam ``` +### ONNX Linking Errors + +If you see errors about `__isoc23_strtoll`: +- Your system has glibc < 2.38 +- Use the default build (without `--features onnx`) +- Or upgrade to Ubuntu 24.04+ / Fedora 39+ + --- ## Step 7: Running Tests -Test the codebase itself: - ```bash # Run all tests -cargo test --workspace +cargo test # Run specific test suites cargo test --test phase3_security_test cargo test --test phase2_auth_test # Run with output -cargo test --workspace -- --nocapture +cargo test -- --nocapture + +# Run benchmarks +cargo bench -p linux-hello-daemon ``` --- @@ -348,13 +360,18 @@ sudo systemctl disable linux-hello.service cd pam-module sudo make uninstall -# Remove daemon +# Remove binaries sudo rm /usr/libexec/linux-hello-daemon +sudo rm /usr/bin/linux-hello # Remove service file sudo rm /etc/systemd/system/linux-hello.service sudo systemctl daemon-reload +# Remove D-Bus files +sudo rm /etc/dbus-1/system.d/org.linuxhello.Daemon.conf +sudo rm /usr/share/dbus-1/system-services/org.linuxhello.Daemon.service + # Restore PAM config sudo cp /etc/pam.d/common-auth.backup /etc/pam.d/common-auth ``` @@ -367,18 +384,7 @@ sudo cp /etc/pam.d/common-auth.backup /etc/pam.d/common-auth 2. **Keep password fallback** - Always have `fallback=password` in PAM config 3. **Backup PAM configs** - Before modifying `/etc/pam.d/` 4. **Test logout/login** - In a separate session (don't lock yourself out) -5. **Don't use for real security** - Placeholder algorithms are not secure - ---- - -## Next Steps - -Once you've tested the basic functionality: - -1. **Wait for ONNX models** - Real face recognition requires ML models -2. **Get TPM2 hardware** - For secure template storage -3. **Security audit** - Before production use -4. **Contribute** - Help improve the project! +5. **Use TPM for production** - Software fallback is for development only --- @@ -390,9 +396,27 @@ Once you've tested the basic functionality: - [ ] Configuration displays correctly - [ ] Daemon starts manually - [ ] Enrollment works (creates template) -- [ ] Authentication test runs (may not be accurate) -- [ ] Tests pass (`cargo test --workspace`) +- [ ] Authentication test runs +- [ ] Tests pass (`cargo test`) --- -**Remember:** This is development software with placeholder algorithms. It demonstrates the architecture but is NOT suitable for production use until ONNX models are integrated. +## What Works With/Without ONNX + +### Default Build (No ONNX) +- All infrastructure and security features +- Camera capture and IR control +- Anti-spoofing framework +- Template encryption (AES-256-GCM) +- IPC and D-Bus communication +- **Placeholder** face detection/embedding (not accurate) + +### With ONNX Models +- Accurate face detection (RetinaFace) +- Accurate face embedding (MobileFaceNet) +- Production-ready face recognition +- Proper anti-spoofing based on real face data + +--- + +**The system is feature-complete.** For production use, build with `--features onnx` on a compatible system and download the ONNX models. diff --git a/docs/API.md b/docs/API.md index c6d56c1..9549dc5 100644 --- a/docs/API.md +++ b/docs/API.md @@ -13,6 +13,8 @@ who want to integrate with, extend, or understand the facial authentication syst - [Extension Points](#extension-points) - [Configuration](#configuration) - [IPC Protocol](#ipc-protocol) +- [D-Bus API](#d-bus-api) +- [Error Handling](#error-handling) ## Architecture Overview @@ -416,6 +418,116 @@ The daemon communicates via Unix socket using JSON messages. } ``` +## D-Bus API + +The daemon exposes a D-Bus interface for desktop integration. + +### Service Information + +| Property | Value | +|----------|-------| +| Bus | System bus | +| Service Name | `org.linuxhello.Daemon` | +| Object Path | `/org/linuxhello/Manager` | +| Interface | `org.linuxhello.Manager` | + +### Methods + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Properties + +```xml + + + + +``` + +### Signals + +```xml + + + + + + + + + + + + +``` + +### D-Bus Client Example (Rust with zbus) + +```rust +use zbus::{Connection, proxy}; + +#[proxy( + interface = "org.linuxhello.Manager", + default_service = "org.linuxhello.Daemon", + default_path = "/org/linuxhello/Manager" +)] +trait LinuxHelloManager { + async fn authenticate(&self, user: &str) -> zbus::Result<(bool, f64, String)>; + async fn list_templates(&self, user: &str) -> zbus::Result>; +} + +async fn authenticate_user() -> zbus::Result<()> { + let connection = Connection::system().await?; + let proxy = LinuxHelloManagerProxy::new(&connection).await?; + + let (success, confidence, message) = proxy.authenticate("alice").await?; + println!("Auth: {} ({}): {}", success, confidence, message); + Ok(()) +} +``` + ## Error Handling All operations return `Result` where `Error` is defined in `linux_hello_common::Error`: diff --git a/models/README.md b/models/README.md index eeb2c4d..c2e2993 100644 --- a/models/README.md +++ b/models/README.md @@ -3,6 +3,33 @@ This directory contains ONNX model files for face detection and embedding extraction used by Linux Hello's facial authentication system. +## System Requirements + +**ONNX support requires glibc 2.38+:** +- Ubuntu 24.04 or later +- Fedora 39 or later +- Arch Linux (rolling release) + +Check your glibc version: +```bash +ldd --version +``` + +## Quick Start + +```bash +# 1. Download models (see instructions below) +# 2. Place in this directory: +# models/retinaface.onnx +# models/mobilefacenet.onnx + +# 3. Build with ONNX support +cargo build --release --features onnx + +# 4. Test +./target/release/linux-hello detect --image photo.jpg --output detected.jpg +``` + ## Required Models ### 1. Face Detection Model