Linux-Hello/TESTING.md

Testing Linux Hello on Your Linux Computer

This guide will help you test Linux Hello on your system. We'll start with safe CLI testing before any system-level installation.

Prerequisites

Install Required Packages

Debian/Ubuntu:

sudo apt update
sudo apt install -y \
    build-essential \
    libpam0g-dev \
    v4l-utils \
    pkg-config \
    libssl-dev

Fedora/RHEL:

sudo dnf install -y \
    gcc \
    make \
    pam-devel \
    v4l-utils \
    pkgconfig \
    openssl-devel

Arch Linux:

sudo pacman -S \
    base-devel \
    pam \
    v4l-utils \
    pkgconf \
    openssl

Install Rust

If you don't have Rust installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

---

Step 1: Build the Project

# Clone or navigate to the project directory
cd Linux-Hello

# Build in release mode (works on any Linux)
cargo build --release

# Or with ONNX ML support (requires glibc 2.38+ / Ubuntu 24.04+)
cargo build --release --features onnx

This will create:

• target/release/linux-hello (CLI tool)
• target/release/linux-hello-daemon (daemon)

Build Options

Build	Command	Requirements
Default	cargo build --release	Any Linux
With ONNX	cargo build --release --features onnx	glibc 2.38+
With TPM	cargo build --release --features tpm	TPM2 libraries

---

Step 2: Test Without Installation (Safest)

You can test most features without installing anything system-wide.

2.1 Check Camera Detection

# Run the CLI tool directly
./target/release/linux-hello status --camera

Expected output:

• Lists available cameras
• Shows IR camera detection
• May show "No cameras found" if no camera is connected

Note: Works even without a camera (will show empty list or use mock).

2.2 Test Configuration

# View default configuration
./target/release/linux-hello config

# View as JSON
./target/release/linux-hello config --json

2.3 Capture Test Frames (if camera available)

# Create a test directory
mkdir -p ~/test-frames

# Capture 5 frames
./target/release/linux-hello capture --output ~/test-frames --count 5

Expected: Creates PNG files in ~/test-frames/ (if camera available).

2.4 Test Face Detection (with image file)

# Test detection on a photo
./target/release/linux-hello detect --image ~/test-frames/frame_000.png --output ~/detected.png

Expected:

• With ONNX models: Accurate face detection with bounding boxes
• Without ONNX: Basic placeholder detection (unreliable)

---

Step 3: Test with Daemon (Manual Start)

Before installing system-wide, test the daemon manually:

3.1 Start Daemon Manually

# Create runtime directory
sudo mkdir -p /run/linux-hello
sudo chmod 777 /run/linux-hello  # For testing only!

# Start daemon in foreground (to see logs)
sudo ./target/release/linux-hello-daemon

Keep this terminal open - you'll see daemon logs.

3.2 Test Enrollment (in another terminal)

# In a new terminal, test enrollment
./target/release/linux-hello enroll --label test

Expected:

• Captures frames from camera
• Runs anti-spoofing checks
• Creates face template
• Stores encrypted in /var/lib/linux-hello/templates/

3.3 Test Authentication

# Test authentication
./target/release/linux-hello test

Expected:

• Captures frame from camera
• Runs face detection
• Compares with enrolled template
• Reports success/failure with confidence score

3.4 List Enrolled Templates

./target/release/linux-hello list

---

Step 4: Full Installation (Optional)

Warning: This modifies system PAM configuration. Test in a VM or have a recovery plan.

4.1 Build PAM Module

cd pam-module
make

4.2 Install Components

# Install PAM module
sudo make install

# Install daemon and CLI
sudo cp ../target/release/linux-hello-daemon /usr/libexec/
sudo cp ../target/release/linux-hello /usr/bin/
sudo chmod +x /usr/libexec/linux-hello-daemon /usr/bin/linux-hello

# Install systemd service
sudo cp ../dist/linux-hello.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable linux-hello.service
sudo systemctl start linux-hello.service

# Install D-Bus configuration
sudo cp ../dist/org.linuxhello.Daemon.conf /etc/dbus-1/system.d/
sudo cp ../dist/org.linuxhello.Daemon.service /usr/share/dbus-1/system-services/

