MDS3 Implementation - FeitianTech/postquantum-webauthn-platform GitHub Wiki

MDS3 Implementation

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Security Considerations
  7. Practical Examples
  8. Troubleshooting Guide
  9. Conclusion

Introduction

The MDS3 (Metadata Service v3) implementation in this WebAuthn platform provides comprehensive support for parsing, validating, and utilizing FIDO Alliance Metadata Service JWTs to ensure authenticator trustworthiness. This implementation serves as a critical security layer that validates attestation statements by cross-referencing authenticator metadata against the official FIDO MDS3 service.

The MDS3 system enables platforms to verify authenticator authenticity through multiple lookup mechanisms including AAGUID-based identification and certificate chain validation. It implements robust security policies including revocation checking and protection against metadata tampering, making it essential for enterprise-grade WebAuthn deployments.

Project Structure

The MDS3 implementation is organized across several key modules within the WebAuthn platform:

graph TB
subgraph "Core MDS3 Module"
MDS3[fido2/mds3.py]
TestMDS3[tests/test_mds3.py]
end
subgraph "Server Integration"
Attestation[server/attestation.py]
Metadata[server/metadata.py]
Config[server/config.py]
end
subgraph "Support Scripts"
UpdateScript[scripts/update_mds_snapshot.py]
end
MDS3 --> Attestation
MDS3 --> Metadata
Config --> Metadata
TestMDS3 --> MDS3

Diagram sources

Section sources

Core Components

The MDS3 implementation consists of several interconnected components that work together to provide comprehensive metadata validation:

Data Classes

The implementation defines several key data classes that model the MDS3 structure:

  • MetadataStatement: Represents the core metadata about an authenticator
  • MetadataBlobPayloadEntry: Contains individual metadata entries with status reports
  • StatusReport: Tracks the current status and certification information
  • BiometricStatusReport: Handles biometric authentication status
  • AuthenticatorStatus: Enumerates possible authenticator statuses

Verification Components

  • MdsAttestationVerifier: Main class for attestation evaluation and metadata lookup
  • MdsAttestationEvaluation: Provides detailed trust information for attestation results

Utility Functions

  • filter_revoked: Removes revoked authenticators from consideration
  • filter_attestation_key_compromised: Prevents use of compromised attestation keys
  • parse_blob: Verifies JWT signatures and decodes payload data

Section sources

Architecture Overview

The MDS3 architecture follows a layered approach that separates concerns between parsing, validation, and integration:

sequenceDiagram
participant Client as "WebAuthn Client"
participant Server as "WebAuthn Server"
participant MDS3 as "MDS3 Parser"
participant Verifier as "MDS Verifier"
participant Metadata as "Metadata Store"
Client->>Server : Registration Request
Server->>MDS3 : Parse MDS Blob
MDS3->>MDS3 : Verify JWT Signature
MDS3->>Metadata : Load Metadata Entries
Server->>Verifier : Initialize Verifier
Verifier->>Metadata : Lookup by AAGUID/Cert Chain
Metadata-->>Verifier : Return Metadata Entry
Verifier->>Verifier : Apply Filters
Verifier-->>Server : Validation Results
Server-->>Client : Registration Response

Diagram sources

Section sources

Detailed Component Analysis

MdsAttestationVerifier Class

The MdsAttestationVerifier class serves as the primary interface for MDS3 functionality, extending the base AttestationVerifier class:

classDiagram
class AttestationVerifier {
+verify_attestation()
+collect_trust_path_details()
}
class MdsAttestationVerifier {
-_attestation_filter : LookupFilter
-_aaguid_table : Dict
-_ski_table : Dict
+find_entry_by_aaguid()
+find_entry_by_chain()
+ca_lookup()
+find_entry()
+evaluate_attestation()
}
class MdsAttestationEvaluation {
+trust_path : TrustPathEvaluation
+metadata_entry : MetadataBlobPayloadEntry
+metadata_lookup_source : str
}
AttestationVerifier <|-- MdsAttestationVerifier
MdsAttestationVerifier --> MdsAttestationEvaluation

Diagram sources

The verifier maintains two lookup tables:

  • AAGUID Table: Maps authenticator identifiers to metadata entries
  • Subject Key Identifier Table: Maps certificate SKIs to metadata entries

Section sources

Metadata Statement Structure

The MetadataStatement class encapsulates comprehensive authenticator metadata:

