Linux-Hello/README.md

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

1. You lock your screen or log out
2. The IR camera captures your face (invisible to you — just a brief red light)
3. The ONNX neural network matches your face against your enrolled template
4. 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.