MDS Validation Errors

MDS Validation Errors

Table of Contents

1. Introduction
2. MDS Architecture Overview
3. JWT Signature Verification Failures
4. Trust Anchor Certificate Mismatches
5. Metadata Cache Corruption Issues
6. MDS Bootstrap Process Troubleshooting
7. Certificate Chain Validation Debugging
8. TLS Trust Anchor Configuration
9. Manual MDS Snapshot Updates
10. Network-Related Issues
11. Certificate Expiration Problems
12. Clock Synchronization Requirements
13. Common Error Scenarios
14. Troubleshooting Guide

Introduction

The Metadata Service (MDS) in the Post-Quantum WebAuthn Platform serves as a critical component for authenticator attestation validation. It maintains a comprehensive database of authenticator metadata, including certification status, cryptographic capabilities, and trust anchors. This document provides detailed guidance on diagnosing and resolving MDS validation errors, covering JWT signature verification failures, certificate trust anchor mismatches, and various network-related issues.

MDS Architecture Overview

The MDS system consists of several interconnected components that work together to validate authenticator attestations:

graph TB
subgraph "MDS Components"
MDS3[MDS3 Parser]
Verifier[MDS Attestation Verifier]
Metadata[Metadata Store]
Cache[Cache Manager]
end
subgraph "External Sources"
Blob[JWKS Blob]
TrustRoot[Trust Root Certificates]
Network[Network Layer]
end
subgraph "Validation Pipeline"
JWT[JWT Verification]
Chain[Certificate Chain]
MDS[MDS Lookup]
end
Blob --> MDS3
TrustRoot --> JWT
Network --> Blob
MDS3 --> Verifier
Verifier --> Metadata
Metadata --> Cache
JWT --> Chain
Chain --> MDS
MDS --> Verifier

Loading

Diagram sources

• fido2/mds3.py
• server/server/metadata.py

Section sources

• fido2/mds3.py
• server/server/metadata.py

JWT Signature Verification Failures

JWT (JSON Web Token) signature verification is the first line of defense in MDS validation. When this fails, it indicates fundamental issues with the authenticity and integrity of the metadata blob.

Common JWT Verification Errors

Error Type	Description	Cause	Resolution
InvalidSignature	JWT signature validation failed	Incorrect trust root certificate or corrupted JWT payload	Verify trust root certificate and JWT structure
ValueError: Metadata signing certificate does not expose a supported public key	Unsupported public key algorithm	Certificate uses unsupported cryptographic algorithm	Update certificate or modify supported algorithms
parse_blob without trust anchor, CONTENT IS NOT VERIFIED!	Missing trust anchor for verification	Trust root not provided for JWT validation	Configure proper trust anchor certificate

Debugging JWT Verification

The JWT verification process involves several critical steps:

sequenceDiagram
participant Client as "Client Application"
participant Parser as "MDS3 Parser"
participant Crypto as "Cryptography Backend"
participant Trust as "Trust Anchor"
Client->>Parser : parse_blob(blob, trust_root)
Parser->>Parser : Split JWT (message, signature_b64)
Parser->>Parser : Decode header and payload
Parser->>Crypto : Load certificate chain
Parser->>Crypto : Verify X.509 chain
Parser->>Crypto : Extract public key
Parser->>Crypto : Verify signature
Crypto-->>Parser : Verification result
Parser-->>Client : MetadataBlobPayload or error

Loading

Diagram sources

• fido2/mds3.py

Troubleshooting JWT Issues

1. Verify Trust Root Certificate: Ensure the GlobalSign root certificate is correctly configured
2. Check JWT Structure: Validate the JWT follows the expected format (header.payload.signature)
3. Examine Public Key Algorithm: Confirm the certificate uses supported algorithms (ECDSA, RSA)
4. Validate Certificate Chain: Ensure the complete certificate chain is available

Section sources

• fido2/mds3.py
• tests/test_mds3.py

Trust Anchor Certificate Mismatches

Trust anchor certificate mismatches occur when the certificate used to verify the MDS blob doesn't match the expected root certificate or when certificate validation fails.

Certificate Validation Process

flowchart TD
Start([Certificate Validation]) --> LoadCert["Load Leaf Certificate"]
LoadCert --> ParseChain["Parse Certificate Chain"]
ParseChain --> VerifyChain["Verify Certificate Chain"]
VerifyChain --> ExtractIssuer["Extract Issuer Information"]
ExtractIssuer --> MatchRoot{"Match Root Certificate?"}
MatchRoot --> |Yes| Success["Validation Successful"]
MatchRoot --> |No| CheckFallback["Check Fallback Roots"]
CheckFallback --> FallbackMatch{"Fallback Match?"}
FallbackMatch --> |Yes| Success
FallbackMatch --> |No| Failure["Validation Failed"]
Success --> End([End])
Failure --> End