classDiagram
class MetadataStatement {
+description : str
+authenticator_version : int
+schema : int
+upv : Sequence[Version]
+attestation_types : Sequence[str]
+user_verification_details : Sequence[Sequence[VerificationMethodDescriptor]]
+key_protection : Sequence[str]
+matcher_protection : Sequence[str]
+attachment_hint : Sequence[str]
+tc_display : Sequence[str]
+attestation_root_certificates : Sequence[bytes]
+aaid : Optional[str]
+aaguid : Optional[Aaguid]
+attestation_certificate_key_identifiers : Optional[Sequence[bytes]]
+alternative_descriptions : Optional[Mapping[str, str]]
+protocol_family : Optional[str]
+authentication_algorithms : Optional[Sequence[str]]
+public_key_alg_and_encodings : Optional[Sequence[str]]
+is_key_restricted : Optional[bool]
+is_fresh_user_verification_required : Optional[bool]
+crypto_strength : Optional[int]
+operating_env : Optional[str]
+tc_display_content_type : Optional[str]
+tc_display_png_characteristics : Optional[Sequence[DisplayPngCharacteristicsDescriptor]]
+ecdaa_trust_anchors : Optional[Sequence[EcdaaTrustAnchor]]
+icon : Optional[str]
+supported_extensions : Optional[Sequence[ExtensionDescriptor]]
+authenticator_get_info : Optional[Mapping[str, Any]]
}

Diagram sources

Section sources

Security Filter Functions

The implementation provides two critical security filters:

Revocation Filtering

The filter_revoked function prevents use of compromised authenticators:

flowchart TD
Start([Metadata Entry]) --> CheckReports["Check Status Reports"]
CheckReports --> HasRevoked{"Has REVOKED Status?"}
HasRevoked --> |Yes| Reject["Reject Entry"]
HasRevoked --> |No| CheckCompromised["Check ATTESTATION_KEY_COMPROMISE"]
CheckCompromised --> Pass["Pass Entry"]
Reject --> End([End])
Pass --> End

Diagram sources

Attestation Key Compromise Filtering

The filter_attestation_key_compromised function validates certificate chains against known compromises:

flowchart TD
Start([Certificate Chain]) --> IterateChain["Iterate Through Certificates"]
IterateChain --> CheckStatus["Check Status Reports"]
CheckStatus --> IsCompromised{"Is Compromised?"}
IsCompromised --> |Yes| MatchCert{"Certificate Matches?"}
MatchCert --> |Yes| Fail["Fail Verification"]
MatchCert --> |No| NextCert["Next Certificate"]
IsCompromised --> |No| NextCert
NextCert --> MoreCerts{"More Certificates?"}
MoreCerts --> |Yes| IterateChain
MoreCerts --> |No| Pass["Pass Verification"]
Fail --> End([End])
Pass --> End

Diagram sources

Section sources

JWT Parsing and Signature Verification

The parse_blob function handles JWT parsing and cryptographic verification:

sequenceDiagram
participant Caller as "Caller"
participant Parser as "parse_blob"
participant Crypto as "Cryptography"
participant Validator as "JWT Validator"
Caller->>Parser : parse_blob(blob, trust_root)
Parser->>Parser : Split JWT (header.payload.signature)
Parser->>Parser : Decode header and payload
Parser->>Crypto : Verify X.509 Chain
Crypto-->>Parser : Chain Validation Result
Parser->>Crypto : Extract Public Key
Crypto-->>Parser : Public Key Object
Parser->>Validator : Verify COSE Signature
Validator-->>Parser : Signature Validation
Parser->>Parser : Convert to MetadataBlobPayload
Parser-->>Caller : Structured Metadata

Diagram sources

Section sources

Security Considerations

Trust Anchor Management

The implementation relies on a carefully curated trust root for JWT signature verification. The FIDO Alliance provides a dedicated trust root certificate that must be used for production environments:

  • Primary Trust Root: Embedded in the configuration as a base64-encoded PEM certificate
  • Additional Trust Anchors: TLS trust anchors for enhanced security
  • Validation Requirement: Signature verification is mandatory for production use

Revocation Checking

Multiple layers of revocation checking ensure authenticator safety:

  1. Automatic Revocation Filtering: Built-in filter removes revoked entries
  2. Certificate Compromise Detection: Validates against known compromised keys
  3. Status Report Validation: Checks current authenticator status

Protection Against Metadata Tampering

Several mechanisms protect against metadata manipulation:

  • Cryptographic Signature Verification: JWT signatures are validated using ECDSA
  • Certificate Chain Validation: X.509 certificate chains are verified
  • Immutable Lookup Tables: Metadata entries are cached in immutable tables
  • Context Variables: Thread-safe tracking of lookup sources and results

Best Practices for Deployment

  1. Always Use Trust Roots: Never disable signature verification in production
  2. Regular Updates: Implement automated metadata updates
  3. Monitoring: Track verification failures and suspicious activities
  4. Fallback Mechanisms: Implement graceful degradation when metadata is unavailable

