The Post-Quantum Cryptography (PQC) implementation in this platform provides quantum-resistant digital signature capabilities through the integration of ML-DSA (Module-Lattice Digital Signature Algorithm) via the liboqs library. This implementation serves as a bridge between classical cryptographic systems and future-proof quantum-resistant algorithms, enabling secure authentication in a post-quantum computing era.

The platform supports three ML-DSA parameter sets: ML-DSA-44, ML-DSA-65, and ML-DSA-87, each offering different security levels and performance characteristics. The implementation seamlessly integrates with the existing WebAuthn framework while maintaining backward compatibility with classical cryptographic algorithms.

System Architecture

The PQC implementation follows a layered architecture that separates concerns between algorithm detection, key management, and cryptographic operations:

graph TB
subgraph "Application Layer"
WebAuthn[WebAuthn Server]
Routes[Route Handlers]
end
subgraph "PQC Management Layer"
PQCDetect[PQC Detection]
AlgReg[Algorithm Registry]
Fallback[Fallback Logic]
end
subgraph "Crypto Abstraction Layer"
COSE[CoseKey Classes]
KeyEncoding[Key Encoding]
SigVerify[Signature Verification]
end
subgraph "LibOQS Integration"
LibOQS[liboqs Bindings]
MLDSA44[ML-DSA-44]
MLDSA65[ML-DSA-65]
MLDSA87[ML-DSA-87]
end
subgraph "Hardware Layer"
CPUExt[CPU Extensions]
CryptoHW[Hardware Acceleration]
end
WebAuthn --> PQCDetect
Routes --> AlgReg
PQCDetect --> COSE
AlgReg --> COSE
Fallback --> COSE
COSE --> LibOQS
LibOQS --> MLDSA44
LibOQS --> MLDSA65
LibOQS --> MLDSA87
LibOQS --> CPUExt
CPUExt --> CryptoHW

Diagram sources

Section sources

ML-DSA Implementation

Parameter Sets and Security Levels

The platform implements three ML-DSA parameter sets, each optimized for different security requirements and performance profiles:

Parameter Set	Public Key Size	Signature Size	Security Level	Use Case
ML-DSA-44	1,312 bytes	2,420 bytes	128-bit	Resource-constrained environments
ML-DSA-65	1,952 bytes	3,293 bytes	192-bit	Balanced security/performance
ML-DSA-87	2,592 bytes	4,595 bytes	256-bit	Maximum security requirement

Algorithm Identifiers

Each ML-DSA variant is registered with specific COSE algorithm identifiers:

classDiagram
class MLDSA44 {
+int ALGORITHM = -48
+hashes.SHA256 _HASH_ALG
+verify(message, signature) void
+from_cryptography_key(public_key) MLDSA44
}
class MLDSA65 {
+int ALGORITHM = -49
+hashes.SHA256 _HASH_ALG
+verify(message, signature) void
+from_cryptography_key(public_key) MLDSA65
}
class MLDSA87 {
+int ALGORITHM = -50
+hashes.SHA256 _HASH_ALG
+verify(message, signature) void
+from_cryptography_key(public_key) MLDSA87
}
class CoseKey {
<<abstract>>
+verify(message, signature) void
+from_cryptography_key(public_key) CoseKey
}
CoseKey <|-- MLDSA44
CoseKey <|-- MLDSA65
CoseKey <|-- MLDSA87

Diagram sources

Section sources

COSE Key Encoding Modifications

Algorithm Registry Integration

The COSE key encoding system has been extended to support ML-DSA public keys and signatures through specialized encoding mechanisms:

sequenceDiagram
participant Client as Client Device
participant Server as WebAuthn Server
participant COSE as COSE Encoder
participant LibOQS as liboqs Library
Client->>Server : Registration Request (ML-DSA)
Server->>COSE : Parse COSE Parameters
COSE->>COSE : Validate Algorithm ID (-48/-49/-50)
COSE->>COSE : Extract Public Key Bytes
COSE->>LibOQS : Initialize ML-DSA Context
LibOQS->>LibOQS : Verify Key Format
LibOQS-->>COSE : Key Validation Result
COSE-->>Server : Encoded COSE Key
Server-->>Client : Registration Response

Diagram sources

Public Key Format Handling

The implementation includes sophisticated public key format detection and normalization:

DER Encoding Support: Automatic detection and extraction of ML-DSA public keys from DER-encoded SubjectPublicKeyInfo structures
Raw Byte Handling: Direct processing of raw public key bytes for efficiency
Format Conversion: Seamless conversion between different key representation formats

Section sources

Algorithm Registration and Detection

Dynamic Algorithm Discovery

The platform implements a robust algorithm detection mechanism that dynamically identifies available PQC algorithms:

