Installation Issues

Installation Issues

Table of Contents

1. Introduction
2. Common Installation Problems
3. Python Dependencies Issues
4. liboqs Library Loading Failures
5. Platform-Specific Compilation Issues
6. Dependency Management Solutions
7. Docker Build Troubleshooting
8. Prebuilt liboqs Integration
9. PYTHONPATH Configuration
10. CMake Integration Validation
11. Installation Validation
12. Diagnostic Commands
13. Troubleshooting Tips

Introduction

The Post-Quantum WebAuthn Platform requires careful setup due to its complex dependencies, particularly the liboqs cryptographic library and Python bindings. This document provides comprehensive solutions for common installation issues encountered during setup.

Common Installation Problems

Missing Python Dependencies

The platform relies on several critical Python packages that must be installed correctly:

• Primary Dependencies: cryptography, cbor2, pyjwt, requests
• Optional Dependencies: pyscard (for PCSC), oqs and pqcrypto (for post-quantum cryptography)
• Runtime Dependencies: Flask, gunicorn, Google Cloud libraries

liboqs Library Loading Failures

The liboqs library is crucial for post-quantum cryptographic operations. Common issues include:

• Library Not Found: The system cannot locate the liboqs shared library
• Version Mismatch: Incompatible versions between Python bindings and native library
• Architecture Mismatch: Using 32-bit vs 64-bit libraries
• Missing Symbols: Functions not available in the loaded library

Platform-Specific Issues

Different operating systems present unique challenges:

• Linux: Library path configuration and package manager dependencies
• macOS: Homebrew dependencies and Xcode command line tools
• Windows: Visual Studio build tools and PATH configuration

Python Dependencies Issues

Dependency Conflicts

The project uses Poetry for dependency management, which can sometimes conflict with existing installations:

flowchart TD
A["Poetry Installation"] --> B["Dependency Resolution"]
B --> C{"Conflicts Detected?"}
C --> |Yes| D["Resolve Conflicts"]
C --> |No| E["Successful Installation"]
D --> F["Manual Override"]
F --> G["Test Dependencies"]
G --> H{"Tests Pass?"}
H --> |No| I["Debug Further"]
H --> |Yes| E
I --> J["Check Specific Packages"]
J --> K["Update Versions"]
K --> D

Loading

Diagram sources

• pyproject.toml
• server/pyproject.toml

Resolving Dependency Conflicts

Using Poetry

Poetry provides the recommended dependency management approach:

# Install dependencies with Poetry
poetry install --with dev

# Install with specific extras
poetry install --extras "pcsc pqc"

# Update dependencies
poetry update

# Show dependency tree
poetry show --tree

Using pip

For environments where Poetry isn't available:

# Install primary dependencies
pip install -r requirements.txt

# Install with extras
pip install fido2[pqc,pcsc]

# Upgrade pip and setuptools first
pip install --upgrade pip setuptools wheel

Section sources

• pyproject.toml
• requirements.txt
• server/pyproject.toml

liboqs Library Loading Failures

Understanding the Error Messages

Common error messages when liboqs fails to load:

ImportError: liboqs library not found
ModuleNotFoundError: No module named 'oqs'
SystemError: liboqs initialization failed

Diagnostic Steps

1. Verify Installation: Check if the liboqs Python package is installed
2. Library Path: Confirm the native library is accessible
3. Version Compatibility: Ensure versions match between Python bindings and native library
4. Architecture: Verify 64-bit compatibility

Solution Approaches

Method 1: Prebuilt Wheels

The project includes prebuilt liboqs wheels for easy installation:

# Install prebuilt liboqs wheel
pip install /opt/liboqs/liboqs_python*.whl

# Verify installation
python -c "import oqs; print(oqs.get_enabled_sig_mechanisms())"

Method 2: Manual Library Configuration

For development or custom builds:

# Set library path
export LD_LIBRARY_PATH=/path/to/liboqs/lib:$LD_LIBRARY_PATH

# On macOS
export DYLD_LIBRARY_PATH=/path/to/liboqs/lib:$DYLD_LIBRARY_PATH

# On Windows
set PATH=C:\path\to\liboqs\lib;%PATH%

Section sources

• server/server/pqc.py
• prebuilt_liboqs/linux-x86_64/liboqs_python-0.14.0-py3-none-any.whl

Platform-Specific Compilation Issues

Linux Compilation Issues

Common Linux compilation problems:

