PQC Algorithm Detection and Selection

PQC Algorithm Detection and Selection

Table of Contents

1. Introduction
2. System Architecture
3. PQC Algorithm Detection
4. Integration with fido2.features
5. Algorithm Negotiation Process
6. Configuration Options
7. Fallback Mechanisms
8. Testing and Validation
9. Troubleshooting Guide
10. Best Practices

Introduction

The Post-Quantum Cryptography (PQC) algorithm detection and selection mechanism in this WebAuthn platform provides a robust framework for identifying, validating, and utilizing quantum-resistant cryptographic algorithms alongside traditional classical algorithms. The system centers around the ML-DSA family of algorithms (ML-DSA-44, ML-DSA-65, ML-DSA-87) backed by the liboqs (Open Quantum Safe) library, enabling seamless integration of post-quantum cryptography into WebAuthn authentication flows.

The implementation follows a sophisticated detection and fallback strategy that maintains backward compatibility while progressively adopting quantum-resistant algorithms. The system intelligently negotiates algorithm availability between client and server, ensuring optimal security posture regardless of the underlying hardware capabilities.

System Architecture

The PQC mechanism operates through a multi-layered architecture that separates concerns between algorithm detection, validation, negotiation, and fallback management:

graph TB
subgraph "Client Layer"
Client[WebAuthn Client]
Browser[Browser Environment]
end
subgraph "Server Application Layer"
Server[Flask Server]
Routes[Route Handlers]
Config[Configuration Manager]
end
subgraph "PQC Detection Layer"
PQCDetector[PQC Detector]
LibOQS[liboqs Backend]
AlgorithmRegistry[Algorithm Registry]
end
subgraph "WebAuthn Integration Layer"
Fido2Server[Fido2Server]
AlgorithmNegotiator[Algorithm Negotiator]
FeatureFlags[Feature Flags]
end
subgraph "Fallback Management Layer"
ClassicalFallback[Classical Fallback]
WarningLogger[Warning Logger]
StateManager[State Manager]
end
Client --> Browser
Browser --> Server
Server --> Routes
Routes --> Config
Config --> PQCDetector
PQCDetector --> LibOQS
LibOQS --> AlgorithmRegistry
Server --> Fido2Server
Fido2Server --> AlgorithmNegotiator
AlgorithmNegotiator --> FeatureFlags
AlgorithmNegotiator --> ClassicalFallback
ClassicalFallback --> WarningLogger
WarningLogger --> StateManager

Loading

Diagram sources

• server/pqc.py
• server/server/routes/advanced.py
• fido2/features.py

Section sources

• server/pqc.py
• server/server/routes/advanced.py

PQC Algorithm Detection

Core Detection Functions

The PQC detection system centers around several key functions that query the liboqs backend and determine algorithm availability:

flowchart TD
Start([Algorithm Detection Start]) --> LoadMechanisms["_load_enabled_mechanisms()"]
LoadMechanisms --> ImportCheck{Import Available?}
ImportCheck --> |No| ImportError[ImportError: oqs unavailable]
ImportCheck --> |Yes| GetMechanisms[Query Enabled Mechanisms]
GetMechanisms --> DetectAvailable["detect_available_pqc_algorithms()"]
DetectAvailable --> FilterMechanisms[Filter ML-DSA Algorithms]
FilterMechanisms --> CheckAvailability{All Algorithms Available?}
CheckAvailability --> |Yes| Success[Return Available IDs + None]
CheckAvailability --> |No| Missing[Return Missing Algorithms + Error Message]
ImportError --> ErrorHandling[Error Handling & Logging]
Missing --> ErrorHandling
ErrorHandling --> End([Detection Complete])
Success --> End

Loading

Diagram sources

• server/pqc.py

Algorithm Identifier Mapping

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

COSE Algorithm ID	ML-DSA Variant	Description
-50	ML-DSA-87	Highest security level, larger key sizes
-49	ML-DSA-65	Medium security level, balanced performance
-48	ML-DSA-44	Lowest security level, smallest key sizes

Detection Process Implementation

The detection process follows a hierarchical approach to ensure compatibility across different liboqs versions:

1. Primary Detection Method: Uses oqs.get_enabled_sig_mechanisms() for modern liboqs installations
2. Compatibility Fallback: Falls back to oqs.Signature.algorithms for older liboqs versions
3. Error Handling: Comprehensive error reporting for missing dependencies or unsupported algorithms

Section sources

• server/pqc.py

Integration with fido2.features

Feature Flag Management

The system integrates with the fido2.features module to manage PQC functionality at runtime. While the primary PQC detection occurs independently, the feature system provides additional control mechanisms:

