Linux Hello Logo
# Linux Hello **Secure facial authentication for Linux using IR cameras and TPM2** A Windows Hello-equivalent biometric authentication system for Linux, designed with security-first principles: TPM-backed credential storage, anti-spoofing detection, and proper PAM integration. [![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)]() --- ## Table of Contents - [Overview](#overview) - [Features](#features) - [Current Status](#current-status) - [Requirements](#requirements) - [Installation](#installation) - [Usage](#usage) - [Configuration](#configuration) - [Architecture](#architecture) - [Security](#security) - [Development](#development) - [Contributing](#contributing) - [License](#license) --- ## Overview Linux Hello provides secure facial authentication for Linux systems, similar to Windows Hello. It uses IR cameras for reliable face detection, TPM2 for secure credential storage, and advanced anti-spoofing to prevent photo/video attacks. ### Key Features - **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 ### 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 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 - 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 - IPC security: peer credentials, rate limiting, authorization ### 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 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 **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 ### 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, USB webcams with IR) - **TPM2 chip** (optional but recommended for production security) - Linux kernel with V4L2 support ### Software - **Rust** 1.75 or later - **Cargo** (Rust package manager) - **PAM development libraries** (`libpam0g-dev` on Debian/Ubuntu) - **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 --- ## Installation > **New to testing?** See [TESTING.md](TESTING.md) for a detailed step-by-step guide. ### Building from Source ```bash # Clone the repository git clone https://github.com/linux-hello/linux-hello.git cd linux-hello # 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 sudo make install ``` ### Installing the Daemon ```bash # 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): ``` auth sufficient pam_linux_hello.so auth required pam_unix.so use_first_pass ``` --- ## Usage ### CLI Commands ```bash # Enroll a face template linux-hello enroll --label default # Test authentication linux-hello test # List enrolled templates linux-hello list # Remove a template linux-hello remove --label default linux-hello remove --all # Capture test frames linux-hello capture --count 10 --output ./frames # Detect faces in an image linux-hello detect --image photo.jpg --output annotated.jpg # Check system status linux-hello status --camera --daemon # View/modify configuration linux-hello config linux-hello config --json 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: - Login (via display manager) - `sudo` commands - Screen unlock - Any PAM-authenticated operation --- ## Configuration Configuration is stored in `/etc/linux-hello/config.toml` (system-wide) or `~/.config/linux-hello/config.toml` (user-specific). ### Key Settings ```toml [general] log_level = "info" timeout_seconds = 5 [camera] device = "auto" # Auto-detect or specify "/dev/video2" ir_emitter = "auto" resolution = [640, 480] fps = 30 [detection] model = "retinaface" # or "placeholder" for testing min_face_size = 80 confidence_threshold = 0.9 [embedding] model = "mobilefacenet" # or "placeholder" for testing distance_threshold = 0.6 [anti_spoofing] enabled = true depth_check = true liveness_model = true temporal_check = true min_score = 0.7 [tpm] enabled = true pcr_binding = false # Set to true for enhanced security ``` See `dist/config.toml` for full configuration options. --- ## Architecture ``` ┌─────────────────────────────────────────────────────────┐ │ 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 │ │ │ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │ └─────────────────────────────────────────────────────────┘ │ ┌─────────┼─────────┐ ▼ ▼ ▼ ┌────────┐ ┌──────┐ ┌────────┐ │Camera │ │ TPM2 │ │ ONNX │ │/dev/vid│ │Device│ │Runtime │ └────────┘ └──────┘ └────────┘ ``` ### Component Communication | From | To | Protocol | Purpose | |------|----|----------|---------| | 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 | --- ## Security ### Biometric Template Protection - **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 using `subtle` crate - **No cloud sync**: All data stays local ### Anti-Spoofing Multiple liveness detection methods: - **IR presence check**: Verifies IR illumination patterns - **Depth estimation**: Detects 3D structure using gradients - **Texture analysis**: LBP-based skin texture verification - **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 | 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 uses strong cryptography but is not hardware-bound. Production deployments should use TPM2 hardware. --- ## Development ### Project Structure ``` Linux-Hello/ ├── 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-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, systemd, D-Bus files ├── debian/ # Debian packaging ├── rpm/ # RPM packaging ├── aur/ # Arch Linux packaging ├── models/ # ONNX models (download separately) └── docs/ # Documentation ``` ### Building ```bash # Development build cargo build # Release build cargo build --release # With ONNX support (requires glibc 2.38+) cargo build --release --features onnx # 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 # Unit tests only cargo test --lib # Integration tests 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 - **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` - **Performance benchmarks** with Criterion --- ## Contributing Contributions are welcome! Please see our contributing guidelines: 1. **Fork the repository** 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`) 6. **Submit a pull request** ### Development Guidelines - Follow Rust best practices and idioms - Write tests for new features - Update documentation as needed - Use conventional commit messages - Keep PRs focused and small ### Areas Where Help is Appreciated - Security auditing and penetration testing - Testing on various hardware (different IR cameras) - Package maintenance for distributions - Documentation improvements - Translations --- ## License This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details. --- ## Acknowledgments - 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**: 0.1.0 (Feature Complete) **Last Updated**: January 2026 **Test Coverage**: 117+ tests, all passing **Production Ready**: Yes (with ONNX models) --- ## Support - **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/](docs/) directory --- ## 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) ```