Loading

Diagram sources

• fido2/mds3.py

Common Trust Anchor Issues

Issue	Symptoms	Solution
Root Certificate Not Found	"No attestation root matching subject"	Add correct root certificate to trust store
Certificate Mismatch	Trust anchor certificate doesn't match expected	Verify certificate fingerprint or subject
Expired Trust Anchor	Certificate validity period exceeded	Update trust anchor certificate
Unsupported Algorithm	Certificate uses unsupported algorithm	Use certificates with supported algorithms

Debugging Certificate Mismatches

The MDS3 parser attempts to match the certificate issuer with known root certificates:

Section sources

• fido2/mds3.py
• server/server/attestation.py

Metadata Cache Corruption Issues

Metadata cache corruption can manifest in various ways, affecting the availability and accuracy of authenticator metadata.

Cache Structure and Validation

The metadata cache follows a specific structure that must be maintained:

erDiagram
CACHE_ENTRY {
string last_modified
string last_modified_iso
string etag
string fetched_at
}
METADATA_SNAPSHOT {
string legal_header
int no
date next_update
array entries
}
METADATA_ENTRY {
string aaid
string aaguid
object metadata_statement
array status_reports
array attestation_certificate_key_identifiers
}
CACHE_ENTRY ||--|| METADATA_SNAPSHOT : contains
METADATA_SNAPSHOT ||--o{ METADATA_ENTRY : includes

Loading

Diagram sources

• scripts/update_mds_snapshot.py
• server/server/metadata.py

Common Cache Issues

Problem	Indicators	Resolution
JSON Decode Error	Malformed cache file	Regenerate cache using update script
Missing Entries	Empty or partial metadata	Force cache refresh
Timestamp Mismatch	Outdated cache	Update cache with current timestamp
Permission Issues	Access denied errors	Fix file permissions

Section sources

• scripts/update_mds_snapshot.py
• server/server/metadata.py

MDS Bootstrap Process Troubleshooting

The MDS bootstrap process initializes the metadata system and handles various failure scenarios gracefully.

Bootstrap Workflow

sequenceDiagram
participant App as "Application"
participant Bootstrap as "Bootstrap Handler"
participant Cache as "Cache Manager"
participant Network as "Network Layer"
participant Storage as "File System"
App->>Bootstrap : Initialize MDS
Bootstrap->>Cache : Check cached metadata
Cache-->>Bootstrap : Cache status
alt Cache Available
Bootstrap->>Storage : Load cached metadata
Storage-->>Bootstrap : Metadata loaded
else Cache Missing/Expired
Bootstrap->>Network : Download fresh blob
Network-->>Bootstrap : Blob downloaded
Bootstrap->>Storage : Store new cache
end
Bootstrap-->>App : Bootstrap complete

Loading

Diagram sources

• tests/test_metadata_bootstrap.py

Bootstrap Error Scenarios

The bootstrap process handles several error conditions:

1. Network Failures: When metadata download fails, the system falls back to packaged metadata
2. Cache Corruption: Invalid cache files trigger regeneration
3. Permission Issues: Insufficient permissions prevent cache updates
4. Missing Dependencies: Required libraries or configurations missing

Section sources

• tests/test_metadata_bootstrap.py
• server/server/metadata.py

Certificate Chain Validation Debugging

Certificate chain validation is crucial for establishing trust in authenticator certificates. The platform implements comprehensive validation logic.

Chain Validation Process

flowchart TD
Start([Start Chain Validation]) --> LoadCerts["Load Certificate Chain"]
LoadCerts --> ValidateFormat["Validate Certificate Format"]
ValidateFormat --> CheckValidity["Check Certificate Validity Period"]
CheckValidity --> VerifySignature["Verify Certificate Signatures"]
VerifySignature --> CheckExtensions["Validate Extensions"]
CheckExtensions --> NextCert{"More Certificates?"}
NextCert --> |Yes| VerifySignature
NextCert --> |No| Success["Chain Valid"]
ValidateFormat --> |Invalid| FormatError["Format Error"]
CheckValidity --> |Expired/Not Yet Valid| ValidityError["Validity Error"]
VerifySignature --> |Invalid| SignatureError["Signature Error"]
CheckExtensions --> |Invalid| ExtensionError["Extension Error"]
FormatError --> Failure["Validation Failed"]
ValidityError --> Failure
SignatureError --> Failure
ExtensionError --> Failure
Success --> End([End])
Failure --> End

Loading

Diagram sources

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

Common Chain Validation Issues

Error Type	Description	Debug Steps
InvalidSignature	Certificate signature verification failed	Check certificate chain and public keys
certificate_parse_error	Unable to parse certificate	Validate certificate format and encoding
certificate_out_of_validity	Certificate validity period expired	Check certificate dates and system clock
trust_path_missing	No certificate chain provided	Verify attestation statement contains x5c

Debugging Certificate Chains

The platform provides detailed error reporting for certificate chain issues:

Section sources

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

TLS Trust Anchor Configuration

Proper TLS trust anchor configuration is essential for secure communication with MDS servers and other external services.

Trust Anchor Configuration

The platform supports multiple trust anchor configurations:

graph LR
subgraph "Trust Anchors"
FIDO[FIDO Root Certificate]
Additional[Additional Trust Anchors]
Custom[Custom Trust Anchors]
end
subgraph "Configuration Sources"
Config[Configuration File]
Environment[Environment Variables]
Runtime[Runtime Settings]
end
Config --> FIDO
Environment --> Additional
Runtime --> Custom
FIDO --> Validation[TLS Validation]
Additional --> Validation
Custom --> Validation

Loading

Diagram sources

• server/server/config.py

Trust Anchor Types

Anchor Type	Purpose	Configuration
FIDO Root Certificate	Primary MDS trust anchor	Built-in PEM certificate
Additional Trust Anchors	Extended certificate pool	Multiple PEM certificates
Custom Trust Anchors	Application-specific	Environment variable or config

Configuration Options

The platform provides flexible trust anchor configuration through multiple mechanisms:

Section sources

• server/server/config.py

Manual MDS Snapshot Updates

When automatic updates fail or need to be performed manually, the platform provides tools for updating MDS snapshots.

Update Process

sequenceDiagram
participant Script as "update_mds_snapshot.py"
participant Remote as "MDS Server"
participant Local as "Local Storage"
participant Cache as "Cache System"
Script->>Remote : Fetch blob.jwt
Remote-->>Script : Binary blob data
Script->>Script : Parse JWT structure
Script->>Script : Verify signature
Script->>Local : Write blob.jwt
Script->>Local : Write verified.json
Script->>Cache : Update cache metadata
Cache-->>Script : Confirmation

Loading

Diagram sources

• scripts/update_mds_snapshot.py

Update Script Features

The update script provides comprehensive functionality:

1. Automatic Download: Downloads latest MDS blob from mds3.fidoalliance.org
2. Signature Verification: Validates JWT signature using GlobalSign root certificate
3. Cache Management: Updates cache metadata with timestamps and ETags
4. Error Handling: Graceful handling of network and parsing errors

Manual Update Commands

To manually update the MDS snapshot:

# Run the update script
python scripts/update_mds_snapshot.py

# Check for errors
# Expected output: "Packaged metadata snapshot refreshed."

Section sources

• scripts/update_mds_snapshot.py

Network-Related Issues

Network connectivity problems can significantly impact MDS functionality, causing timeouts, connection failures, and incomplete downloads.

Network Error Categories

Error Type	Symptoms	Solutions
Connection Timeout	Request hangs indefinitely	Increase timeout values, check network
DNS Resolution	Cannot resolve hostname	Verify DNS configuration
SSL/TLS Handshake	Certificate validation fails	Check certificate chain and trust anchors
Rate Limiting	Requests rejected with 429	Implement exponential backoff
Firewall Blocking	Connections blocked	Configure firewall rules

Network Troubleshooting Steps

1. Verify Connectivity: Test basic network connectivity to mds3.fidoalliance.org
2. Check Proxy Settings: Ensure proxy configuration is correct
3. Validate SSL/TLS: Verify SSL/TLS certificate chain
4. Monitor Bandwidth: Check for bandwidth limitations
5. Review Logs: Examine network-related error logs

Section sources

• scripts/update_mds_snapshot.py

Certificate Expiration Problems

Certificate expiration can cause validation failures and disrupt MDS functionality.

Expiration Detection

The platform implements comprehensive certificate expiration checking:

flowchart TD
Start([Certificate Check]) --> LoadCert["Load Certificate"]
LoadCert --> GetDates["Get Validity Dates"]
GetDates --> CheckPast{"Current Date > NotAfter?"}
CheckPast --> |Yes| Expired["Certificate Expired"]
CheckPast --> |No| CheckFuture{"Current Date < NotBefore?"}
CheckFuture --> |Yes| NotYetValid["Certificate Not Yet Valid"]
CheckFuture --> |No| Valid["Certificate Valid"]
Expired --> LogWarning["Log Expiration Warning"]
NotYetValid --> LogWarning
Valid --> Continue["Continue Validation"]
LogWarning --> End([End])
Continue --> End

Loading

Diagram sources

• server/server/attestation.py

Expiration Handling Strategies

Scenario	Detection Method	Action
Near Expiration	Days until expiration	Alert administrators
Expired Certificate	Current date past NotAfter	Reject certificate
Future Certificate	Current date before NotBefore	Hold for activation
Unknown Expiration	Missing validity dates	Flag for review

Preventive Measures

1. Regular Monitoring: Monitor certificate expiration dates
2. Automated Alerts: Set up alerts for approaching expirations
3. Proactive Renewal: Renew certificates before expiration
4. Fallback Mechanisms: Maintain backup certificates

Section sources

• server/server/attestation.py

Clock Synchronization Requirements

Accurate system clock is critical for certificate validation and JWT timestamp verification.

Clock Requirements

Component	Precision Requirement	Impact of Drift
System Clock	±1 minute	Certificate validity checks
NTP Sync	±10 milliseconds	JWT timestamp validation
Hardware Clock	±1 second	Boot-time validation

Clock Synchronization Issues

1. Negative Drift: System clock runs slow
2. Positive Drift: System clock runs fast
3. Time Zone Issues: Incorrect time zone configuration
4. Leap Seconds: Leap second handling problems

Synchronization Solutions

graph TB
subgraph "Clock Sources"
NTP[NTP Server]
GPS[GPS Receiver]
Atomic[Atomic Clock]
end
subgraph "System Services"
Chrony[Chrony Daemon]
NTPd[NTP Daemon]
System[System Clock]
end
subgraph "Validation"
Certs[Certificate Validation]
JWTs[JWT Validation]
Logs[Log Timestamps]
end
NTP --> Chrony
GPS --> Chrony
Atomic --> NTPd
Chrony --> System
NTPd --> System
System --> Certs
System --> JWTs
System --> Logs

Loading

Section sources

• server/server/attestation.py

Common Error Scenarios

Understanding common error patterns helps in rapid diagnosis and resolution.

Authentication Failures

flowchart TD
AuthReq[Authentication Request] --> ValidateJWT{JWT Valid?}
ValidateJWT --> |No| JWTError[JWT Signature Error]
ValidateJWT --> |Yes| ValidateCert{Certificate Valid?}
ValidateCert --> |No| CertError[Certificate Error]
ValidateCert --> |Yes| ValidateMDS{MDS Entry Valid?}
ValidateMDS --> |No| MDSError[MDS Lookup Error]
ValidateMDS --> |Yes| Success[Authentication Success]
JWTError --> LogError[Log Error Details]
CertError --> LogError
MDSError --> LogError
LogError --> ErrorResponse[Return Error Response]

Loading

Error Classification

Error Category	Examples	Severity
Authentication	JWT signature invalid, certificate expired	High
Authorization	MDS entry not found, revoked status	Medium
System	Network timeout, disk full	Low
Configuration	Missing trust anchor, invalid settings	Medium

Section sources

• server/server/attestation.py

Troubleshooting Guide

This section provides systematic approaches to diagnosing and resolving MDS validation issues.

Diagnostic Checklist

1. Verify Network Connectivity

   • Test connection to mds3.fidoalliance.org
   • Check firewall and proxy settings
   • Validate DNS resolution

2. Check Certificate Status

   • Verify certificate validity periods
   • Validate certificate chain completeness
   • Confirm trust anchor configuration

3. Examine System Clock

   • Verify system time accuracy
   • Check NTP synchronization
   • Review time zone settings

4. Inspect Cache Health

   • Validate cache file integrity
   • Check cache freshness
   • Review cache permissions

Step-by-Step Resolution

Step 1: Initial Diagnosis

# Check MDS service status
curl -I https://mds3.fidoalliance.org/

# Verify certificate chain
openssl s_client -connect mds3.fidoalliance.org:443 -showcerts

Step 2: Cache Validation

# Check cache file existence and permissions
ls -la server/server/static/fido-mds3.verified.json*
ls -la server/server/static/fido-mds3.verified.json.meta.json

# Validate JSON structure
python -m json.tool server/server/static/fido-mds3.verified.json

Step 3: Manual Update

# Force cache update
cd scripts
python update_mds_snapshot.py

# Verify update success
cat ../server/server/static/fido-mds3.verified.json.meta.json

Recovery Procedures

1. Cache Corruption Recovery

   • Delete corrupted cache files
   • Run manual update script
   • Verify cache reconstruction

2. Certificate Issues

   • Update trust anchor certificates
   • Refresh certificate chains
   • Validate certificate algorithms

3. Network Problems

   • Configure proxy settings
   • Adjust timeout values
   • Implement retry logic

Monitoring and Prevention

Implement comprehensive monitoring to detect issues early:

• Health Checks: Regular MDS endpoint testing
• Alerts: Certificate expiration notifications
• Logging: Detailed error logging and analysis
• Backups: Regular cache backups

Section sources

• scripts/update_mds_snapshot.py
• server/server/metadata.py