eliott
7a4db52140
Remove planning docs, phase summaries, old installers, and redundant documentation. These were development-phase artifacts that don't belong in the shipped project. install.sh replaces setup.sh and install-system.sh. API docs can be generated with cargo doc. Removed: - .planning/ (37 files of threat modeling and review docs) - CODING_STANDARDS.md, TESTING.md, CHANGELOG.md - docs/API.md, docs/BENCHMARKS.md - scripts/setup.sh, scripts/install-system.sh - tests/PHASE*_TEST_SUMMARY.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Linux Hello
Windows Hello-style face authentication for Linux
Unlock your computer with your face using your laptop's IR camera. Works with GDM, SDDM, and LightDM — your password always works as a fallback.
How it works
- You lock your screen or log out
- The IR camera captures your face (invisible to you — just a brief red light)
- The ONNX neural network matches your face against your enrolled template
- If it's you, you're in. If not, type your password as usual.
Phone screens are invisible to IR, so photos on a phone can't fool it.
Tested on
| Hardware | OS | Display Manager | Status |
|---|---|---|---|
| Lenovo Yoga Pro 7 (Chicony IR camera) | Zorin OS 17 | GDM (GNOME) | Working |
Other laptops with Windows Hello-compatible IR cameras should work. GDM, SDDM, and LightDM are supported. If you test on different hardware, please open an issue to let us know.
Install
You need Rust and a Windows Hello-compatible IR camera.
git clone https://gitea.lab48.be/eliott/Linux-Hello.git
cd Linux-Hello
./install.sh
The installer handles everything: dependencies, build, ONNX models, IR emitter setup, face enrollment, and lock screen integration.
When it's done, lock your screen and look at the camera.
To uninstall:
./install.sh --uninstall
CLI commands
linux-hello enroll # Enroll your face (5 frames)
linux-hello test # Test authentication
linux-hello list # Show enrolled templates
linux-hello remove default # Remove a template
linux-hello remove --all # Remove all templates
linux-hello detect --image pic.jpg --scores # Detect faces in an image
linux-hello capture --count 5 # Capture raw frames
linux-hello status --camera # Show camera info
linux-hello config # Show current config
Configuration
Config lives at /etc/linux-hello/config.toml (system) or ~/.config/linux-hello/config.toml (user).
[camera]
device = "/dev/video2" # Your IR camera (or "auto")
resolution = [640, 360]
fps = 15
[detection]
model = "blazeface"
[embedding]
model = "mobilefacenet"
distance_threshold = 0.6 # Lower = stricter matching
[anti_spoofing]
enabled = true
depth_check = false # Disable if no depth camera
temporal_check = false # Blink/movement (needs longer capture)
min_score = 0.7
Security
- IR camera blocks phone/screen photo attacks (screens don't emit IR)
- Anti-spoofing checks IR reflection patterns and skin texture
- AES-256-GCM encrypted face templates with PBKDF2 key derivation (600k iterations)
- TPM2 hardware-bound keys when available, software fallback otherwise
- Secure memory — embeddings are zeroized on drop, locked in RAM (no swap)
- Constant-time comparisons prevent timing attacks
- IPC uses Unix socket with peer credentials and rate limiting
Contributing
Contributions welcome — especially:
- Testing on other laptops/IR cameras
- Packaging for distributions
- Security auditing
See CONTRIBUTING.md for guidelines.
License
GPL-3.0 — see LICENSE.