Metadata Service (MDS) Integration - FeitianTech/postquantum-webauthn-platform GitHub Wiki

Metadata Service (MDS) Integration

Table of Contents

  1. Introduction
  2. MDS Architecture Overview
  3. Core Components
  4. Server-Side Metadata Management
  5. Frontend MDS Browser
  6. Security Considerations
  7. Implementation Details
  8. Testing and Validation
  9. Troubleshooting Guide
  10. Conclusion

Introduction

The Metadata Service (MDS) integration provides a comprehensive framework for validating authenticator attestation statements and verifying device trustworthiness in the WebAuthn platform. This system enables the platform to check authenticator compliance with FIDO standards, manage trust anchors, and maintain up-to-date metadata about authenticators from the FIDO Alliance.

The MDS integration consists of three primary components:

  • MDS3 Parser: Handles JWT parsing and signature verification using trust anchors
  • Server-Side Metadata Manager: Manages caching, refresh mechanisms, and session integration
  • Frontend MDS Browser: Provides visualization and interactive exploration of metadata content

MDS Architecture Overview

The MDS integration follows a layered architecture that separates concerns between parsing, validation, and presentation:

graph TB
subgraph "Client Layer"
A[Web Client] --> B[MDM Browser UI]
B --> C[Lazy Loader]
end
subgraph "Server Layer"
D[Metadata Manager] --> E[Caching Layer]
E --> F[Session Store]
D --> G[Trust Anchor Verifier]
end
subgraph "External Services"
H[FIDO MDS3 Endpoint] --> I[Metadata Snapshot]
J[GitHub Repository] --> K[Metadata Storage]
end
A --> D
D --> H
D --> J
C --> D
G --> L[Certificate Chain Validation]
G --> M[Signature Verification]

Diagram sources

Core Components

MDS3 JWT Parser and Verifier

The MDS3 module provides robust JWT parsing and signature verification capabilities:

classDiagram
class MdsAttestationVerifier {
+MetadataBlobPayload blob
+EntryFilter entry_filter
+LookupFilter attestation_filter
+find_entry_by_aaguid(aaguid) MetadataBlobPayloadEntry
+find_entry_by_chain(chain) MetadataBlobPayloadEntry
+ca_lookup(attestation, auth_data) bytes
+evaluate_attestation(obj, hash) MdsAttestationEvaluation
}
class MetadataBlobPayload {
+str legal_header
+int no
+date next_update
+Sequence~MetadataBlobPayloadEntry~ entries
}
class MetadataBlobPayloadEntry {
+Sequence~StatusReport~ status_reports
+date time_of_last_status_change
+str aaid
+Aaguid aaguid
+Sequence~bytes~ attestation_certificate_key_identifiers
+MetadataStatement metadata_statement
+Sequence~BiometricStatusReport~ biometric_status_reports
}
class MdsAttestationEvaluation {
+TrustPathEvaluation trust_path
+MetadataBlobPayloadEntry metadata_entry
+str metadata_lookup_source
}
MdsAttestationVerifier --> MetadataBlobPayload
MetadataBlobPayload --> MetadataBlobPayloadEntry
MdsAttestationVerifier --> MdsAttestationEvaluation

Diagram sources

The MDS3 parser handles:

  • JWT Parsing: Extracts header, payload, and signature from MDS3 blobs
  • Signature Verification: Validates JWT signatures using X.509 certificate chains
  • Trust Anchor Validation: Ensures authenticity through root certificate verification
  • Metadata Extraction: Converts raw JWT data into structured metadata objects

Section sources

Authenticator Status Management

The system tracks authenticator statuses through comprehensive status reporting:

stateDiagram-v2
[*] --> NotFidoCertified
NotFidoCertified --> FidoCertified
FidoCertified --> UserVerificationBypass
FidoCertified --> AttestationKeyCompromise
FidoCertified --> UserKeyRemoteCompromise
FidoCertified --> UserKeyPhysicalCompromise
FidoCertified --> UpdateAvailable
FidoCertified --> Revoked
FidoCertified --> SelfAssertionSubmitted
FidoCertified --> FidoCertifiedL1
FidoCertified --> FidoCertifiedL2
FidoCertified --> FidoCertifiedL3
UserVerificationBypass --> Revoked
AttestationKeyCompromise --> Revoked
UserKeyRemoteCompromise --> Revoked
UserKeyPhysicalCompromise --> Revoked
UpdateAvailable --> FidoCertified
Revoked --> [*]