classDiagram
class FeatureFlag {
+enabled : bool
+name : str
+description : str
+require(state : bool)
+warn()
}
class PQCFeature {
+detect_available_pqc_algorithms()
+is_pqc_algorithm(alg_id : int)
+log_algorithm_selection(stage : str, alg_id : int)
}
class AlgorithmRegistry {
+PQC_ALGORITHM_ID_TO_NAME : Dict[int, str]
+is_pqc_algorithm(alg_id : int)
+describe_algorithm(alg_id : int)
}
FeatureFlag <|-- PQCFeature
PQCFeature --> AlgorithmRegistry

Loading

Diagram sources

• fido2/features.py
• server/pqc.py

Runtime Control Mechanisms

The integration provides several runtime control mechanisms:

• Automatic Detection: Algorithms are automatically detected during server startup
• Graceful Degradation: Systems gracefully fall back to classical algorithms when PQC is unavailable
• Logging Integration: All PQC operations are logged through the Flask application logger
• Error Reporting: Comprehensive error messages guide administrators toward resolution

Section sources

• fido2/features.py
• server/pqc.py

Algorithm Negotiation Process

WebAuthn Registration Flow

The algorithm negotiation process during WebAuthn registration involves several sophisticated steps:

sequenceDiagram
participant Client as WebAuthn Client
participant Server as Flask Server
participant PQCDetector as PQC Detector
participant LibOQS as liboqs Backend
participant Fido2Server as Fido2 Server
Client->>Server : Registration Request
Server->>Server : Parse publicKeyCredentialParameters
Server->>PQCDetector : detect_available_pqc_algorithms()
PQCDetector->>LibOQS : Query Enabled Mechanisms
LibOQS-->>PQCDetector : Available Algorithm Names
PQCDetector-->>Server : Available PQC IDs + Error Message
Server->>Server : Filter Allowed Algorithms
alt PQC Algorithms Available
Server->>Fido2Server : Configure PQC Algorithms
Fido2Server-->>Server : Registration Options
else No PQC Algorithms Available
Server->>Server : Apply Classical Fallback
Server->>Fido2Server : Configure Classical Algorithms
Fido2Server-->>Server : Registration Options
end
Server-->>Client : Registration Challenge with Algorithm List

Loading

Diagram sources

• server/server/routes/advanced.py
• server/pqc.py

Algorithm Selection Logic

The algorithm selection process follows a priority-based approach:

1. Client Preference: Client-provided algorithm preferences are honored when possible
2. Server Configuration: Server-side algorithm preferences override client choices
3. Availability Check: Only algorithms supported by the liboqs backend are considered
4. Fallback Resolution: Automatic fallback to classical algorithms when PQC is unavailable
5. Security Priority: Higher-security PQC variants are preferred when available

publicKeyCredentialParameters Integration

The system integrates seamlessly with WebAuthn's publicKeyCredentialParameters structure:

// Example algorithm parameter configuration
{
    "pubKeyCredParams": [
        {"type": "public-key", "alg": -50},  // ML-DSA-87 (PQC)
        {"type": "public-key", "alg": -49},  // ML-DSA-65 (PQC)
        {"type": "public-key", "alg": -48},  // ML-DSA-44 (PQC)
        {"type": "public-key", "alg": -8},   // EdDSA (Classical)
        {"type": "public-key", "alg": -7}    // ES256 (ECDSA)
    ]
}

Section sources

• server/server/routes/advanced.py
• server/server/routes/simple.py

Configuration Options

Environment-Based Configuration

The system supports several configuration approaches to control PQC behavior:

PQC Availability Control

Configuration Option	Purpose	Default Behavior
python-fido2-webauthn-test[pqc]	Install PQC dependencies	Disabled
liboqs presence	Runtime detection	Auto-detected
Algorithm availability	Per-algorithm support	Dynamic

Testing and Development Configuration

For development and testing scenarios, administrators can control PQC behavior:

• Force PQC Mode: Enforce PQC-only operation for testing
• Disable PQC: Temporarily disable PQC for compatibility testing
• Selective Enable: Enable specific PQC algorithms while disabling others

Dependency Management

The system manages PQC dependencies through Poetry's extra system:

[tool.poetry.extras]
pqc = ["oqs", "pqcrypto"]

This allows administrators to install only the dependencies they need, reducing the attack surface and simplifying deployment.

Section sources

• pyproject.toml
• requirements.txt

Fallback Mechanisms

Hierarchical Fallback Strategy

The system implements a sophisticated fallback mechanism that ensures authentication continuity:

flowchart TD
Start([Algorithm Negotiation]) --> CheckPQC{PQC Available?}
CheckPQC --> |Yes| CheckSpecific{Specific Algorithm Available?}
CheckSpecific --> |Yes| UsePQC[Use PQC Algorithm]
CheckSpecific --> |No| LogWarning[Log Warning Message]
LogWarning --> CheckFallback{Fallback Available?}
CheckFallback --> |Yes| UseFallback[Use Classical Fallback]
CheckFallback --> |No| RejectRegistration[Reject Registration]
CheckPQC --> |No| LogError[Log Error Message]
LogError --> UseFallback
UsePQC --> Success([Authentication Success])
UseFallback --> Success
RejectRegistration --> Failure([Authentication Failure])

