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

Quick install

# Install dependencies
sudo apt install libpam0g-dev v4l-utils build-essential

# Clone and build
git clone https://gitea.lab48.be/eliott/Linux-Hello.git
cd Linux-Hello
cargo build --release --features onnx

# Build PAM module
cd pam-module && make && cd ..

# Download ONNX models (RetinaFace + MobileFaceNet)
./scripts/download-models.sh

# Install ONNX Runtime (if on Ubuntu 22.04 / glibc < 2.38)
./scripts/install-onnx-runtime.sh --user

# Run the system installer
sudo ./scripts/install-system.sh

# Enable the IR emitter (interactive — follow the prompts)
pip install linux-enable-ir-emitter  # or build from source
sudo linux-enable-ir-emitter configure

# Start the daemon
sudo systemctl enable --now linux-hello.service

# Enroll your face
linux-hello enroll

# Test it
linux-hello test

Enable on lock screen

Add face auth to GDM by inserting one line in /etc/pam.d/gdm-password, right before @include common-auth:

auth    sufficient      pam_linux_hello.so timeout=5

That's it. Lock your screen and look at the camera.

If face auth fails for any reason, the password prompt appears normally. To undo, just remove that line.

---

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.