Diagram sources

Section sources

Server-Side Metadata Management

Metadata Caching and Refresh Mechanisms

The server-side metadata manager implements sophisticated caching and refresh strategies:

sequenceDiagram
participant Client as Client Request
participant Manager as Metadata Manager
participant Cache as Local Cache
participant Remote as FIDO MDS3
participant Store as Session Store
Client->>Manager : Request Metadata
Manager->>Cache : Check Cache Validity
alt Cache Miss or Expired
Manager->>Remote : Fetch Latest Snapshot
Remote-->>Manager : Return MDS3 Blob
Manager->>Manager : Parse & Verify
Manager->>Cache : Update Cache
end
Manager->>Store : Merge Session Items
Manager-->>Client : Return Combined Metadata

Diagram sources

Session-Based Metadata Management

The system supports dynamic metadata injection through session-based storage:

Feature Description Implementation
Session Isolation Separate metadata per user session Cookie-based session identification
Dynamic Upload Allow users to upload custom metadata JSON-based metadata format
Automatic Cleanup Remove inactive sessions 14-day inactivity threshold
Persistence Store metadata across requests Local filesystem with GCS support
Validation Ensure metadata integrity Schema validation and type checking

Section sources

Trust Anchor Management

The system maintains multiple trust anchors for comprehensive validation:

flowchart TD
A[Incoming Certificate] --> B{Validate Against Trust Anchors}
B --> C[FIDO Root Certificate]
B --> D[Additional TLS Trust Anchors]
B --> E[Session Custom Anchors]
C --> F{Signature Valid?}
D --> F
E --> F
F --> |Yes| G[Accept Certificate]
F --> |No| H[Reject Certificate]
G --> I[Update Trust Path]
H --> J[Log Security Event]

Diagram sources

Section sources

Frontend MDS Browser

Interactive Metadata Visualization

The frontend MDS browser provides comprehensive visualization capabilities:

classDiagram
class MdsLazyLoader {
+Object[] allEntries
+Set~number~ fullyParsedIndices
+Map~string,Object~ fullyParsedKeys
+Boolean isBackgroundLoading
+initialize(metadata) void
+getAllRawEntries() Array
+getRawEntryByIndex(index) Object
+getRawEntryByKey(key) Object
+findEntriesWithCertificate(cert) Array
+startBackgroundLoading() Promise
+getStats() Object
}
class MdsBrowser {
+Object mdsState
+Array mdsData
+Array filteredData
+Boolean isLoading
+loadMetadata() Promise
+applyMetadataEntries() Promise
+updateFilters() void
+showEntryDetails(entry) void
}
MdsBrowser --> MdsLazyLoader
MdsBrowser --> CertificateCache
MdsBrowser --> FilterSystem

Diagram sources

Performance Optimization Features

The frontend implements several performance optimization strategies:

Optimization Technique Benefit
Lazy Loading Background parsing of metadata entries Faster initial page load
Virtual Scrolling Render only visible rows Smooth scrolling with large datasets
Certificate Caching Cache decoded certificate information Reduced computation overhead
Filter Debouncing Delay filter updates during rapid changes Improved responsiveness
Progressive Enhancement Load basic functionality first Progressive feature enhancement

Section sources

Security Considerations

Trust Anchor Protection

The system implements multiple layers of security for trust anchor management:

flowchart LR
A[Trust Anchor Source] --> B[Validation Layer]
B --> C[Certificate Verification]
C --> D[Signature Validation]
D --> E[Root Certificate Matching]
F[Metadata Source] --> G[Integrity Check]
G --> H[Schema Validation]
H --> I[Content Verification]
E --> J[Trust Decision]
I --> J
J --> K{Trusted?}
K --> |Yes| L[Accept Metadata]
K --> |No| M[Reject Metadata]
M --> N[Security Logging]

Diagram sources

Revocation Checking

The system performs comprehensive revocation checking:

Check Type Implementation Purpose
Status Reports Filter entries with REVOKED status Prevent use of compromised authenticators
Attestation Key Compromise Check for compromised certificates Detect compromised attestation keys
Time-Based Validation Verify certificate validity periods Ensure certificates are current
Chain Validation Verify complete certificate chains Confirm certificate authenticity

