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:**
```bash
sudo apt update
sudo apt install -y \
    build-essential \
    libpam0g-dev \
    v4l-utils \
    pkg-config \
    libssl-dev
```

**Fedora/RHEL:**
```bash
sudo dnf install -y \
    gcc \
    make \
    pam-devel \
    v4l-utils \
    pkgconfig \
    openssl-devel
```

**Arch Linux:**
```bash
sudo pacman -S \
    base-devel \
    pam \
    v4l-utils \
    pkgconf \
    openssl
```

### Install Rust

If you don't have Rust installed:
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

---

## Step 1: Build the Project

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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)

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
./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

```bash
cd pam-module
make
```

### 4.2 Install Components

```bash
# 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:**
```bash
sudo cp /etc/pam.d/common-auth /etc/pam.d/common-auth.backup
```

**Edit PAM config:**
```bash
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)

```bash
# Check your glibc version
ldd --version
```

### 5.2 Download Models

See [models/README.md](models/README.md) for model download instructions.

### 5.3 Build with ONNX

```bash
cargo build --release --features onnx
```

---

## Step 6: Troubleshooting

### Daemon Won't Start

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

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

### Camera Not Detected

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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.