576 lines
17 KiB
Markdown
576 lines
17 KiB
Markdown
<div align="center">
|
|
<img src="public/logo.png" alt="Linux Hello Logo" width="200">
|
|
</div>
|
|
|
|
# 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.
|
|
|
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
|
[](https://www.rust-lang.org/)
|
|
[]()
|
|
|
|
---
|
|
|
|
## 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)
|
|
```
|