1. Introduction
2. System Architecture Overview
3. Core Components Analysis
4. Common Failure Scenarios
5. Diagnostic Tools and Techniques
6. Troubleshooting Workflows
7. Validation Testing Suite
8. Debug Logging Configuration
9. Performance Considerations
10. Resolution Strategies

The post-quantum cryptography (PQC) implementation in this WebAuthn platform focuses on ML-DSA (Module-Lattice Digital Signature Algorithm) integration through the liboqs library. This document provides comprehensive guidance for diagnosing, understanding, and resolving PQC-related failures that commonly occur in production environments.

ML-DSA represents one of the leading candidates for post-quantum cryptography standardization, offering resistance against quantum computing attacks while maintaining reasonable performance characteristics. However, its integration presents unique challenges that require specialized troubleshooting approaches.

The PQC implementation follows a layered architecture that separates concerns between cryptographic operations, algorithm negotiation, and platform integration:

graph TB
subgraph "Application Layer"
WebApp[Web Application]
Server[Fido2Server]
end
subgraph "Crypto Abstraction Layer"
COSE[COSE Key Management]
PQC[PQC Detection & Selection]
Features[Feature Flags]
end
subgraph "LibOQS Integration Layer"
OQS[liboqs Bindings]
SigMech[Signature Mechanisms]
AlgNeg[Algorithm Negotiation]
end
subgraph "Platform Layer"
CertMgr[Certificate Management]
Attestation[Attestation Verification]
Logging[Debug Logging]
end
WebApp --> Server
Server --> COSE
COSE --> PQC
PQC --> Features
COSE --> OQS
OQS --> SigMech
PQC --> AlgNeg
Server --> CertMgr
CertMgr --> Attestation
Attestation --> Logging

Diagram sources

• server/server/pqc.py
• fido2/cose.py
• server/server/attestation.py

Section sources

• server/server/pqc.py
• fido2/cose.py

The PQC detection system operates through a sophisticated mechanism that validates liboqs availability and enumerates supported algorithms:

flowchart TD
Start([Algorithm Detection Start]) --> LoadOQS["Load liboqs Module"]
LoadOQS --> OQSExists{"liboqs Available?"}
OQSExists --> |No| ImportError["Raise ImportError"]
OQSExists --> |Yes| GetMechs["Query Enabled Mechanisms"]
GetMechs --> MechFunc{"get_enabled_sig_mechanisms<br/>Available?"}
MechFunc --> |Yes| EnumMechs["Enumerate Mechanisms"]
MechFunc --> |No| FallbackMechs["Use Signature.algorithms"]
EnumMechs --> FilterPQC["Filter ML-DSA Algorithms"]
FallbackMechs --> FilterPQC
FilterPQC --> ValidateSupport["Validate Algorithm Support"]
ValidateSupport --> Success["Return Available IDs"]
ImportError --> ErrorMsg["Return Error Message"]
Success --> End([Detection Complete])
ErrorMsg --> End

Diagram sources

• server/server/pqc.py
• server/server/pqc.py

The core detection logic handles multiple scenarios including missing dependencies, version compatibility issues, and partial algorithm support configurations.

Section sources

• server/server/pqc.py

The COSE (CBOR Object Signing and Encryption) implementation provides robust handling of ML-DSA keys with comprehensive error checking:

classDiagram
class CoseKey {
+verify(message, signature) void
+set_assertion_debug_data(auth_data, client_data) void
+_log_signature_debug(alg_label, msg_bytes, sig_bytes, pub_key_bytes) void
+from_cryptography_key(public_key) CoseKey
}
class MLDSA44 {
+ALGORITHM : -48
+_HASH_ALG : SHA256
+verify(message, signature) void
+from_cryptography_key(public_key) MLDSA44
}
class MLDSA65 {
+ALGORITHM : -49
+_HASH_ALG : SHA256
+verify(message, signature) void
+from_cryptography_key(public_key) MLDSA65
}
class MLDSA87 {
+ALGORITHM : -50
+_HASH_ALG : SHA256
+verify(message, signature) void
+from_cryptography_key(public_key) MLDSA87
}
CoseKey <|-- MLDSA44
CoseKey <|-- MLDSA65
CoseKey <|-- MLDSA87

Diagram sources

• fido2/cose.py

Each ML-DSA variant implements specific validation logic including parameter set verification, public key format checking, and signature structure validation.

Section sources

• fido2/cose.py

The attestation system provides comprehensive ML-DSA certificate validation with fallback mechanisms:

sequenceDiagram
participant Client as Client Device
participant Server as WebAuthn Server
participant OQS as liboqs Library
participant Cert as Certificate Chain
Client->>Server : Registration Request
Server->>Server : Generate Challenge
Server->>Client : Challenge Response
Client->>Server : Attestation Object
Server->>Cert : Parse Certificate
Cert->>Server : Extract Public Key Info
Server->>Server : Verify OID Mapping
Server->>OQS : Initialize Signature Context
OQS->>Server : Algorithm Ready
Server->>OQS : Verify Certificate Signature
OQS->>Server : Verification Result
Server->>Server : Validate Trust Path
Server->>Client : Registration Response

