Installation & Setup - FeitianTech/postquantum-webauthn-platform GitHub Wiki

Installation & Setup

Table of Contents

  1. Local Development Setup
  2. Docker Containerization
  3. Cloud Deployment with Render
  4. Configuration Options
  5. Google Cloud Storage Setup
  6. Post-Quantum Cryptography Setup
  7. Troubleshooting Guide

Local Development Setup

To set up the Post-Quantum WebAuthn Platform for local development, follow these step-by-step instructions using Python virtual environments and pip dependency management.

Prerequisites

  • Python 3.12 or higher with pip
  • Git for repository cloning
  • A modern browser with WebAuthn support (Chrome, Edge, Safari, or Firefox)

Virtual Environment and Dependency Installation

Create and activate a Python virtual environment, then install dependencies from requirements.txt:

Windows (PowerShell):

py -3.12 -m venv .venv
.\.venv\scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

The requirements.txt file specifies essential dependencies including Flask, fido2, cryptography, cbor2, and Google Cloud Storage libraries that enable the core WebAuthn functionality and cloud integration.

Section sources

Docker Containerization

The platform provides a comprehensive Dockerfile for containerized deployment, which handles both build and runtime environments with proper liboqs integration.

Docker Build Process

The Dockerfile uses a multi-stage build process with separate builder and runtime stages:

docker build -t postquantum-webauthn-platform .

The build process:

  1. Uses python:3.12-slim as base image
  2. Installs build dependencies (build-essential, cmake, git, etc.)
  3. Copies prebuilt liboqs libraries to /opt/liboqs
  4. Configures library paths via ldconfig
  5. Installs Python dependencies including the liboqs-python wheel
  6. Creates a minimal runtime image with only necessary components

Runtime Configuration

The runtime container exposes port 8000 and uses gunicorn as the WSGI server. The CMD instruction includes LD_PRELOAD to ensure liboqs is properly loaded:

CMD ["/bin/sh", "-c", "export LD_PRELOAD=/opt/liboqs/lib/liboqs.so; exec gunicorn --bind 0.0.0.0:${PORT:-8000} server.app:app"]

Environment variables can be passed to customize the runtime behavior, particularly the PORT variable which defaults to 8000.

Section sources

Cloud Deployment with Render

The platform includes a render.yaml configuration file for seamless deployment to the Render cloud platform.

Render Configuration

The render.yaml file defines a web service with the following specifications:

  • Service type: web
  • Name: python-fido2-webauthn-demo
  • Runtime: docker (using the provided Dockerfile)
  • Plan: free tier
  • Automatic deployment on git push
services:
  - type: web
    name: python-fido2-webauthn-demo
    runtime: docker
    plan: free
    dockerfilePath: ./Dockerfile
    dockerContext: .
    autoDeploy: true

Environment Variable Configuration

When deploying to Render, configure the following environment variables in the web service settings:

  • FIDO_SERVER_SECRET_KEY: Cryptographic key for Flask session management
  • FIDO_SERVER_RP_NAME: Relying Party name (e.g., "My WebAuthn Service")
  • FIDO_SERVER_RP_ID: Relying Party identifier (domain name)
  • FIDO_SERVER_GCS_ENABLED: Set to "true" to enable Google Cloud Storage
  • FIDO_SERVER_GCS_PROJECT: Google Cloud project ID
  • FIDO_SERVER_GCS_BUCKET: Cloud Storage bucket name
  • FIDO_SERVER_GCS_CREDENTIALS_JSON: Service account credentials JSON

Scaling Considerations

The free plan on Render provides basic hosting capabilities. For production workloads, consider upgrading to a higher tier to:

  • Increase CPU and memory allocation
  • Enable persistent storage
  • Configure custom domains with SSL
  • Set up environment-specific deployments (staging, production)
  • Adjust instance count based on authentication request volume

Section sources

Configuration Options

The server configuration is managed through environment variables and the config.py file, providing flexibility for different deployment scenarios.

Core Configuration Parameters

The following configuration options can be set via environment variables in server/server/config.py:

  • DEBUG: Enables debug mode when set to "true", providing detailed error messages and auto-reloading
  • SECRET_KEY: Cryptographic key for session management, configurable via FIDO_SERVER_SECRET_KEY environment variable or file
  • STORAGE_BACKEND: Determines storage mechanism (local filesystem or Google Cloud Storage)
  • GOOGLE_CLOUD_PROJECT: Specifies the Google Cloud project for GCS integration
  • MDS_ROOT_CERTS: Root certificates for FIDO Metadata Service validation

Secret Key Management

The system resolves the secret key through a hierarchy of sources:

  1. FIDO_SERVER_SECRET_KEY environment variable
  2. FIDO_SERVER_SECRET_KEY_FILE pointing to a key file
  3. Generated key stored in instance/session-secret.key

The key resolution process ensures secure default behavior while allowing flexible configuration for different environments.

Relying Party Configuration

