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 (requires glibc 2.38+ / Ubuntu 24.04+)
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

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 (requires glibc 2.38+)
cargo test --features onnx

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