# Install configuration
sudo mkdir -p /etc/linux-hello
sudo cp ../dist/config.toml /etc/linux-hello/

4.3 Configure PAM (CAREFUL!)

Backup first:

sudo cp /etc/pam.d/common-auth /etc/pam.d/common-auth.backup

Edit PAM config:

sudo nano /etc/pam.d/common-auth

Add at the top:

auth sufficient pam_linux_hello.so debug fallback=password
auth required pam_unix.so use_first_pass

Test login:

• Try logging out and back in
• Face authentication will be attempted first
• Falls back to password if it fails

---

Step 5: ONNX Model Setup (For Real Face Recognition)

For accurate face recognition, you need ONNX models:

5.1 Check System Requirements

ONNX support requires glibc 2.38+:

• Ubuntu 24.04 or later
• Fedora 39 or later
• Arch Linux (rolling release)

# Check your glibc version
ldd --version

5.2 Download Models

See models/README.md for model download instructions.

5.3 Build with ONNX

cargo build --release --features onnx

---

Step 6: Troubleshooting

Daemon Won't Start

# Check if socket directory exists
ls -la /run/linux-hello/

# Check daemon logs
sudo journalctl -u linux-hello.service -f

Camera Not Detected

# List V4L2 devices
v4l2-ctl --list-devices

# Check permissions
ls -la /dev/video*

# May need to add user to video group
sudo usermod -aG video $USER
# Log out and back in

Permission Errors

# Template storage directory
sudo mkdir -p /var/lib/linux-hello/templates
sudo chmod 755 /var/lib/linux-hello/templates

# Runtime directory
sudo mkdir -p /run/linux-hello
sudo chmod 755 /run/linux-hello

PAM Module Issues

# Check if module is installed
ls -la /lib/x86_64-linux-gnu/security/pam_linux_hello.so

# Check PAM logs
sudo tail -f /var/log/auth.log
# or
sudo journalctl -f | grep pam

ONNX Linking Errors

If you see errors about __isoc23_strtoll:

• Your system has glibc < 2.38
• Use the default build (without --features onnx)
• Or upgrade to Ubuntu 24.04+ / Fedora 39+

---

Step 7: Running Tests

# Run all tests
cargo test

# Run specific test suites
cargo test --test phase3_security_test
cargo test --test phase2_auth_test

# Run with output
cargo test -- --nocapture

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

---

Step 8: Cleanup (If Needed)

Remove Installation

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

# Remove PAM module
cd pam-module
sudo make uninstall

# Remove binaries
sudo rm /usr/libexec/linux-hello-daemon
sudo rm /usr/bin/linux-hello

# Remove service file
sudo rm /etc/systemd/system/linux-hello.service
sudo systemctl daemon-reload

# Remove D-Bus files
sudo rm /etc/dbus-1/system.d/org.linuxhello.Daemon.conf
sudo rm /usr/share/dbus-1/system-services/org.linuxhello.Daemon.service

# Restore PAM config
sudo cp /etc/pam.d/common-auth.backup /etc/pam.d/common-auth

---

Safety Recommendations

1. Test in a VM first - Don't test on your main system
2. Keep password fallback - Always have fallback=password in PAM config
3. Backup PAM configs - Before modifying /etc/pam.d/
4. Test logout/login - In a separate session (don't lock yourself out)
5. Use TPM for production - Software fallback is for development only

---

Quick Test Checklist

• Project builds successfully
• CLI tool runs (./target/release/linux-hello status)
• Camera enumeration works (or shows empty list)
• Configuration displays correctly
• Daemon starts manually
• Enrollment works (creates template)
• Authentication test runs
• Tests pass (cargo test)

---

What Works With/Without ONNX

Default Build (No ONNX)

• All infrastructure and security features
• Camera capture and IR control
• Anti-spoofing framework
• Template encryption (AES-256-GCM)
• IPC and D-Bus communication
• Placeholder face detection/embedding (not accurate)

With ONNX Models

• Accurate face detection (RetinaFace)
• Accurate face embedding (MobileFaceNet)
• Production-ready face recognition
• Proper anti-spoofing based on real face data

---

The system is feature-complete. For production use, build with --features onnx on a compatible system and download the ONNX models.