Configure the Relying Party (RP) settings:

  • FIDO_SERVER_RP_NAME: Display name for the service
  • FIDO_SERVER_RP_ID: Domain identifier for WebAuthn operations

These values can be overridden by environment variables and are used to create the PublicKeyCredentialRpEntity for WebAuthn protocol compliance.

Section sources

Google Cloud Storage Setup

The platform supports Google Cloud Storage (GCS) for persistent credential storage and metadata management.

Enabling Cloud Storage

Enable GCS integration by setting the FIDO_SERVER_GCS_ENABLED environment variable to "true". When disabled, the system defaults to local file storage.

Required Configuration

To configure GCS integration, set the following environment variables:

  • FIDO_SERVER_GCS_BUCKET: Name of the GCS bucket for storage
  • FIDO_SERVER_GCS_PROJECT: Google Cloud project ID
  • FIDO_SERVER_GCS_CREDENTIALS_FILE: Path to service account key file, or
  • FIDO_SERVER_GCS_CREDENTIALS_JSON: Service account credentials as JSON string

Authentication Methods

The system supports multiple authentication methods:

  1. Service account key file via FIDO_SERVER_GCS_CREDENTIALS_FILE
  2. Service account credentials JSON via FIDO_SERVER_GCS_CREDENTIALS_JSON
  3. Default application credentials when running on Google Cloud

Storage Operations

The cloud_storage.py module provides retry logic for transient failures and implements operations including:

  • upload_bytes: Store binary data in GCS
  • download_bytes: Retrieve data from GCS
  • delete_blob: Remove stored objects
  • list_blob_names: Enumerate stored items
  • blob_exists: Check object existence

The system automatically creates the storage client and validates bucket accessibility during startup.

Section sources

Post-Quantum Cryptography Setup

The platform integrates liboqs for post-quantum cryptographic algorithms, specifically supporting ML-DSA variants.

PQC Algorithm Support

The system supports the following ML-DSA algorithms:

  • ML-DSA-44 (COSE algorithm ID -48)
  • ML-DSA-65 (COSE algorithm ID -49)
  • ML-DSA-87 (COSE algorithm ID -50)

These are mapped in the PQC_ALGORITHM_ID_TO_NAME dictionary in pqc.py and automatically detected when liboqs is available.

Building and Linking liboqs

The platform includes prebuilt liboqs components in the prebuilt_liboqs/linux-x86_64 directory. During Docker build, these are copied to /opt/liboqs and configured in the library path.

For manual setup:

  1. Build liboqs with ML-DSA enabled: cmake -S . -B build -DOQS_BUILD_SIG_MLDSA=ON
  2. Install the shared library to a location in the system library path
  3. Set LD_LIBRARY_PATH to include the liboqs library directory
  4. Install the liboqs-python bindings via pip

Verification

Verify PQC setup by running:

python -c "import oqs; print(oqs.get_enabled_sigs())"

The output should include ML-DSA-44, ML-DSA-65, and ML-DSA-87 in the list of enabled signature mechanisms.

Section sources

Troubleshooting Guide

Missing liboqs Dependencies

Symptom: ImportError: oqs bindings are unavailable Solution:

  1. Verify liboqs shared library is in the library path
  2. Check LD_LIBRARY_PATH includes the liboqs library directory
  3. Ensure the library file (liboqs.so or oqs.dll) is accessible
  4. Validate architecture compatibility (x86_64)

HID Device Permissions

Symptom: Unable to access FIDO security keys Solution: Linux: Add udev rules for FIDO devices:

echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="*", ATTRS{idProduct}=="*", TAG+="uaccess"' | sudo tee /etc/udev/rules.d/99-fido.rules
sudo udevadm control --reload-rules

macOS: Ensure the application has permission to access USB devices in System Preferences > Security & Privacy > Privacy > USB.

Metadata Service Connectivity

Symptom: Failed to download metadata BLOB Solution:

  1. Verify network connectivity to https://mds3.fidoalliance.org/
  2. Check firewall rules allow outbound HTTPS traffic
  3. Validate TLS certificate trust chain
  4. Ensure the FIDO_METADATA_TRUST_ROOT_CERT is correctly configured

Google Cloud Storage Issues

Symptom: Failed to verify Google Cloud Storage readiness Solution:

  1. Verify FIDO_SERVER_GCS_ENABLED is set to "true"
  2. Confirm FIDO_SERVER_GCS_BUCKET is correctly specified
  3. Validate service account credentials have proper permissions (Storage Object Admin)
  4. Check network connectivity to Google Cloud APIs

SSL/TLS Configuration

Symptom: WebAuthn not working due to insecure context Solution:

  1. Use mkcert to generate locally-trusted development certificates
  2. Name certificate files as demo.ftsafe.demo.pem and demo.ftsafe.demo-key.pem
  3. Ensure the hostname in the certificate matches the server configuration
  4. Run the server with SSL context pointing to the certificate files

Section sources