FIDO2/WebAuthn Test Platform and Developer Tools

Production Deployment: webauthndev.ftsafe.com

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

Note for Developers: Setting up and building all local dependencies (Python environment, Flask/FIDO2/Cryptography, PQC libraries, liboqs builds, HTTPS certificates, etc.) requires significant configuration time and toolchain setup. For most use cases, it is far more efficient to use the deployed platform directly instead of running on local environment.

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+ 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.