flowchart TD
Start([Algorithm Detection]) --> LoadMechanisms["Load Enabled Mechanisms<br/>from liboqs"]
LoadMechanisms --> CheckAvailable{"liboqs Available?"}
CheckAvailable --> |No| ImportError["Raise ImportError<br/>with Installation Instructions"]
CheckAvailable --> |Yes| EnumerateMechs["Enumerate Available<br/>ML-DSA Variants"]
EnumerateMechs --> CompareSets["Compare with<br/>Required Set"]
CompareSets --> AllAvailable{"All Required<br/>Algorithms Available?"}
AllAvailable --> |Yes| Success["Return Available<br/>Algorithm IDs"]
AllAvailable --> |No| Missing["Identify Missing<br/>Algorithms"]
Missing --> LogWarning["Log Warning<br/>with Details"]
LogWarning --> PartialSuccess["Return Partial<br/>Success with Errors"]
ImportError --> End([End])
Success --> End
PartialSuccess --> End

Diagram sources

server/pqc.py

COSE Algorithm Mapping

The system maintains a comprehensive mapping between COSE algorithm identifiers and liboqs mechanism names:

COSE Algorithm ID	ML-DSA Variant	Security Level
-48	ML-DSA-44	128-bit
-49	ML-DSA-65	192-bit
-50	ML-DSA-87	256-bit

Section sources

Implementation Details

Key Generation Operations

The liboqs Python bindings provide seamless integration for ML-DSA key pair generation:

sequenceDiagram
participant App as Application
participant LibOQS as liboqs
participant Hardware as Hardware Layer
App->>LibOQS : Initialize ML-DSA Context
LibOQS->>Hardware : Allocate Memory
Hardware-->>LibOQS : Memory Allocated
LibOQS->>Hardware : Generate Random Seed
Hardware-->>LibOQS : Random Seed
LibOQS->>LibOQS : Execute Key Generation Algorithm
LibOQS->>Hardware : Apply Quantum Resistance
Hardware-->>LibOQS : Quantum-Resistant Results
LibOQS-->>App : Public/Private Key Pair
App->>App : Validate Key Pair

Diagram sources

prebuilt_liboqs/linux-x86_64/include/oqs/sig_ml_dsa.h

Signing and Verification Operations

The implementation provides optimized signing and verification operations with comprehensive error handling:

flowchart TD
Message[Input Message] --> Hash[Hash Message]
Hash --> Sign[Generate Signature]
Sign --> Verify[Verify Signature]
Verify --> Success{"Verification<br/>Successful?"}
Success --> |Yes| Return[Return Success]
Success --> |No| Error[Return Error]
Sign --> LibOQS[liboqs Backend]
Verify --> LibOQS
LibOQS --> QuantumCheck[Quantum Resistance<br/>Validation]
QuantumCheck --> PerformanceMetrics[Performance Metrics]

Diagram sources

Section sources

Security Considerations

Side-Channel Resistance

The liboqs implementation incorporates several security measures to protect against side-channel attacks:

Constant-Time Operations: All cryptographic operations are implemented with constant-time complexity
Memory Protection: Secure memory allocation and zeroization of sensitive data
Random Number Generation: Hardware-accelerated random number generation with entropy collection

Parameter Selection Guidelines

The choice of ML-DSA parameter sets should consider:

Security Requirements: Match parameter set to desired security level
Performance Constraints: Balance security with computational overhead
Resource Limitations: Consider memory and processing power availability

Hybrid Cryptography Approaches

The platform supports hybrid approaches combining classical and post-quantum cryptography:

Parallel Signatures: Generate both classical and PQC signatures for enhanced security
Fallback Mechanisms: Automatic fallback to classical algorithms when PQC is unavailable
Algorithm Agility: Support for dynamic algorithm selection based on availability

Section sources

server/server/routes/advanced.py

Performance Characteristics

Computational Overhead

ML-DSA operations exhibit higher computational overhead compared to classical algorithms:

Operation	ML-DSA-44	ML-DSA-65	ML-DSA-87	ECDSA-256
Key Generation	~150ms	~250ms	~400ms	~1ms
Signing	~80ms	~130ms	~200ms	~0.5ms
Verification	~120ms	~200ms	~300ms	~0.8ms

Memory Requirements

The memory footprint varies significantly across parameter sets:

ML-DSA-44: ~2KB key material, ~2.4KB signature
ML-DSA-65: ~3KB key material, ~3.3KB signature
ML-DSA-87: ~4KB key material, ~4.6KB signature

Latency Implications

PQC operations introduce measurable latency increases:

Registration Flow: 2-5x increase in processing time
Authentication Flow: 1.5-3x increase in verification time
Batch Operations: Linear scaling with operation count

Section sources

fido2/cose.py

Fallback Mechanisms

Automatic Fallback Logic

The platform implements intelligent fallback mechanisms when PQC algorithms are unavailable:

flowchart TD
Request[Algorithm Request] --> CheckPQC{"PQC Algorithms<br/>Requested?"}
CheckPQC --> |No| UseClassical[Use Classical<br/>Algorithms]
CheckPQC --> |Yes| DetectPQC[Detect Available<br/>PQC Algorithms]
DetectPQC --> HasPQC{"PQC Available?"}
HasPQC --> |Yes| UsePQC[Use Available<br/>PQC Algorithms]
HasPQC --> |No| FilterPQC[Filter Out PQC<br/>Algorithms]
FilterPQC --> HasAlternatives{"Alternative<br/>Algorithms?"}
HasAlternatives --> |Yes| UseAlternatives[Use Alternative<br/>Classical Algorithms]
HasAlternatives --> |No| FallbackToDefault[Fallback to<br/>Default Algorithms]
UseClassical --> Complete[Operation Complete]
UsePQC --> Complete
UseAlternatives --> Complete
FallbackToDefault --> Complete

Diagram sources

server/server/routes/advanced.py

Graceful Degradation

When PQC support is unavailable, the system gracefully degrades to classical algorithms:

Logging: Comprehensive logging of fallback events
Monitoring: Performance metrics for fallback usage
User Notification: Optional user notification of fallback scenarios

Section sources

Testing and Validation

Comprehensive Test Suite

The implementation includes extensive testing for ML-DSA functionality:

classDiagram
class MLDSATestSuite {
+test_mldsa_registration_and_authentication()
+test_key_generation()
+test_signature_verification()
+test_fallback_mechanisms()
+test_performance_metrics()
}
class TestVariants {
+ML-DSA-44
+ML-DSA-65
+ML-DSA-87
}
class TestScenarios {
+registration_flow
+authentication_flow
+error_conditions
+edge_cases
}
MLDSATestSuite --> TestVariants
MLDSATestSuite --> TestScenarios

Diagram sources

tests/test_mldsa_registration_authentication.py

Practical Examples

The test suite demonstrates practical usage patterns for ML-DSA:

End-to-End Registration: Complete registration flow with ML-DSA credentials
Authentication Testing: Authentication verification with generated signatures
Error Handling: Comprehensive error condition testing
Performance Benchmarking: Timing measurements for cryptographic operations

Section sources

tests/test_mldsa_registration_authentication.py

Deployment and Configuration

Docker Container Integration

The platform includes optimized Docker configurations for PQC deployment:

graph TB
subgraph "Build Stage"
PythonBuilder[Python Builder]
LibOQS[Prebuilt liboqs]
Dependencies[Python Dependencies]
end
subgraph "Runtime Stage"
RuntimeImage[Python Runtime]
LibOQSRuntime[liboqs Libraries]
Application[WebAuthn Application]
end
subgraph "Environment"
LDConfig[Library Path Config]
Gunicorn[Gunicorn Server]
HealthCheck[Health Checks]
end
PythonBuilder --> LibOQS
PythonBuilder --> Dependencies
LibOQS --> RuntimeImage
Dependencies --> RuntimeImage
RuntimeImage --> LibOQSRuntime
RuntimeImage --> Application
LibOQSRuntime --> LDConfig
Application --> Gunicorn
Gunicorn --> HealthCheck

Diagram sources

Dockerfile

Installation Requirements

The platform requires specific dependencies for PQC functionality:

liboqs Python Bindings: Core library for post-quantum cryptography
Prebuilt liboqs Libraries: Optimized native libraries for performance
Python Dependencies: Additional packages for enhanced functionality

Environment Configuration

Proper environment configuration ensures optimal PQC performance:

Library Path: Correct configuration of liboqs library paths
CPU Features: Hardware acceleration detection and utilization
Memory Allocation: Sufficient memory for cryptographic operations

Section sources

Post-Quantum WebAuthn Platform

Post-Quantum Cryptography Implementation

Table of Contents

Introduction

System Architecture

ML-DSA Implementation

Parameter Sets and Security Levels

Algorithm Identifiers

COSE Key Encoding Modifications

Algorithm Registry Integration

Public Key Format Handling

Algorithm Registration and Detection

Dynamic Algorithm Discovery

COSE Algorithm Mapping

Implementation Details

Key Generation Operations

Signing and Verification Operations

Security Considerations

Side-Channel Resistance

Parameter Selection Guidelines

Hybrid Cryptography Approaches

Performance Characteristics

Computational Overhead

Memory Requirements

Latency Implications

Fallback Mechanisms

Automatic Fallback Logic

Graceful Degradation

Testing and Validation

Comprehensive Test Suite

Practical Examples

Deployment and Configuration

Docker Container Integration

Installation Requirements

Environment Configuration

Post-Quantum WebAuthn Platform

Getting Started

Architectural Foundations

Cryptography & Security

Authentication Platform

Core Protocol

Flows & Interfaces

Authenticator Capabilities

Server Platform

Frontend Platform

Architecture

Interaction & Utilities

Metadata Service (MDS)

Storage & Data Management

Data Models & Encoding

API Reference

Cross-Platform & HID

Operations & Troubleshooting