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.

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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes following the code style
Add tests for new functionality
Ensure all tests pass (cargo test --workspace)
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.

Languages

Rust 83.9%

Shell 5.2%

C++ 3.6%

C 3.6%

QML 3.1%

Other 0.6%

README.md

Linux Hello

Table of Contents

Overview

Key Features

Features

✅ Implemented (Phase 1-3 Complete)

Phase 1: Foundation

Phase 2: Core Authentication

Phase 3: Security Hardening

🚧 Planned (Phase 4-5)

Phase 4: Polish & Integration

Phase 5: Hardening & Release

Current Status

Requirements

Hardware

Software

Supported Platforms

Installation

Building from Source

Installing the Daemon

Configuring PAM

Usage

CLI Commands

Enroll a face template

Test authentication

List enrolled templates

Remove a template

Capture test frames

Detect faces in an image

Check system status

View/modify configuration

Using with PAM

Configuration

Key Settings

Architecture

Component Communication

Security

Biometric Template Protection

Anti-Spoofing

Threat Mitigation

Development

Project Structure

Building

Testing

Code Quality

Roadmap

Phase 4: Polish & Integration (Next)

Phase 5: Hardening & Release

Future Enhancements

Contributing

Development Guidelines

Areas Needing Help

License

Acknowledgments

Status

Support