Fallback to Classical Cryptography - FeitianTech/postquantum-webauthn-platform GitHub Wiki

Fallback to Classical Cryptography

Table of Contents

  1. Introduction
  2. Conditional Logic in pqc.py
  3. COSE Key Structure Construction
  4. Feature Flag Control
  5. Practical Fallback Scenarios
  6. Security Implications and Best Practices

Introduction

The post-quantum cryptography (PQC) implementation in this WebAuthn platform includes robust fallback mechanisms to ensure continued operation when PQC algorithms are unavailable. The system gracefully degrades to classical cryptographic algorithms such as ECDSA and EdDSA when the liboqs library is not present, ML-DSA is unsupported, or explicitly disabled via feature flags. This document details the fallback mechanisms, conditional logic, and configuration options that enable interoperability across different authenticator capabilities while maintaining security.

Section sources

Conditional Logic in pqc.py

The pqc.py module contains the core logic for determining the active signature algorithm during WebAuthn operations. The system uses a hierarchical decision-making process to select appropriate cryptographic algorithms based on availability and configuration.

The detect_available_pqc_algorithms() function attempts to import the oqs module and query liboqs for enabled signature mechanisms. When the oqs bindings are unavailable, the function returns an empty set with an explanatory error message, triggering fallback to classical algorithms. The function handles various failure scenarios, including missing installations and incompatible builds.

The is_pqc_algorithm(alg_id) function serves as a simple lookup to determine if a given COSE algorithm identifier corresponds to an ML-DSA option. This boolean check is used throughout the system to route cryptographic operations appropriately.

When PQC algorithms are requested but not available, the system applies a two-tiered fallback strategy:

  1. First, it filters out unavailable PQC algorithms while preserving other supported algorithms
  2. If no algorithms remain after filtering, it applies a hard fallback to a predefined set of classical algorithms (ES256, EdDSA, RS256)

The log_algorithm_selection() function provides detailed logging of the negotiated algorithm for each registration or authentication flow, clearly indicating whether a post-quantum or classical algorithm is being used.

flowchart TD
Start([Algorithm Selection]) --> CheckPQC["Check if PQC requested?"]
CheckPQC --> |Yes| DetectAvailable["Detect available PQC algorithms"]
DetectAvailable --> CheckAvailability["Any PQC algorithms available?"]
CheckAvailability --> |Yes| UsePQC["Use available PQC algorithms"]
CheckAvailability --> |No| FilterAlgorithms["Filter out unavailable PQC"]
FilterAlgorithms --> CheckRemaining["Any algorithms remain?"]
CheckRemaining --> |Yes| UseRemaining["Use remaining algorithms"]
CheckRemaining --> |No| ApplyFallback["Apply hard fallback to ES256, EdDSA, RS256"]
UsePQC --> End([Operation Complete])
UseRemaining --> End
ApplyFallback --> End
CheckPQC --> |No| UseClassical["Use classical algorithms"]
UseClassical --> End

Diagram sources

Section sources

COSE Key Structure Construction

The construction of COSE key structures differs significantly based on whether PQC is enabled, primarily handled in the cose.py file. The system must accommodate different key formats and validation requirements for ML-DSA versus classical algorithms.

When PQC is enabled, the system processes ML-DSA public keys through specialized functions like _unwrap_mldsa_subject_public_key() which handle DER-wrapped key material. The function recursively searches DER structures for OCTET STRINGs of the expected length, accommodating various encoding formats that may be present in certificates.

For classical algorithms, the system uses standard COSE key structures with well-defined parameters:

  • ECDSA algorithms use curve identifiers and raw public key bytes
  • EdDSA algorithms specify curve types (Ed25519, Ed448) and include raw public keys
  • RSA algorithms include modulus and exponent values

The CoseKey base class and its derivatives (ES256, EdDSA, RS256, etc.) implement algorithm-specific verification methods that handle the distinct mathematical operations required for each signature scheme. The system maintains separate verification paths to ensure optimal performance and security for each algorithm type.

When processing attestation statements, the system examines the alg parameter to determine the appropriate verification method. For ML-DSA algorithms, it attempts to validate signatures using the oqs library, falling back to classical verification methods when PQC is unavailable.