Loading

Diagram sources

• server/server/routes/advanced.py

Classical Algorithm Fallback

When PQC algorithms are unavailable, the system automatically falls back to classical algorithms:

• Primary Fallback: ES256 (ECDSA) with P-256 curve
• Secondary Fallback: EdDSA (Ed25519)
• Tertiary Fallback: RS256 (RSA) with 2048-bit keys

Warning and Error Reporting

The fallback mechanism provides comprehensive logging:

• Warning Messages: Informative messages about algorithm unavailability
• Error Details: Specific information about missing dependencies
• Resolution Guidance: Clear instructions for administrators

Section sources

• server/server/routes/advanced.py
• server/pqc.py

Testing and Validation

ML-DSA Testing Framework

The system includes comprehensive testing for ML-DSA algorithms:

classDiagram
class MLDSATestSuite {
+ML_DSA_VARIANTS : List[Tuple]
+test_mldsa_registration_and_authentication()
+setup_test_environment()
+validate_attestation_flow()
+test_authentication_flow()
}
class TestVariant {
+label : str
+cose_cls : Type[CoseKey]
+alg_id : int
+key_length : int
}
class TestEnvironment {
+mock_server : Fido2Server
+mock_attestation : AttestationObject
+test_user : Dict
+client_data : CollectedClientData
}
MLDSATestSuite --> TestVariant
MLDSATestSuite --> TestEnvironment

Loading

Diagram sources

• tests/test_mldsa_registration_authentication.py

Test Coverage Areas

The testing framework covers:

• Registration Flows: End-to-end registration with ML-DSA algorithms
• Authentication Flows: Authentication using ML-DSA credentials
• Error Scenarios: Edge cases and failure modes
• Algorithm Variants: Testing all three ML-DSA parameter sets

Validation Procedures

Each test validates:

1. Algorithm Identification: Proper identification of ML-DSA algorithms
2. Key Generation: Correct key pair generation and validation
3. Signature Verification: Successful signature verification
4. Attestation Chain: Proper attestation chain validation
5. Fallback Behavior: Graceful degradation when PQC is unavailable

Section sources

• tests/test_mldsa_registration_authentication.py

Troubleshooting Guide

Common Issues and Solutions

PQC Not Available

Symptoms: ML-DSA algorithms not appearing in registration options Causes: Missing liboqs installation or unsupported algorithms Solutions:

1. Install PQC dependencies: pip install python-fido2-webauthn-test[pqc]
2. Verify liboqs installation: Check for oqs module availability
3. Rebuild liboqs with ML-DSA support

Algorithm Unavailability

Symptoms: Warning messages about missing PQC algorithms Causes: Partial liboqs installation or outdated bindings Solutions:

1. Update liboqs to latest version
2. Reinstall python-fido2-webauthn-test package
3. Verify algorithm availability in liboqs

Performance Issues

Symptoms: Slow registration/authentication with PQC algorithms Causes: Hardware limitations or inefficient implementations Solutions:

1. Use smaller ML-DSA variant (-48) for better performance
2. Ensure adequate CPU resources
3. Monitor system performance metrics

Diagnostic Tools

The system provides several diagnostic capabilities:

• Algorithm Detection Logs: Detailed logs of algorithm availability
• Error Messages: Specific error messages guiding resolution
• Fallback Warnings: Information about fallback algorithm usage
• Performance Metrics: Timing information for algorithm operations

Section sources

• server/pqc.py
• server/server/routes/advanced.py

Best Practices

Deployment Recommendations

1. Dependency Management: Always install PQC dependencies explicitly
2. Monitoring: Monitor algorithm availability and fallback usage
3. Testing: Regular testing of PQC functionality in staging environments
4. Documentation: Maintain clear documentation of PQC configuration

Security Considerations

1. Algorithm Selection: Prefer higher-security PQC variants when available
2. Fallback Security: Ensure fallback algorithms meet minimum security requirements
3. Monitoring: Monitor for unusual fallback patterns that may indicate issues
4. Updates: Keep liboqs and PQC dependencies updated

Performance Optimization

1. Algorithm Choice: Select appropriate ML-DSA variant based on performance requirements
2. Hardware: Ensure adequate computational resources for PQC operations
3. Caching: Implement caching for algorithm detection results
4. Monitoring: Monitor performance impact of PQC operations

Maintenance Guidelines

1. Regular Updates: Keep PQC dependencies updated
2. Testing: Regular testing of fallback mechanisms
3. Documentation: Maintain up-to-date documentation
4. Monitoring: Implement comprehensive monitoring and alerting