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 (faster, optimized)
cargo build --release

This will create:

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

---

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:

• May detect a "face" (placeholder algorithm is very basic)
• Creates annotated image if face detected
• Note: Placeholder detection is unreliable - it just checks image statistics

---

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
• Creates face template
• Stores in /var/lib/linux-hello/templates/ (may need sudo)

Note: With placeholder algorithms, this will work but won't be accurate.

3.3 Test Authentication

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

Expected:

• Attempts to authenticate using your face
• May succeed or fail (placeholder algorithms are unreliable)

3.4 List Enrolled Templates

./target/release/linux-hello list

---

Step 4: Full Installation (Optional - More Invasive)

⚠️ 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
sudo cp ../target/release/linux-hello-daemon /usr/libexec/
sudo chmod +x /usr/libexec/linux-hello-daemon

# 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 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: What to Expect

With Placeholder Algorithms

Face Detection:

• Very basic - just checks image brightness/contrast
• Assumes face is centered if image has "reasonable" contrast
• Not reliable - may detect faces where there aren't any, or miss real faces

Face Recognition:

• Uses image statistics (mean, variance, histogram)
• Cannot reliably distinguish between different people
• May authenticate the wrong person
• May reject the correct person

Anti-Spoofing:

• Framework is implemented
• But depends on accurate face detection (which we don't have)
• Will not effectively prevent photo/video attacks

Expected Behavior

✅ Will work:

• Camera enumeration
• Frame capture
• Template storage/retrieval
• CLI commands
• Daemon communication
• Basic workflow

❌ Will NOT work reliably:

• Actual face recognition
• Accurate authentication
• Spoofing prevention

---

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

# Test PAM module manually
sudo pam_test -a pam_linux_hello.so

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

---

Step 7: Running Tests

Test the codebase itself:

# Run all tests
cargo test --workspace

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

# Run with output
cargo test --workspace -- --nocapture

---

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 daemon
sudo rm /usr/libexec/linux-hello-daemon

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

# 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. Don't use for real security - Placeholder algorithms are not secure

---

Next Steps

Once you've tested the basic functionality:

1. Wait for ONNX models - Real face recognition requires ML models
2. Get TPM2 hardware - For secure template storage
3. Security audit - Before production use
4. Contribute - Help improve the project!

---

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 (may not be accurate)
• Tests pass (cargo test --workspace)

---

Remember: This is development software with placeholder algorithms. It demonstrates the architecture but is NOT suitable for production use until ONNX models are integrated.