Section sources

Feature Flag Control

The fido2.features.USE_PQC feature flag (represented by webauthn_json_mapping in the codebase) plays a crucial role in controlling PQC behavior during development and deployment. This flag allows developers and administrators to explicitly enable or disable post-quantum cryptography functionality.

The feature system is implemented through the _Feature class in features.py, which provides a consistent interface for managing experimental or transitional functionality. The enabled property can be set to True to enable PQC algorithms or False to disable them, with appropriate warnings issued when the default behavior is used.

During server initialization in config.py, the system attempts to enable the webauthn_json_mapping feature for compatibility across fido2 versions. This initialization sequence demonstrates how feature flags can be configured programmatically:

try:
    fido2.features.webauthn_json_mapping.enabled = True
except Exception:
    try:
        fido2.features.webauthn_json.enabled = True
    except Exception:
        pass

The feature flag system supports both explicit configuration and environment-based control, allowing for flexible deployment scenarios. Administrators can disable PQC entirely in production environments where it's not needed, or enable it selectively during testing and evaluation phases.

Section sources

Practical Fallback Scenarios

Several practical scenarios trigger the fallback to classical cryptography, each representing common deployment and operational conditions.

Missing prebuilt_liboqs: When the prebuilt liboqs library is not present in the deployment environment, the import of the oqs module fails, triggering immediate fallback to classical algorithms. This scenario commonly occurs in development environments or when deploying to platforms without precompiled PQC support.

Unsupported CPU architectures: The liboqs library may not support certain CPU architectures or instruction sets required for efficient PQC operations. In such cases, the library may be present but unable to provide the required algorithms, leading to selective fallback where only available algorithms are used.

Test environments: During development and testing, engineers may explicitly disable PQC to focus on classical cryptographic functionality or to ensure compatibility with test tools and frameworks that don't support PQC. The feature flag system allows for easy toggling between modes.

Hybrid authenticator capabilities: When a relying party requests multiple algorithms including both PQC and classical options, but the authenticator only supports classical algorithms, the system automatically negotiates the strongest available classical option. This ensures interoperability while maintaining security.

Resource-constrained environments: In environments with limited computational resources, administrators may choose to disable PQC algorithms due to their higher computational requirements, opting for the more efficient classical algorithms instead.

The system logs detailed information about fallback events, including the specific algorithms that were requested but unavailable, and the fallback strategy applied. This logging enables monitoring and troubleshooting of PQC availability issues in production environments.

Section sources

Security Implications and Best Practices

The hybrid operation of PQC and classical cryptography introduces specific security considerations that must be addressed through careful implementation and monitoring.

Security implications:

  • The fallback mechanism creates a potential attack surface where an adversary could attempt to force downgrade to classical algorithms
  • Mixed algorithm support requires careful validation to prevent cross-algorithm attacks
  • Key management complexity increases when supporting multiple cryptographic families
  • Performance characteristics differ significantly between PQC and classical algorithms, potentially creating timing side-channel opportunities

Best practices for monitoring fallback usage:

  1. Enable detailed logging: The system should log all fallback events, including the requested algorithms, available algorithms, and final selection. This provides visibility into PQC availability and usage patterns.

  2. Implement alerting: Configure alerts for unexpected fallback occurrences, particularly in production environments where PQC should be consistently available.

  3. Monitor algorithm distribution: Track the proportion of authentications using PQC versus classical algorithms to identify potential issues with PQC deployment or authenticator support.

  4. Regular availability testing: Periodically test PQC algorithm availability to ensure the liboqs library remains functional and properly configured.

  5. Gradual rollout: When deploying PQC support, use feature flags to enable it gradually, monitoring for issues before full rollout.

  6. Maintain classical algorithm security: Even with PQC available, ensure classical algorithms are properly configured with strong parameters and current best practices.

  7. Plan for algorithm agility: Design systems to accommodate future cryptographic transitions, recognizing that PQC standards may evolve over time.

The fallback mechanism is designed to be secure by default, ensuring that when PQC is unavailable, the system reverts to well-established classical algorithms with proven security properties, rather than failing completely or using weaker alternatives.

Section sources