Diagram sources

• fido2/attestation/base.py
• server/server/attestation.py

Section sources

• fido2/attestation/base.py
• server/server/attestation.py

Algorithm negotiation failures typically manifest as:

1. Missing liboqs Installation: When the required Python bindings for liboqs are not installed
2. Partial Algorithm Support: When only some ML-DSA variants are available
3. Version Compatibility Issues: When the installed liboqs version doesn't support required features

Symptom Patterns:

• RuntimeError: ML-DSA verification requires the 'oqs' package
• ImportError: oqs bindings are unavailable
• Algorithm selection falling back to classical algorithms unexpectedly

Signature verification failures often occur due to:

1. Incorrect Parameter Sets: Using mismatched ML-DSA parameter configurations
2. Malformed Public Keys: Improperly encoded or corrupted public key data
3. Invalid Signature Structures: Non-compliant signature formats

Symptom Patterns:

• ValueError: Invalid ML-DSA signature
• ValueError: Missing ML-DSA public key
• ValueError: Unsupported ML-DSA parameter

Integration issues commonly involve:

1. Library Loading Failures: Dynamic library loading problems
2. Function Symbol Resolution: Missing or incompatible function exports
3. Memory Management Issues: Resource cleanup and allocation problems

Symptom Patterns:

• ImportError: cannot import name 'Signature' from 'oqs'
• OSError: liboqs library not found
• AttributeError: 'NoneType' has no attribute 'verify'

Section sources

• fido2/cose.py
• fido2/cose.py

The diagnostic system provides comprehensive algorithm availability reporting:

flowchart TD
DetectAlgs["detect_available_pqc_algorithms()"] --> TryLoad["Try Load liboqs"]
TryLoad --> LoadSuccess{"Load Successful?"}
LoadSuccess --> |No| NoOQS["Return Empty Set + Error"]
LoadSuccess --> |Yes| EnumMechs["Enumerate Mechanisms"]
EnumMechs --> CheckSupport["Check Against Expected"]
CheckSupport --> AllPresent{"All Algorithms Present?"}
AllPresent --> |Yes| Success["Return Full Set + None"]
AllPresent --> |No| Missing["Identify Missing Algorithms"]
Missing --> BuildError["Build Error Message"]
BuildError --> PartialFail["Return Partial Set + Error"]
NoOQS --> End([Diagnostic Complete])
Success --> End
PartialFail --> End

Diagram sources

• server/server/pqc.py

COSE key validation employs multiple diagnostic layers:

1. Format Validation: Ensuring proper CBOR structure
2. Parameter Verification: Checking algorithm identifiers and parameters
3. Public Key Extraction: Validating key format and length
4. Signature Structure Analysis: Verifying signature encoding compliance

Section sources

• fido2/cose.py
• fido2/cose.py

The feature flag system provides controlled access to PQC functionality:

classDiagram
class _Feature {
-_enabled : Optional[bool]
-_name : str
-_desc : str
+enabled : bool
+require(state : bool) void
+warn() void
}
class FeatureNotEnabledError {
+message : str
}
_Feature --> FeatureNotEnabledError : raises

Diagram sources

• fido2/features.py

Section sources

• fido2/features.py

When encountering PQC-related issues, follow this systematic approach:

1. Verify Dependencies: Confirm liboqs installation and accessibility
2. Check Algorithm Availability: Validate supported ML-DSA variants
3. Test Basic Functionality: Perform simple signature operations
4. Analyze Error Context: Examine error messages and stack traces
5. Review Configuration: Verify feature flag settings

flowchart TD
Start([Start liboqs Troubleshooting]) --> CheckImport["Check 'import oqs'"]
CheckImport --> ImportError{"Import Error?"}
ImportError --> |Yes| CheckInstallation["Check Installation Status"]
ImportError --> |No| CheckFunctions["Check Function Availability"]
CheckInstallation --> PipInstall["pip install python-fido2-webauthn-test[pqc]"]
PipInstall --> CheckFunctions
CheckFunctions --> FuncAvailable{"Functions Available?"}
FuncAvailable --> |No| CheckVersion["Check liboqs Version"]
FuncAvailable --> |Yes| CheckSymbols["Check Symbol Resolution"]
CheckVersion --> RebuildLiboqs["Rebuild with ML-DSA Support"]
RebuildLiboqs --> CheckSymbols
CheckSymbols --> SymbolOK{"Symbols Resolved?"}
SymbolOK --> |No| CheckLibraryPath["Check Library Path"]
SymbolOK --> |Yes| Success["liboqs Working"]
CheckLibraryPath --> FixPath["Fix LD_LIBRARY_PATH"]
FixPath --> Success
Success --> End([Troubleshooting Complete])

Diagram sources

• server/server/pqc.py

For CBOR-related issues, implement these validation steps:

1. Structure Validation: Verify CBOR object integrity
2. Parameter Consistency: Ensure algorithm parameter alignment
3. Key Format Compliance: Validate public key encoding standards
4. Signature Format Verification: Check signature structure correctness

