Linux-Hello/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Linux Hello is a Windows Hello-equivalent biometric authentication system for Linux. It provides secure facial authentication using IR cameras and TPM2-backed credential storage.

Current Status: All phases complete (1-5). Feature complete with ONNX model support.

Build Commands

# Development build (works on any Linux)
cargo build

# Release build
cargo build --release

# Build with ONNX ML models
# - Ubuntu 24.04+ / glibc 2.38+: works directly
# - Ubuntu 22.04 / glibc 2.35+: run installer first (see below)
cargo build --release --features onnx

# Build with TPM hardware support
cargo build --release --features tpm

# Build with all features
cargo build --release --features "onnx,tpm"

# Run all tests
cargo test

# Run tests for a specific package
cargo test -p linux-hello-daemon

# Run specific integration test suite
cargo test --test phase3_security_test

# Run benchmarks
cargo bench -p linux-hello-daemon

# Generate documentation
cargo doc --workspace --no-deps --open

# Build PAM module (C)
cd pam-module && make

# Install PAM module (requires sudo)
cd pam-module && sudo make install

# Build GNOME Settings app (requires libgtk-4-dev, libadwaita-1-dev)
cargo build -p linux-hello-settings

Architecture

Workspace Crates

Crate	Purpose
linux-hello-common	Shared types (Config, Error, FaceTemplate, TemplateStore)
linux-hello-daemon	Core daemon with camera, auth, security, D-Bus; builds linux-hello-daemon binary
linux-hello-cli	CLI tool, builds linux-hello binary
linux-hello-settings	GNOME Settings app (GTK4/libadwaita)
linux-hello-tests	Integration test harness
pam-module	C PAM module (pam_linux_hello.so)

External Directories

Directory	Purpose
kde-settings/	KDE System Settings module (CMake/Qt6)
debian/	Debian packaging files
rpm/	RPM spec file
aur/	Arch Linux PKGBUILD
dist/	Config templates, systemd service, D-Bus files
models/	ONNX model files (download separately)
docs/	API documentation, benchmarks
scripts/	Installation and setup scripts

Key Daemon Modules (linux-hello-daemon/src/)

Module	Purpose
camera/	V4L2 camera enumeration, frame capture, IR emitter control
detection/	Face detection (placeholder + ONNX)
embedding.rs	Face embedding extraction (placeholder + ONNX)
matching.rs	Template matching with cosine similarity
anti_spoofing.rs	Liveness detection (IR, depth, texture, blink, movement)
secure_memory.rs	SecureBytes, SecureEmbedding with zeroization, memory locking
secure_template_store.rs	Encrypted template storage
tpm.rs	TPM2 integration with AES-256-GCM software fallback
ipc.rs	Unix socket server/client with peer credentials, rate limiting
auth.rs	Authentication service orchestration
dbus_service.rs	D-Bus interface implementation
dbus_server.rs	D-Bus server bootstrap
onnx/	ONNX model integration (feature-gated)

Communication Flow

Desktop/PAM → pam_linux_hello.so → Unix Socket → linux-hello-daemon → Camera/TPM
Settings App → D-Bus → linux-hello-daemon → Camera/TPM

Platform-Specific Code

Camera code uses conditional compilation:

• #[cfg(target_os = "linux")] - Real V4L2 implementation
• #[cfg(not(target_os = "linux"))] - Mock implementation for development

ONNX code is feature-gated:

• #[cfg(feature = "onnx")] - Real ONNX models
• #[cfg(not(feature = "onnx"))] - Placeholder algorithms

Security Considerations

• Encryption: AES-256-GCM with PBKDF2-HMAC-SHA256 (600k iterations)
• Secure memory: SecureEmbedding and SecureBytes auto-zeroize on drop
• Constant-time: Template comparisons use subtle crate (timing attack resistant)
• Memory locking: Sensitive data locked in RAM (no swap)
• IPC security: Peer credentials (SO_PEERCRED), rate limiting, authorization
• Software TPM fallback: Cryptographically strong but not hardware-bound

Key Dependencies

Dependency	Purpose
zbus	D-Bus integration
tokio	Async runtime
v4l	V4L2 camera interface
aes-gcm	Template encryption
subtle	Constant-time operations
zeroize	Secure memory wiping
ort	ONNX Runtime (optional)
tss-esapi	TPM2 support (optional)

Testing

# Quick test (default packages only)
cargo test

# All packages including integration tests
cargo test --workspace

# Specific test file
cargo test --test phase3_security_test

# With output
cargo test -- --nocapture

# ONNX tests
# On Ubuntu 22.04, set ORT_DYLIB_PATH first (see ONNX section below)
cargo test --features onnx

ONNX Runtime Setup

The ONNX feature requires different setup depending on your glibc version:

System	glibc	Setup Required
Ubuntu 24.04+, Fedora 39+	>= 2.38	None - works directly
Ubuntu 22.04, Debian 12	2.35-2.37	Run installer script
Ubuntu 20.04 and older	< 2.28	Not supported

For Ubuntu 22.04 / glibc 2.35-2.37

Run the installer to download a compatible ONNX Runtime:

# Check compatibility
./scripts/install-onnx-runtime.sh --check

# User install (no sudo)
./scripts/install-onnx-runtime.sh --user

# System-wide install
sudo ./scripts/install-onnx-runtime.sh

After installation, set the environment variable:

# Source the environment file
source ~/.local/etc/linux-hello/onnx-env.sh

# Or set directly
export ORT_DYLIB_PATH=~/.local/lib/linux-hello/libonnxruntime.so

# Then run
./target/release/linux-hello detect

Common Tasks

Adding a new D-Bus method

1. Add method to dbus_service.rs in the LinuxHelloManager impl
2. Update D-Bus client in linux-hello-settings/src/dbus_client.rs
3. Update KDE client in kde-settings/src/dbus_client.cpp

Adding a new CLI command

1. Add subcommand to linux-hello-cli/src/main.rs
2. Implement handler using daemon's IPC client

Adding a new anti-spoofing check

1. Add check method to anti_spoofing.rs
2. Add config option to Config in linux-hello-common/src/config.rs
3. Add test in tests/integration/phase3_security_test.rs