Section sources

Metadata Tampering Protection

Several mechanisms protect against metadata tampering:

  • Digital Signatures: All metadata is cryptographically signed
  • Integrity Checks: Hash-based verification of metadata content
  • Source Tracking: Record origin of metadata entries
  • Audit Logging: Comprehensive logging of metadata operations
  • Validation Rules: Strict schema validation for metadata content

Implementation Details

Attestation Verification Workflow

The attestation verification process follows a structured workflow:

sequenceDiagram
participant Client as Authenticator
participant Server as Web Server
participant MDS as MDS Verifier
participant Cache as Metadata Cache
Client->>Server : Registration Request
Server->>MDS : Parse Attestation
MDS->>Cache : Lookup Authenticator Info
Cache-->>MDS : Return Metadata Entry
MDS->>MDS : Validate Trust Chain
MDS->>MDS : Check Status Reports
MDS->>MDS : Verify Algorithms
MDS-->>Server : Verification Result
Server-->>Client : Registration Response

Diagram sources

Metadata Snapshot Update Process

The update process ensures metadata remains current:

flowchart TD
A[Check Cache Age] --> B{Cache Stale?}
B --> |No| C[Use Cached Metadata]
B --> |Yes| D[Fetch Remote Snapshot]
D --> E[Verify Signature]
E --> F{Signature Valid?}
F --> |No| G[Log Error & Use Cache]
F --> |Yes| H[Parse Metadata]
H --> I[Validate Structure]
I --> J{Structure Valid?}
J --> |No| K[Log Error & Use Cache]
J --> |Yes| L[Update Cache]
L --> M[Notify Clients]
C --> N[Return Metadata]
G --> N
K --> N
M --> N

Diagram sources

Section sources

Testing and Validation

Unit Test Coverage

The MDS integration includes comprehensive testing:

Test Category Coverage Purpose
MDS3 Parser JWT parsing, signature verification Ensure proper JWT handling
Metadata Manager Caching, session management Validate server-side functionality
Frontend Components Lazy loading, filtering Test client-side performance
Integration Tests End-to-end workflows Verify complete functionality

Section sources

Validation Examples

The system provides practical examples of authenticator validation:

flowchart LR
A[Authenticator AAGUID] --> B[Lookup Metadata Entry]
B --> C[Validate Status Reports]
C --> D{Status OK?}
D --> |No| E[Reject Authenticator]
D --> |Yes| F[Verify Trust Chain]
F --> G{Chain Valid?}
G --> |No| E
G --> |Yes| H[Check Algorithms]
H --> I{Algorithms Supported?}
I --> |No| E
I --> |Yes| J[Accept Authenticator]

Diagram sources

Troubleshooting Guide

Common Issues and Solutions

Issue Symptoms Solution
Metadata Cache Stale Outdated authenticator information Run update script or clear cache
Signature Verification Failure "Metadata signing certificate does not expose a supported public key" Check trust anchor configuration
Session Metadata Conflicts Unexpected metadata behavior Clear session cookies and restart
Performance Issues Slow metadata loading Enable lazy loading and optimize filters
Certificate Validation Errors Trust chain failures Verify certificate validity and trust anchors

Debugging Tools

The system provides several debugging capabilities:

  • Console Logging: Detailed logs for metadata operations
  • Status Indicators: Visual feedback on metadata status
  • Error Reporting: Comprehensive error messages with context
  • Performance Metrics: Timing information for optimization
  • Security Auditing: Complete audit trail of metadata operations

Conclusion

The Metadata Service (MDS) integration provides a robust foundation for authenticator attestation validation and device trustworthiness verification. Through its layered architecture, comprehensive security measures, and performance optimizations, the system ensures reliable and secure operation in production environments.

Key strengths of the implementation include:

  • Comprehensive Validation: Multi-layered security checks for authenticator trustworthiness
  • Performance Optimization: Lazy loading and caching mechanisms for efficient operation
  • Flexible Architecture: Support for both base metadata and custom session-based additions
  • Security Focus: Multiple layers of protection against tampering and compromise
  • Developer-Friendly: Extensive testing and debugging capabilities

The MDS integration successfully balances security, performance, and usability, providing a solid foundation for WebAuthn implementations that require authenticator attestation validation and device trust verification.