Section sources

• fido2/cose.py
• fido2/cose.py

The system implements graceful degradation when PQC features are unavailable:

sequenceDiagram
participant App as Application
participant PQC as PQC Module
participant Fallback as Fallback Handler
participant Logger as Logger
App->>PQC : Request PQC Operation
PQC->>PQC : Check liboqs Availability
PQC->>Logger : Log Algorithm Selection
alt liboqs Unavailable
PQC->>Fallback : Activate Fallback
Fallback->>Logger : Log Fallback Activation
Fallback->>App : Return Classical Algorithm
else liboqs Available
PQC->>PQC : Execute PQC Operation
PQC->>App : Return PQC Result
end

Diagram sources

• server/server/pqc.py

Section sources

• server/server/pqc.py

The test suite provides comprehensive validation of ML-DSA functionality:

The test framework validates complete ML-DSA workflows:

sequenceDiagram
participant Test as Test Suite
participant Server as Fido2Server
participant Mock as Mock Objects
participant Validator as Signature Validator
Test->>Server : Register Begin
Server->>Mock : Generate Challenge
Test->>Mock : Create Credential
Test->>Server : Register Complete
Server->>Validator : Validate Signature
Validator->>Test : Verification Result
Test->>Server : Authenticate Begin
Server->>Mock : Generate Assertion
Test->>Mock : Stub Verify Method
Test->>Server : Authenticate Complete
Server->>Test : Authentication Result

Diagram sources

• tests/test_mldsa_registration_authentication.py

The test suite covers all supported ML-DSA variants:

Section sources

• tests/test_mldsa_registration_authentication.py

Configure comprehensive logging for PQC operations:

# Enable debug logging for PQC operations
import logging
from server.server import app

# Configure logger level
app.logger.setLevel(logging.DEBUG)

# Enable specific PQC debug categories
logging.getLogger('fido2.cose').setLevel(logging.DEBUG)
logging.getLogger('server.server.pqc').setLevel(logging.DEBUG)
logging.getLogger('server.server.attestation').setLevel(logging.DEBUG)

The system provides detailed algorithm selection logging:

flowchart LR
Stage[Registration/Auth Stage] --> CheckAlg{Algorithm Type?}
CheckAlg --> |PQC| PQCLoad["Log PQC Algorithm Usage"]
CheckAlg --> |Classical| ClassicLoad["Log Classical Algorithm Usage"]
PQCLoad --> LogEntry["INFO: Using post-quantum algorithm ML-DSA-65 (COSE -49) during registration"]
ClassicLoad --> LogEntry2["INFO: Using classical algorithm ES256 (COSE -7) during authentication"]

Diagram sources

• server/server/pqc.py

The COSE key implementation provides comprehensive debug output:

flowchart TD
VerifyCall[verify() Called] --> ExtractData["Extract Message, Signature, Public Key"]
ExtractData --> LogDebug["Log Debug Information"]
LogDebug --> PrintAuthData["Print Authenticator Data"]
PrintAuthData --> PrintClientData["Print Client Data JSON"]
PrintClientData --> PrintMessage["Print Message Bytes"]
PrintMessage --> PrintSignature["Print Signature Bytes"]
PrintSignature --> PrintPublicKey["Print Public Key Bytes"]
PrintPublicKey --> Complete[Debug Output Complete]

Diagram sources

• fido2/cose.py

Section sources

• server/server/pqc.py
• fido2/cose.py

ML-DSA algorithms exhibit different performance profiles:

PQC operations require careful memory management:

1. Key Storage: Large public/private key pairs
2. Signature Buffers: Variable-length signature structures
3. Certificate Chains: Hierarchical certificate validation
4. Temporary Buffers: Algorithm-specific intermediate data

1. Pre-allocation: Reserve memory for large operations
2. Batch Processing: Group multiple operations
3. Resource Pooling: Reuse expensive initialization
4. Lazy Loading: Defer expensive operations until needed

Ensure proper dependency installation:

# Install PQC-enabled dependencies
pip install python-fido2-webauthn-test[pqc]

# Verify liboqs installation
python -c "import oqs; print(oqs.get_enabled_sig_mechanisms())"

Verify system configuration:

1. Environment Variables: Check LD_LIBRARY_PATH for liboqs
2. Python Path: Ensure proper module discovery
3. Feature Flags: Confirm PQC features are enabled
4. Logging Configuration: Verify debug output settings

When failures occur, implement these recovery steps:

1. Graceful Degradation: Fall back to classical algorithms
2. Error Reporting: Collect comprehensive diagnostic information
3. State Cleanup: Proper resource deallocation
4. Retry Logic: Implement exponential backoff for transient failures

Establish monitoring for PQC operations:

1. Availability Metrics: Track algorithm detection success rates
2. Performance Indicators: Monitor operation timing
3. Error Rates: Track failure frequencies by category
4. Resource Usage: Monitor memory and CPU consumption

Section sources

• server/server/pqc.py
• fido2/cose.py