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.

---

Table of Contents

• Overview
• Features
• Current Status
• Requirements
• Installation
• Usage
• Configuration
• Architecture
• Security
• Development
• Contributing
• 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)

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 for a detailed step-by-step guide.

Building from Source

# 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

# 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

# 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

# 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

[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

# 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

# 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

# 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 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
• Discussions: GitHub Discussions
• Documentation: See docs/ directory

---

Quick Start

# 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)