eliott
8c478836d8
Wire up ONNX RetinaFace detector and MobileFaceNet embeddings in the CLI and auth pipeline. Add IR camera detection for Windows Hello-style "Integrated I" cameras and greyscale-only format heuristic. Add histogram normalization for underexposed IR frames from low-power emitters. - Add `onnx` feature flag to CLI crate forwarding to daemon - Wire ONNX detector into `detect` command with fallback to simple detector - Fix IR camera detection for Chicony "Integrated I" naming pattern - Add `normalize_if_dark()` for underexposed IR frames in auth pipeline - Load user config from ~/.config/linux-hello/ as fallback - Update systemd service for IR emitter integration and camera access - Add system installation script and ONNX runtime installer - Update .gitignore for local dev artifacts Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
212 lines
6.3 KiB
Markdown
212 lines
6.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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`
|