Section sources

Practical Examples

Basic Metadata Verification

Here's how the platform validates an authenticator's attestation statement:

sequenceDiagram
participant Client as "Client Device"
participant Platform as "WebAuthn Platform"
participant MDS3 as "MDS3 Verifier"
participant Metadata as "FIDO MDS3 Service"
Client->>Platform : Register Authenticator
Platform->>Metadata : Download MDS3 Blob
Metadata-->>Platform : Encrypted Metadata
Platform->>MDS3 : Parse and Verify Blob
MDS3->>MDS3 : Verify JWT Signature
MDS3->>MDS3 : Build Lookup Tables
Platform->>MDS3 : Find Entry by AAGUID
MDS3->>MDS3 : Apply Security Filters
MDS3-->>Platform : Validated Metadata Entry
Platform->>Platform : Complete Registration

Diagram sources

Authenticator Status Validation

The platform tracks authenticator status through multiple channels:

Status Type Description Impact
FIDO_CERTIFIED Authenticator passes FIDO certification Full trust
USER_VERIFICATION_BYPASS Bypasses user verification Reduced trust
ATTESTATION_KEY_COMPROMISE Compromised attestation key Immediate rejection
REVOKED Explicitly revoked by manufacturer Immediate rejection
UPDATE_AVAILABLE Software update recommended Warning level

Section sources

Error Handling and Recovery

The implementation provides comprehensive error handling:

flowchart TD
Start([Verification Request]) --> LoadMetadata["Load Metadata"]
LoadMetadata --> MetadataAvailable{"Metadata Available?"}
MetadataAvailable --> |No| LogWarning["Log Warning"]
MetadataAvailable --> |Yes| ValidateAtt["Validate Attestation"]
ValidateAtt --> ValidSignature{"Valid Signature?"}
ValidSignature --> |No| Reject["Reject"]
ValidSignature --> |Yes| FindEntry["Find Metadata Entry"]
FindEntry --> EntryFound{"Entry Found?"}
EntryFound --> |No| LogError["Log Error"]
EntryFound --> |Yes| ApplyFilters["Apply Security Filters"]
ApplyFilters --> FilterPass{"Filters Pass?"}
FilterPass --> |No| Reject
FilterPass --> |Yes| Success["Success"]
LogWarning --> GracefulDegradation["Graceful Degradation"]
LogError --> GracefulDegradation
Reject --> End([End])
Success --> End
GracefulDegradation --> End

Diagram sources

Section sources

Troubleshooting Guide

Common Issues and Solutions

Metadata Signature Verification Failures

Symptoms: JWT signature verification errors Causes:

  • Using incorrect trust root certificate
  • Network issues preventing metadata download
  • Corrupted metadata blob

Solutions:

  1. Verify trust root certificate matches FIDO Alliance standards
  2. Check network connectivity to MDS3 endpoint
  3. Validate metadata blob integrity

Authenticator Not Found in Metadata

Symptoms: "Metadata entry missing" errors Causes:

  • Authenticator not yet in FIDO MDS3
  • Incorrect AAGUID detection
  • Metadata synchronization delays

Solutions:

  1. Verify authenticator AAGUID is correctly extracted
  2. Check for recent metadata updates
  3. Implement fallback mechanisms for unknown authenticators

Certificate Chain Validation Errors

Symptoms: "Certificate chain error" messages Causes:

  • Expired certificates in chain
  • Invalid certificate authority
  • Malformed certificate data

Solutions:

  1. Validate certificate validity dates
  2. Verify certificate authority hierarchy
  3. Check certificate format compliance

Debugging Tools and Techniques

The implementation provides several debugging capabilities:

  • Context Variables: Track lookup sources and results
  • Logging Integration: Comprehensive logging for troubleshooting
  • Exception Handling: Detailed error reporting for development

Section sources

Conclusion

The MDS3 implementation provides a robust foundation for WebAuthn attestation verification, offering comprehensive security features and flexible integration options. Its modular design allows for easy customization while maintaining strong security guarantees.

Key strengths of the implementation include:

  • Comprehensive Security: Multiple layers of validation and filtering
  • Flexible Integration: Support for various lookup mechanisms
  • Production Ready: Robust error handling and monitoring capabilities
  • Standards Compliant: Full adherence to FIDO Alliance specifications

The platform's approach to metadata management ensures that authenticator trustworthiness is maintained through continuous validation against authoritative sources, making it suitable for enterprise-grade applications requiring high security standards.

Future enhancements could include expanded metadata sources, improved caching mechanisms, and enhanced monitoring capabilities to further strengthen the platform's security posture.