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 (GNOME/Zorin) lock screen and login — 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	Status
Lenovo Yoga Pro 7 (Chicony IR camera)	Zorin OS 17 (GNOME/GDM)	Working

Other laptops with Windows Hello-compatible IR cameras should work. If you test on different hardware, please open an issue to let us know.

---

Install

Requirements

• A Linux laptop with a Windows Hello-compatible IR camera (check with v4l2-ctl --list-devices — look for a second camera labeled "IR" or "Integrated I")
• Rust 1.75+ and Cargo
• GDM display manager (GNOME, Zorin, Ubuntu)
• Packages: libpam0g-dev, v4l-utils, build-essential

Install

You need Rust installed. Then:

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.

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

---

Uninstall

# Remove PAM line
sudo sed -i '/pam_linux_hello/d' /etc/pam.d/gdm-password

# Stop and disable service
sudo systemctl disable --now linux-hello.service

# Remove files
sudo rm -f /usr/libexec/linux-hello-daemon /usr/local/bin/linux-hello
sudo rm -f /lib/x86_64-linux-gnu/security/pam_linux_hello.so
sudo rm -f /etc/systemd/system/linux-hello.service
sudo rm -rf /etc/linux-hello /var/lib/linux-hello /usr/share/linux-hello

---

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.