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
• Roadmap
• 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 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

---

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
• ✅ 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 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:
  • IR presence verification
  • Depth estimation
  • Texture analysis (LBP-based)
  • Blink detection
  • Micro-movement analysis
• ✅ Secure template store with migration support

🚧 Planned (Phase 4-5)

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

---

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

Note: Currently using placeholder algorithms for face detection and embedding extraction. ONNX model integration is planned once the ort 2.0 runtime is stable.

---

Requirements

Hardware

• IR-capable camera (e.g., Intel RealSense, some 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)

Supported Platforms

• Linux (primary target)
• Other platforms use mock implementations for development

---

Installation

Building from Source

# Clone the repository
git clone https://github.com/linux-hello/linux-hello.git
cd linux-hello

# Build the project
cargo build --release

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

# 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 configuration
sudo mkdir -p /etc/linux-hello
sudo cp dist/config.toml /etc/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
# or remove all
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

# View config
linux-hello config

# View as JSON
linux-hello config --json

# Modify config
linux-hello config --set "anti_spoofing.enabled=true"

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 = "blazeface"  # Placeholder until ONNX integration
min_face_size = 80
confidence_threshold = 0.9

[embedding]
model = "mobilefacenet"  # Placeholder until ONNX integration
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                    │
│      (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│  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
   ┌────────┐ ┌──────┐ ┌────────┐
   │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
Daemon	Camera	V4L2	Frame capture, IR control
Daemon	TPM2	tss-esapi	Secure key/template storage

---

Security

Biometric Template Protection

• TPM2 encryption: Templates encrypted with hardware-bound keys
• Secure memory: Automatic zeroization on drop, memory locking
• Constant-time operations: Timing attack resistant comparisons
• 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

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
Memory dumps	Memory locking, zeroization

Note: Software TPM fallback is NOT cryptographically secure. Production deployments require TPM2 hardware.

---

Development

Project Structure

Linux-Hello/
├── linux-hello-common/      # Shared types, config, errors
├── linux-hello-daemon/       # Core daemon (camera, auth, security)
├── linux-hello-cli/          # CLI tool
├── linux-hello-tests/        # Test package
├── pam-module/               # C PAM module
├── tests/                    # Integration tests
├── dist/                     # Config templates, systemd service
└── models/                   # ONNX models (future)

Building

# Development build
cargo build

# Release build
cargo build --release

# Run tests
cargo test --workspace

# Run with TPM support
cargo build --features tpm

Testing

# All tests
cargo test --workspace

# Unit tests only
cargo test --lib

# Integration tests
cargo test --test '*'

# Specific test suite
cargo test --test phase3_security_test

Code Quality

• 116+ 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

---

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 --workspace)
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 Needing Help

• ONNX model integration (waiting for ort 2.0 stable)
• Desktop integration (GNOME/KDE)
• Package maintainers (.deb, .rpm, AUR)
• Security auditing
• Documentation improvements

---

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

---

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.

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See docs/ directory (when available)

---

⚠️ 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.