• Missing Build Tools: Missing build-essential, cmake, pkg-config
• Library Dependencies: Missing SSL development libraries
• Permission Issues: Insufficient permissions for system-wide installation

Ubuntu/Debian Solutions

# Install required build tools
sudo apt-get update
sudo apt-get install build-essential cmake pkg-config libssl-dev

# Alternative minimal installation
sudo apt-get install gcc make cmake ninja-build pkg-config

CentOS/RHEL Solutions

# Install development tools
sudo yum groupinstall "Development Tools"
sudo yum install cmake3 openssl-devel

# Use cmake3 instead of cmake
cmake3 .

macOS Compilation Issues

macOS-specific challenges:

• Xcode Command Line Tools: Required for compilation
• Homebrew Dependencies: Often needed for missing libraries
• Apple Silicon: M1/M2 compatibility considerations

macOS Solutions

# Install Xcode command line tools
xcode-select --install

# Install with Homebrew
brew install cmake pkg-config openssl

# Set compiler flags for OpenSSL
export LDFLAGS="-L$(brew --prefix openssl)/lib"
export CPPFLAGS="-I$(brew --prefix openssl)/include"
export PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig"

Windows Compilation Issues

Windows compilation requires specific toolchain setup:

• Visual Studio Build Tools: Required for C++ compilation
• Python Development Headers: Needed for C extensions
• PATH Configuration: Proper environment setup

Windows Solutions

# Install Visual Studio Build Tools
# Download from Microsoft website

# Set environment variables
$env:LIB="C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.xx.xxxxx\lib\x64;$env:LIB"
$env:INCLUDE="C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.xx.xxxxx\include;$env:INCLUDE"

Dependency Management Solutions

Using Poetry for Dependency Management

Poetry provides isolated environments and reproducible builds:

sequenceDiagram
participant Dev as Developer
participant Poetry as Poetry
participant VEnv as Virtual Environment
participant PyPI as PyPI Repository
Dev->>Poetry : poetry install
Poetry->>VEnv : Create virtual environment
Poetry->>PyPI : Resolve dependencies
PyPI-->>Poetry : Return dependency graph
Poetry->>VEnv : Install packages
VEnv-->>Dev : Ready to use

Loading

Diagram sources

• pyproject.toml
• server/pyproject.toml

Poetry Best Practices

# Initialize new project
poetry init

# Add dependencies
poetry add cryptography==45.0.0
poetry add --group dev pytest

# Install with specific extras
poetry install --extras "pqc"

# Export requirements
poetry export -f requirements.txt --output requirements.txt

Using pip for Dependency Management

For simpler setups or when Poetry isn't available:

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Upgrade pip
pip install --upgrade pip setuptools wheel

# Install requirements
pip install -r requirements.txt

# Install with extras
pip install fido2[pqc,pcsc]

Section sources

• pyproject.toml
• requirements.txt
• server/pyproject.toml

Docker Build Troubleshooting

Common Docker Build Failures

The Dockerfile includes comprehensive build steps but can fail at various points:

flowchart TD
A["Docker Build Start"] --> B["Base Image Pull"]
B --> C["Package Installation"]
C --> D["liboqs Copy"]
D --> E["Library Configuration"]
E --> F["Dependencies Installation"]
F --> G{"Build Successful?"}
G --> |No| H["Check Logs"]
G --> |Yes| I["Runtime Setup"]
H --> J["Fix Dependencies"]
J --> K["Retry Build"]
K --> G
I --> L["Final Image"]

Loading

Diagram sources

• Dockerfile

Docker Build Issues and Solutions

Issue 1: Missing Base Dependencies

Problem: Build fails during package installation

E: Unable to locate package build-essential

Solution:

# Ensure proper package updates
RUN apt-get update && apt-get install -y \
    build-essential \
    cmake \
    git \
    libssl-dev \
    pkg-config

Issue 2: Library Path Configuration

Problem: Runtime library loading failures

ImportError: liboqs library not found

Solution: Verify library path configuration in Dockerfile:

# Set library paths
ENV LD_LIBRARY_PATH=/opt/liboqs/lib:/usr/local/lib

# Configure dynamic linker
RUN echo "/opt/liboqs/lib" > /etc/ld.so.conf.d/liboqs.conf && \
    ldconfig

Issue 3: Permission Problems

Problem: Cannot copy files or execute commands

chmod: changing permissions of '/opt/liboqs': Operation not permitted

Solution: Use appropriate user permissions in Dockerfile:

# Use non-root user for security
RUN useradd -m -u 1000 appuser
USER appuser

Docker Compose Troubleshooting

For development environments using Docker Compose:

version: '3.8'
services:
  webauthn:
    build: .
    ports:
      - "8000:8000"
    environment:
      - PYTHONPATH=/app:${PYTHONPATH}
      - LD_LIBRARY_PATH=/opt/liboqs/lib:/usr/local/lib
    volumes:
      - .:/app

Section sources

• Dockerfile
• cloudbuild.yaml

Prebuilt liboqs Integration

Understanding the Prebuilt System

The project includes prebuilt liboqs binaries for simplified deployment:

graph TB
A["Source Code"] --> B["Prebuilt liboqs"]
B --> C["Include Headers"]
B --> D["Shared Libraries"]
B --> E["CMake Configuration"]
C --> F["Header Files"]
D --> G["liboqs.so"]
E --> H["liboqsConfig.cmake"]
F --> I["Compilation"]
G --> J["Runtime Linking"]
H --> K["CMake Integration"]

Loading

Diagram sources

• prebuilt_liboqs/linux-x86_64/include/oqs/oqsconfig.h
• Dockerfile

Verifying Prebuilt Integration

Step 1: Check Library Availability

# Verify liboqs library exists
ls -la prebuilt_liboqs/linux-x86_64/lib/

# Check library version
ldd prebuilt_liboqs/linux-x86_64/lib/liboqs.so | grep oqs

Step 2: Validate CMake Configuration

# Check CMake files
ls -la prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/

# Test CMake configuration
cmake -DCMAKE_PREFIX_PATH=prebuilt_liboqs/linux-x86_64 -P \
    prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/liboqsConfig.cmake

Step 3: Verify Python Bindings

# Test Python bindings
try:
    import oqs
    print(f"liboqs version: {oqs.get_version()}")
    mechanisms = oqs.get_enabled_sig_mechanisms()
    print(f"Enabled mechanisms: {mechanisms}")
except ImportError as e:
    print(f"Import error: {e}")

Manual liboqs Integration

For custom liboqs builds:

# Build liboqs from source
git clone https://github.com/open-quantum-safe/liboqs.git
cd liboqs
mkdir build && cd build
cmake .. -DBUILD_SHARED_LIBS=ON -DOQS_BUILD_ONLY_LIB=OFF
make -j$(nproc)

# Install to system
sudo make install

# Verify installation
ldconfig -p | grep liboqs

Section sources

• prebuilt_liboqs/linux-x86_64/include/oqs/oqsconfig.h
• Dockerfile

PYTHONPATH Configuration

Understanding PYTHONPATH Issues

The application requires proper PYTHONPATH configuration for module imports:

flowchart LR
A["Application Start"] --> B["Discover Project Root"]
B --> C["Add to sys.path"]
C --> D["Import Modules"]
D --> E{"Imports Successful?"}
E --> |No| F["ModuleNotFoundError"]
E --> |Yes| G["Application Running"]
F --> H["Check PYTHONPATH"]
H --> I["Fix Path Configuration"]
I --> B

Loading

Diagram sources

• server/server/app.py

Common PYTHONPATH Problems

Problem 1: Module Not Found

ModuleNotFoundError: No module named 'server.config'

Problem 2: Circular Imports

ImportError: cannot import name 'app' from partially initialized module

Problem 3: Relative Import Failures

ImportError: attempted relative import with no known parent package

Solutions for PYTHONPATH Issues

Method 1: Automatic Discovery

The application includes automatic project root discovery:

def _discover_project_root(package_root: pathlib.Path) -> pathlib.Path:
    """Locate the repository root so local imports take precedence."""
    for candidate in package_root.parents:
        if (candidate / "fido2").is_dir():
            return candidate
    return package_root.parents[1]

Method 2: Manual PYTHONPATH Setting

# Set PYTHONPATH for development
export PYTHONPATH="/path/to/project:$PYTHONPATH"

# For Docker containers
ENV PYTHONPATH=/app:${PYTHONPATH}

# For testing environments
export PYTHONPATH=$(pwd):$PYTHONPATH

Method 3: Virtual Environment Activation

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Verify imports work
python -c "from server.server import app; print('Success')"

Section sources

• server/server/app.py

CMake Integration Validation

Understanding CMake Configuration

The project uses CMake for building and configuring liboqs:

graph TD
A["CMake Configuration"] --> B["Find liboqs"]
B --> C{"liboqs Found?"}
C --> |Yes| D["Configure Targets"]
C --> |No| E["Search Paths"]
E --> F["Try Alternative Locations"]
F --> G{"Found?"}
G --> |Yes| D
G --> |No| H["Build from Source"]
D --> I["Generate Makefiles"]
H --> I
I --> J["Compile"]
J --> K["Link"]

Loading

Diagram sources

• prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/liboqsConfig.cmake
• prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/liboqsTargets.cmake

Validating CMake Integration

Step 1: Check CMake Configuration Files

# Verify CMake files exist
ls -la prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/

# Test CMake configuration
cmake -DCMAKE_PREFIX_PATH=prebuilt_liboqs/linux-x86_64 \
      -P prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/liboqsConfig.cmake

Step 2: Validate Target Configuration

# Check target configuration
cat prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/liboqsTargets.cmake | \
    grep -A 10 "OQS::oqs"

# Verify library locations
cat prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/liboqsTargets-release.cmake

Step 3: Test CMake Find Module

# Create test CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(test_liboqs)

find_package(liboqs REQUIRED)

add_executable(test_app main.cpp)
target_link_libraries(test_app PRIVATE OQS::oqs)

Troubleshooting CMake Issues

Issue 1: CMake Cannot Find liboqs

Problem: Could not find liboqsConfig.cmake

Solution:

# Set CMAKE_PREFIX_PATH
export CMAKE_PREFIX_PATH=/path/to/prebuilt_liboqs:$CMAKE_PREFIX_PATH

# Or use cmake command
cmake -DCMAKE_PREFIX_PATH=/path/to/prebuilt_liboqs ..

Issue 2: Incorrect Library Paths

Problem: Cannot find -loqs

Solution:

# Verify library path
echo $LD_LIBRARY_PATH

# Set library path
export LD_LIBRARY_PATH=/path/to/liboqs/lib:$LD_LIBRARY_PATH

Section sources

• prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/liboqsConfig.cmake
• prebuilt_liboqs/linux-x86_64/lib/cmake/liboqs/liboqsTargets.cmake

Installation Validation

Comprehensive Installation Testing

Test 1: Basic Functionality

# Test core functionality
from fido2.webauthn import AuthenticatorData
from fido2.utils import sha256

# Test basic operations
data = AuthenticatorData(b'\x00' * 32)
print(f"Authenticator data: {data}")

# Test hashing
hash_result = sha256(b"test")
print(f"SHA256 hash: {hash_result.hex()}")

Test 2: Post-Quantum Cryptography

# Test PQC functionality
from server.server.pqc import detect_available_pqc_algorithms

try:
    available, error = detect_available_pqc_algorithms()
    if error:
        print(f"PQC Error: {error}")
    else:
        print(f"Available PQC algorithms: {available}")
except ImportError as e:
    print(f"PQC not available: {e}")

Test 3: Server Startup Validation

# Test server startup
from server.server.startup import warm_up_dependencies

try:
    warm_up_dependencies()
    print("Server dependencies validated successfully")
except Exception as e:
    print(f"Startup validation failed: {e}")

Automated Validation Scripts

Installation Verification Script

#!/bin/bash
# installation-verify.sh

echo "=== Post-Quantum WebAuthn Platform Installation Validator ==="

# Check Python version
echo "Python version:"
python --version

# Check dependencies
echo "Checking dependencies..."
pip list | grep -E "(fido2|cryptography|oqs)"

# Test liboqs
echo "Testing liboqs..."
python -c "
import oqs
print(f'liboqs version: {oqs.get_version()}')
mechs = oqs.get_enabled_sig_mechanisms()
print(f'Enabled mechanisms: {mechs}')
"

# Test server import
echo "Testing server import..."
python -c "
from server.server import app
print('Server import successful')
"

echo "=== Validation Complete ==="

Section sources

• server/server/pqc.py
• server/server/startup.py

Diagnostic Commands

System Information Collection

Operating System Detection

# Linux
uname -a
lsb_release -a  # Ubuntu/Debian
cat /etc/os-release  # Modern distributions

# macOS
uname -a
sw_vers

# Windows
ver

Python Environment Information

# Python version and configuration
python --version
python -m sysconfig

# Virtual environment status
which python
python -c "import sys; print(sys.prefix)"

# Installed packages
pip list --format=columns

Library Path Diagnostics

Dynamic Linker Configuration

