-
Notifications
You must be signed in to change notification settings - Fork 0
Technology Stack & Dependencies
- Core Technology Stack
- Python Dependencies
- Post-Quantum Cryptography Integration
- Frontend JavaScript Dependencies
- Development and Deployment Tools
- Dependency Analysis
- Workflow Examples
The postquantum-webauthn-platform is built on a modern technology stack designed to support both classical and post-quantum WebAuthn authentication. The architecture follows a client-server model with a Python-based backend and a JavaScript-based frontend, enabling secure credential management through FIDO2/WebAuthn standards.
The platform's core runtime is Python 3.x, specifically targeting Python 3.8 and above as specified in the project configuration. The server-side logic is implemented using the Flask web framework, which provides a lightweight and flexible foundation for handling HTTP requests, routing, and session management. Flask's simplicity allows for rapid development while maintaining the ability to scale and integrate with various extensions and middleware.
The system architecture is organized into distinct components:
- fido2/: Core FIDO2/WebAuthn library implementation with modules for attestation, CTAP2 protocol, and cryptographic operations
- server/: Flask application with routes, configuration, and business logic
- prebuilt_liboqs/: Pre-compiled liboqs library for post-quantum cryptographic operations
- tests/: Comprehensive test suite using pytest for both unit and integration testing
The platform leverages containerization through Docker for consistent deployment across environments, with Render serving as the deployment platform for hosting the application. This combination ensures that the application can be reliably deployed and scaled while maintaining security and performance standards.
Section sources
- pyproject.toml
- server/pyproject.toml
- Dockerfile
- render.yaml
The platform's functionality is enabled by a carefully selected set of Python dependencies that handle various aspects of WebAuthn authentication, cryptographic operations, and system integration. These dependencies are managed through both requirements.txt and pyproject.toml files, ensuring consistent installation and version compatibility.
The primary dependencies include:
cryptography: This library provides essential classical cryptographic operations required for WebAuthn implementation. It handles operations such as key generation, digital signatures, and encryption using established algorithms like ECDSA, RSA, and AES. The dependency is specified with a version range of >=2.6,<45, ensuring compatibility with both older and newer versions while avoiding known issues in specific releases.
cbor2: This dependency handles CBOR (Concise Binary Object Representation) serialization and deserialization, which is fundamental to the CTAP2 protocol used by WebAuthn. CBOR is used to encode and decode messages between the authenticator and the relying party, ensuring efficient binary data exchange. The library is specified at version >=5.6.4, providing stable and performant CBOR operations.
pyjwt: This library is used for parsing and validating JWT (JSON Web Tokens) in the context of MDS3 (Metadata Service) validation. When downloading metadata from the FIDO Alliance, the platform uses pyjwt to verify the authenticity and integrity of the metadata blob, ensuring that attestation statements come from trusted authenticators.
requests: This HTTP client library is used for downloading metadata from external sources, specifically the FIDO MDS3 service. It enables the platform to fetch up-to-date information about authenticator capabilities and trust anchors, which is critical for verifying attestation statements during registration.
google-cloud-storage: This dependency provides persistent storage capabilities for credential artifacts and session metadata. By integrating with Google Cloud Storage, the platform can reliably store and retrieve user credentials and session information across application restarts and deployments.
Additional dependencies include gunicorn as the WSGI server for production deployment, and various Google Cloud libraries (google-api-core, google-auth, google-cloud-core) that facilitate secure authentication and communication with Google Cloud services.
Section sources
- requirements.txt
- pyproject.toml
- server/routes/general.py
The platform's most distinctive feature is its integration of post-quantum cryptographic operations through the liboqs library and its Python bindings. This integration enables the platform to support the ML-DSA (Module-Lattice Digital Signature Algorithm) signature scheme, which is designed to be resistant to attacks from quantum computers.
The integration is implemented through several key components:
liboqs: This is a C library that provides implementations of various post-quantum cryptographic algorithms, including ML-DSA. The platform includes a pre-built version of liboqs in the prebuilt_liboqs directory, specifically compiled for Linux x86_64 architecture. This pre-built library contains the necessary header files and shared libraries to support ML-DSA operations.
oqs Python bindings: These bindings provide a Python interface to the liboqs C library, allowing Python code to invoke post-quantum cryptographic operations. The bindings are installed as a wheel file from the prebuilt_liboqs directory, enabling seamless integration without requiring compilation on the target system.
The ML-DSA algorithm is implemented in three security levels:
- ML-DSA-44: Provides approximately 128 bits of security
- ML-DSA-65: Provides approximately 192 bits of security
- ML-DSA-87: Provides approximately 256 bits of security
These variants are exposed through the COSE (CBOR Object Signing and Encryption) algorithm identifiers -48, -49, and -50 respectively. The server detects available algorithms by querying the liboqs bindings and maps these COSE identifiers to their corresponding ML-DSA parameter sets.
The integration is facilitated through the pqc.py module in the server, which provides functions for:
- Detecting available post-quantum algorithms
- Mapping COSE algorithm identifiers to liboqs mechanism names
- Logging algorithm selection during registration and authentication flows
The Dockerfile includes specific instructions for copying the prebuilt liboqs library and configuring the dynamic linker to ensure the shared library is properly loaded at runtime. This approach allows the platform to use post-quantum cryptography without requiring users to compile liboqs from source.
classDiagram
class PQCHelper {
+PQC_ALGORITHM_ID_TO_NAME : Dict[int, str]
+detect_available_pqc_algorithms() Tuple[Set[int], Optional[str]]
+is_pqc_algorithm(alg_id : int) bool
+describe_algorithm(alg_id : Optional[int]) str
+log_algorithm_selection(stage : str, alg_id : Optional[int]) None
}
class MLDSA44 {
+ALGORITHM : int = -48
+verify(message, signature) bool
+from_cryptography_key(public_key) MLDSA44
}
class MLDSA65 {
+ALGORITHM : int = -49
+verify(message, signature) bool
+from_cryptography_key(public_key) MLDSA65
}
class MLDSA87 {
+ALGORITHM : int = -50
+verify(message, signature) bool
+from_cryptography_key(public_key) MLDSA87
}
class CoseKey {
+verify(message, signature) bool
+from_cryptography_key(public_key) CoseKey
}
PQCHelper --> "uses" CoseKey : for algorithm detection
MLDSA44 --> CoseKey : extends
MLDSA65 --> CoseKey : extends
MLDSA87 --> CoseKey : extends
Diagram sources
- server/pqc.py
- fido2/cose.py
- prebuilt_liboqs/linux-x86_64/include/oqs/sig_ml_dsa.h
Section sources
- server/pqc.py
- fido2/cose.py
- prebuilt_liboqs/linux-x86_64/include/oqs/sig_ml_dsa.h
- Dockerfile
The platform's frontend is built with JavaScript dependencies that enhance the WebAuthn user experience and provide additional functionality for developers and administrators. These dependencies are organized in the server/static/scripts directory and serve various purposes in the application.
WebAuthn API polyfills: The webauthn-json.browser-ponyfill.js library provides a convenient wrapper around the native WebAuthn API, simplifying the integration of WebAuthn functionality in the browser. This polyfill handles the conversion between base64url-encoded strings (used in JSON) and ArrayBuffer objects (used by the WebAuthn API), making it easier to work with credential data in web applications. The library exports functions for credential creation and retrieval, along with utilities for parsing and serializing WebAuthn options and responses.
Codec libraries: The codec.js module provides encoding and decoding capabilities for various data formats used in WebAuthn and CTAP2 protocols. This includes support for CBOR, base64, base64url, and hexadecimal representations of binary data. The codec functionality is exposed through a web interface that allows users to encode and decode payloads, making it easier to debug and understand the data exchanged during authentication flows.
The frontend architecture follows a modular structure with separate directories for different functionality:
- advanced/: Scripts for advanced WebAuthn features and configuration
- decoder/: Tools for encoding and decoding various data formats
- shared/: Common utilities used across different parts of the application
- simple/: Scripts for basic authentication flows
The JavaScript codebase includes comprehensive error handling for WebAuthn operations, translating native DOMException types into user-friendly error messages. For example, NotAllowedError is presented as "User cancelled or no compatible authenticator detected," while SecurityError is shown as "Security error - check your connection and try again."
The frontend also includes browser detection capabilities to identify platform authenticators and available transports (USB, NFC, Bluetooth), helping users understand their authentication options. This information is used to provide appropriate guidance during the registration and authentication processes.
Section sources
- server/static/scripts/shared/webauthn-json.browser-ponyfill.js
- server/static/scripts/decoder/codec.js
- server/static/scripts/advanced/auth-advanced.js
The platform leverages a comprehensive set of development and deployment tools that streamline the development process, ensure consistent environments, and enable reliable production deployment.
pytest: This testing framework is used for comprehensive testing of the platform's functionality. The test suite is organized in the tests/ directory and includes both unit tests and integration tests. The configuration in conftest.py allows for flexible test execution with options to include hardware-in-the-loop tests when appropriate. The test suite covers critical functionality such as CTAP2 protocol implementation, client operations, and metadata processing.
Docker: Containerization is implemented through the Dockerfile, which defines a multi-stage build process. The first stage (python-builder) installs all dependencies, including the prebuilt liboqs library and its Python bindings, while the second stage (runtime) creates a minimal production image. This approach reduces the final image size and attack surface by removing build tools and development dependencies from the runtime environment.
The Docker configuration includes several important features:
- Installation of build dependencies (build-essential, cmake, etc.) in the builder stage
- Copying of the prebuilt liboqs library to /opt/liboqs
- Configuration of the dynamic linker to locate the liboqs shared library
- Installation of Python dependencies including the liboqs Python wheel
- Cleanup of unnecessary files and packages to minimize image size
Render: This platform is used for deployment, as specified in the render.yaml configuration file. Render provides a simple and reliable way to deploy web applications with automatic HTTPS, custom domains, and continuous deployment from the repository. The configuration specifies a web service with a free plan, using the Dockerfile for building and deploying the application.
The deployment process is automated through the Docker build process, which:
- Installs the liboqs Python wheel and other dependencies
- Copies the application code to the container
- Configures the runtime environment with appropriate environment variables
- Sets up the command to run the application using gunicorn
This toolchain enables developers to work in a consistent environment, test changes locally using Docker, and deploy to production with confidence that the application will behave the same way in all environments.
graph TB
subgraph "Development"
A[pytest] --> B[Test Suite]
B --> C[Unit Tests]
B --> D[Integration Tests]
B --> E[Hardware Tests]
end
subgraph "Build"
F[Dockerfile] --> G[Builder Stage]
G --> H[Install Dependencies]
H --> I[Copy liboqs]
I --> J[Compile/Install]
J --> K[Runtime Stage]
K --> L[Minimal Image]
L --> M[Remove Build Tools]
end
subgraph "Deployment"
N[Render] --> O[Web Service]
O --> P[Automatic HTTPS]
P --> Q[Custom Domain]
Q --> R[Continuous Deployment]
end
A --> F
F --> N
Diagram sources
- Dockerfile
- render.yaml
- tests/conftest.py
Section sources
- Dockerfile
- render.yaml
- tests/conftest.py
- tests/test_ctap2.py
The platform's dependencies form a cohesive ecosystem that enables secure, post-quantum resistant WebAuthn authentication. The dependency graph reveals several key relationships and integration points that are critical to the platform's functionality.
The core dependency chain begins with the Flask application, which serves as the entry point for all HTTP requests. The app.py file initializes the Flask application and imports route modules, establishing the request handling pipeline. The config.py file configures the application with essential settings, including the relying party identifier and secret key management.
The fido2 library serves as the foundation for WebAuthn functionality, with the cose.py module providing critical cryptographic operations. This module integrates both classical cryptography (through the cryptography library) and post-quantum cryptography (through the oqs bindings). The cose.py implementation includes specific classes for ML-DSA variants (MLDSA44, MLDSA65, MLDSA87) that inherit from the base CoseKey class, enabling consistent handling of different signature algorithms.
The pqc.py module acts as an adapter between the Flask application and the liboqs bindings, providing a clean interface for detecting and using post-quantum algorithms. This module maps COSE algorithm identifiers to liboqs mechanism names and handles error conditions gracefully, providing informative messages when required dependencies are missing.
The decoder functionality is implemented across multiple files:
- decode.py and encode.py in the server/decoder directory handle the core encoding and decoding logic
- codec.js provides the frontend interface for these operations
- The /api/codec endpoint in routes/general.py exposes this functionality through a REST API
The metadata processing pipeline involves several components:
- The mds3.py module handles parsing and verification of FIDO MDS3 blobs
- The general.py routes manage metadata upload, storage, and retrieval
- The storage.py module persists credential data using Google Cloud Storage
The dependency analysis reveals a well-structured architecture with clear separation of concerns. The platform successfully integrates multiple complex technologies—classical and post-quantum cryptography, WebAuthn protocols, and cloud storage—while maintaining a clean and maintainable codebase.
graph TD
A[Flask Application] --> B[app.py]
B --> C[config.py]
C --> D[Flask Configuration]
C --> E[Relying Party Setup]
A --> F[Routes]
F --> G[general.py]
G --> H[Metadata Management]
G --> I[Credential Storage]
G --> J[Codec API]
A --> K[fido2 Library]
K --> L[cose.py]
L --> M[Classical Crypto]
L --> N[Post-Quantum Crypto]
N --> O[MLDSA44]
N --> P[MLDSA65]
N --> Q[MLDSA87]
A --> R[pqc.py]
R --> S[liboqs Bindings]
S --> T[ML-DSA Operations]
A --> U[decoder]
U --> V[decode.py]
U --> W[encode.py]
V --> X[CBOR Processing]
W --> Y[Canonical Encoding]
A --> Z[Frontend]
Z --> AA[webauthn-json.browser-ponyfill.js]
Z --> AB[codec.js]
S --> |Pre-built| AC[prebuilt_liboqs]
AA --> |Base64url Conversion| AB
G --> |API| AB
L --> |Uses| M
R --> |Detects| T
Diagram sources
- server/app.py
- server/config.py
- server/routes/general.py
- fido2/cose.py
- server/pqc.py
- server/decoder/decode.py
- server/decoder/encode.py
- server/static/scripts/shared/webauthn-json.browser-ponyfill.js
- server/static/scripts/decoder/codec.js
Section sources
- server/app.py
- server/config.py
- server/routes/general.py
- fido2/cose.py
- server/pqc.py
- server/decoder/decode.py
- server/decoder/encode.py
The platform's dependencies work together to enable key WebAuthn workflows, particularly in the context of post-quantum secure credential management. Two critical workflows—credential creation and attestation verification—demonstrate how the various components integrate to provide a secure authentication experience.
The credential creation process begins when a user initiates registration through the frontend interface. The workflow involves several steps that leverage the platform's dependencies:
- The frontend uses webauthn-json.browser-ponyfill.js to convert JSON-formatted registration options into the binary formats required by the WebAuthn API
- The browser invokes the authenticator to create a new credential, which may use ML-DSA as the signature algorithm
- The resulting credential is returned to the frontend, where the ponyfill converts the binary data back to JSON for transmission to the server
- The server receives the registration request and uses the fido2 library to process the attestation object
- If ML-DSA is used, the cose.py module invokes the oqs bindings through the pqc.py helper to verify the signature
- The verified credential is stored in Google Cloud Storage through the storage.py module
This workflow demonstrates the integration of frontend JavaScript dependencies with backend Python components, ensuring seamless data exchange between the browser and server while maintaining cryptographic security.
The attestation verification process ensures that a credential comes from a trusted authenticator. This workflow involves:
- The server downloads the FIDO MDS3 metadata blob using the requests library
- The pyjwt library verifies the JWT signature of the metadata blob using the trust anchor certificate
- The mds3.py module parses the metadata and validates the attestation statement against the authenticator's metadata
- For ML-DSA attestations, the liboqs bindings verify the signature using the appropriate parameter set
- The result is cached in memory and on disk for performance optimization
The verification process is critical for preventing the use of counterfeit or compromised authenticators. By combining metadata validation with cryptographic verification, the platform ensures that only credentials from trusted sources are accepted.
These workflows illustrate how the platform's dependencies work in concert to provide a robust, post-quantum resistant WebAuthn implementation. The integration of classical and post-quantum cryptography, combined with secure metadata validation and persistent storage, creates a comprehensive authentication solution that is prepared for future cryptographic challenges.
Section sources
- server/pqc.py
- fido2/cose.py
- server/routes/general.py
- fido2/mds3.py
- server/storage.py
- server/static/scripts/shared/webauthn-json.browser-ponyfill.js