FIDO2/WebAuthn Test Platform and Developer Tools

Main Deployment (Google Cloud): https://webauthnlab.tech

Backup Deployment (Render): https://pqcwebauthn.onrender.com

Note: Due to the server’s automatic shut down during inactivity, a few seconds of cold start is expected.

This project provides an end-to-end platform for exploring WebAuthn user flows secured by post-quantum cryptography. The hosted demo and local setup instructions help you register authenticators, run authentication process, and compare PQC signature suites in a realistic WebAuthn environment. Decoder is integrated for decoding attestation objects, WebAuthn type CBOR responses, authenticator metadata, etc. A FIDO MDS explorer is also built for direct retrieval of authenticator metadata information, and conducting root certificate verification.

💻 Local Setup

Scope - Includes: Python, virtual environment, Flask, python-fido2, and Post-Quantum Crypto (PQC) algorithms. - Currently supporting ML-DSA 44/65/87 for PQC

---

✅ Supported Platforms

• Windows 10/11 (64-bit)

• macOS (Intel or Apple Silicon)

A modern browser with WebAuthn support is required: - Edge, Chrome, Safari, Firefox

---

1. Prerequisites

• Git: (https://git-scm.com/)

• Python 3.12+ (64-bit) with pip (https://www.python.org/downloads/)

---

2. Clone the Repository

git clone https://github.com/FeitianTech/postquantum-webauthn-platform.git
cd postquantum-webauthn-platform

---

3. Setup — pip + venv

Windows (PowerShell)

# Create and activate a virtual environment
py -3.12 -m venv .venv
.\.venv\scripts\activate

# Upgrade pip and install runtime dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt

# Optional: PC/SC smart card extras
pip install "fido2[pcsc]"

macOS

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Upgrade pip and install runtime dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt

# Optional: PC/SC smart card extras
pip install "fido2[pcsc]"

🔐 PQC Setup

1. Activate Your Python Virtual Environment

Windows (PowerShell):

.\.venv\scripts\activate

macOS:

source .venv/bin/activate

2. Install PQC Cryptography Libraries

Using pip / virtualenv

pip install ".[pqc]"
python -c "import oqs"

3. Install Open Quantum Safe (OQS) Libraries

Install liboqs

Windows

# Clone liboqs
git clone --branch main https://github.com/open-quantum-safe/liboqs.git
cd liboqs

# Configure build
cmake -S . -B build -DOQS_BUILD_SHARED_LIBS=ON -DOQS_USE_OPENSSL=OFF

# Build in Release mode
cmake --build build --config Release

Output: build\bin\Release\oqs.dll

Copy the DLL into your Python venv so oqs can find it:

copy build\bin\Release\oqs.dll C:\path\to\your\venv\Lib\site-packages\oqs\

Or add the folder to your PATH.

macOS

# Clone liboqs
git clone --branch main https://github.com/open-quantum-safe/liboqs.git
cd liboqs

# Configure build
cmake -S . -B build -DOQS_BUILD_SHARED_LIBS=ON -DOQS_USE_OPENSSL=OFF

# Build in Release mode
cmake --build build --config Release

# Install the library (requires sudo)
sudo cmake --install build

4. Install liboqs-python

Make sure you already built and installed liboqs (the C library). Now, clone and install the Python wrapper:

# Go to home directory
cd ~

# Clone liboqs-python
git clone https://github.com/open-quantum-safe/liboqs-python.git
cd liboqs-python

# Install into your active virtual environment
pip install .

5. Verify Installation

From your project root (where your .venv is located):

cd ~/postquantum-webauthn-platform
python -c "import oqs; print(oqs.get_version()); print(oqs.get_enabled_sigs())"

If installed correctly, you should see something like:

0.14.0-dev
['ML-DSA-44', 'ML-DSA-65', 'ML-DSA-87', ...]

This indicates the version number and supported algorithms. Make sure every PQC algorithm that you plan to use appears in the list above.

---

🔒 mkcert Setup for Local HTTPS

1. Install mkcert

Windows

# Install Chocolatey
Set-ExecutionPolicy Bypass -Scope Process -Force; `
  [System.Net.ServicePointManager]::SecurityProtocol = `
  [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; `
  iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
# Install mkcert via Chocolatey
choco install mkcert -y

macOS

brew install mkcert
brew install nss   # required for Firefox users
mkcert -install

---

2. Generate Certificates

Windows (PowerShell)

cd C:\path\to\your\project
mkcert demo.ftsafe.demo

macOS (Terminal)

cd /path/to/your/project
mkcert demo.ftsafe.demo

⚠️ Important: - WebAuthn only works on secure contexts (HTTPS or localhost). - Rename files to: - demo.ftsafe.demo.pem - demo.ftsafe.demo-key.pem Otherwise, the program will fail to run.

---

🚀 Quickstart

1. Create and Activate Virtual Environment

Windows (PowerShell)

py -3 -m venv .venv
.\.venv\scripts\activate

macOS

python3 -m venv .venv
source .venv/bin/activate

---

2. Run the Server

python server/server/app.py

The first launch writes a Flask session secret to instance/session-secret.key. Keep that file alongside the application so multiple restarts reuse the same secret; delete it if you need to rotate the key.

Expected output:

Running on https://demo.ftsafe.demo:5000/

Click the link to open the test app in your browser.