# Linux
ldconfig -p | grep oqs
ldd $(which python) | grep oqs

# macOS
otool -L $(which python) | grep oqs
dyld_info -images $(which python)

# Windows
dumpbin /dependents $(which python) | findstr oqs

Environment Variable Checks

# Library path variables
echo "LD_LIBRARY_PATH: $LD_LIBRARY_PATH"
echo "DYLD_LIBRARY_PATH: $DYLD_LIBRARY_PATH"
echo "PATH: $PATH"

# Python path
echo "PYTHONPATH: $PYTHONPATH"
python -c "import sys; print('\n'.join(sys.path))"

Build System Diagnostics

CMake Configuration

# CMake version and configuration
cmake --version
cmake --system-information | head -50

# Find liboqs
cmake -DCMAKE_PREFIX_PATH=/path/to/prebuilt_liboqs \
      -DCMAKE_FIND_DEBUG=ON \
      -P /dev/null

Package Manager Information

# Package manager diagnostics
# Ubuntu/Debian
dpkg -l | grep -E "(cmake|pkg-config|openssl)"

# CentOS/RHEL
rpm -qa | grep -E "(cmake|pkg-config|openssl)"

# macOS (Homebrew)
brew list --versions | grep -E "(cmake|pkg-config|openssl)"

Troubleshooting Tips

General Troubleshooting Workflow

flowchart TD
A["Installation Issue"] --> B["Identify Error Type"]
B --> C{"Dependency Issue?"}
B --> D{"Library Issue?"}
B --> E{"Environment Issue?"}
C --> F["Check Dependencies"]
F --> G["Update/Reinstall"]
D --> H["Check Library Paths"]
H --> I["Verify Installation"]
E --> J["Check Environment Variables"]
J --> K["Fix Configuration"]
G --> L["Test Installation"]
I --> L
K --> L
L --> M{"Works?"}
M --> |Yes| N["Issue Resolved"]
M --> |No| O["Advanced Debugging"]
O --> P["Check Logs"]
P --> Q["Community Support"]

Loading

Specific Issue Solutions

ImportError: No module named 'oqs'

Symptoms: Application fails to start with import errors

Solutions:

1. Verify liboqs Python bindings installation
2. Check PYTHONPATH configuration
3. Ensure compatible Python version
4. Reinstall with correct architecture

liboqs library not found

Symptoms: Runtime errors when importing oqs module

Solutions:

1. Verify library file exists in expected location
2. Check library path configuration
3. Run ldconfig (Linux) or equivalent
4. Verify library architecture compatibility

CMake configuration failures

Symptoms: Build process stops with CMake errors

Solutions:

1. Verify CMake version compatibility
2. Check CMAKE_PREFIX_PATH setting
3. Validate prebuilt liboqs structure
4. Review CMake cache files

Permission denied errors

Symptoms: Installation fails with permission errors

Solutions:

1. Use virtual environment
2. Run with appropriate privileges
3. Check file ownership and permissions
4. Use user-specific installation paths

Performance Optimization

Memory Usage Optimization

# Monitor memory usage during installation
ulimit -a
# Adjust stack size if needed

# Use swap space for large builds
swapon --show

Parallel Build Configuration

# Optimize build parallelism
export CMAKE_BUILD_PARALLEL_LEVEL=4
export MAKEFLAGS="-j4"

# Docker build optimization
docker build --parallel --compress .

Recovery Procedures

Clean Installation

# Remove existing installations
pip uninstall -y fido2 oqs pqcrypto
rm -rf ~/.local/lib/python*/site-packages/fido2*
rm -rf ~/.local/lib/python*/site-packages/oqs*

# Clear caches
pip cache purge
rm -rf ~/.cache/pip

# Fresh installation
pip install -r requirements.txt

Environment Reset

# Create new virtual environment
rm -rf venv
python -m venv venv
source venv/bin/activate

# Fresh installation
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Community Resources

Getting Help

1. GitHub Issues: Report bugs and request features
2. Documentation: Review official documentation
3. Community Forums: Seek help from user community
4. Stack Overflow: Search for similar issues

Contributing Back

1. Bug Reports: Provide detailed reproduction steps
2. Documentation: Improve installation guides
3. Code Contributions: Submit fixes and improvements
4. Testing: Help with quality assurance

This comprehensive guide addresses the most common installation issues while providing practical solutions and diagnostic tools. Regular updates to this documentation ensure continued support for the Post-Quantum WebAuthn Platform.