WebAuthn FIDO2 Test Application With PQC Support

A test server and web UI for WebAuthn/FIDO2 registration and authentication. It displays the selected algorithm, authenticator flags (UP/UV/AT/ED/BE/BS), sign counter, and extension results (credProps, PRF, largeBlob) for validation. This test app also supports functionalities such as decoder, FIDO MDS explorer, etc.

Built on python-fido2-PQC, which extends Yubico’s python-fido2. Classical algorithms work by default.

---

💻 Local Setup

Scope - Includes: Python, virtual environment, Flask, python-fido2, and Post-Quantum Crypto (PQC) algorithm options.

---

✅ 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/rainzhang05/python-fido2-webauthn-test.git
cd python-fido2-webauthn-test

---

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 fido2 flask cryptography cbor2

# 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 fido2 flask cryptography cbor2

# 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 and build
cmake -S . -B build -DOQS_BUILD_SHARED_LIBS=ON -DOQS_USE_OPENSSL=OFF
cmake --build build --config Release

Output: build/lib/liboqs.dylib

Copy to your venv:

cp build/lib/liboqs.dylib /path/to/venv/lib/python3.X/site-packages/oqs/

Or add to DYLD_LIBRARY_PATH:

export DYLD_LIBRARY_PATH=$PWD/build/lib:$DYLD_LIBRARY_PATH

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 .

Step 2. Verify Installation

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

cd ~/IdeaProjects/python-fido2-webauthn-test
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 all PQC algorithm that you would like 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 localhost 127.0.0.1 ::1

macOS (Terminal)

cd /path/to/your/project
mkcert localhost 127.0.0.1 ::1

⚠️ Important: - WebAuthn works on localhost, not 127.0.0.1. - Rename files to: - localhost+1.pem - localhost+1-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.ps1

macOS

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

---

2. Install Dependencies

python -m pip install --upgrade pip
pip install flask fido2

---

3. Run the Server

python examples/server/server/app.py

Expected output:

Running on https://localhost:5000/

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

---

📝 Notes

• Credentials are saved as .pkl files in: examples/server/server

• Deleting credentials in the test app will also delete the corresponding .pkl file locally.

---