Skip to main content

python-fido-mds

FIDO Alliance Metadata Service (MDS) in a Python package with WebAuthn attestation verification.

License Python

Overview

This package provides:

  • FIDO Metadata Service (MDS) - Bundled and regularly updated FIDO Alliance authenticator metadata
  • Attestation Verification - Comprehensive WebAuthn attestation format support
  • Type Safety - Full Pydantic models for type-safe metadata and attestation handling
  • Production Ready - Used in production environments for WebAuthn authentication

Features

FIDO Metadata Service

  • Regularly updated authenticator metadata from FIDO Alliance
  • Certificate chain verification
  • Metadata statement validation
  • Support for status reports

Attestation Format Support

  • ✅ Android Key - Complete KeyMint 4.0+ implementation with security validations

From python-fido2:

  • ✅ Packed - Standard packed attestation format
  • ✅ TPM - Trusted Platform Module attestation
  • ✅ Android SafetyNet - Legacy Android attestation (via fido2 library)
  • ✅ Apple Anonymous - Apple device attestation
  • ✅ FIDO U2F - Universal 2nd Factor attestation
  • ✅ None - Self attestation

Installation

pip install fido-mds

Development Installation

# Clone the repository
git clone https://github.com/SUNET/python-fido-mds.git
cd python-fido-mds

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Or using uv (faster)
uv pip install -e ".[dev]"

# Verify installation
pytest src
make reformat
make typecheck

This installs:

  • All runtime dependencies (fido2, pydantic, cryptography, pyOpenSSL, asn1crypto)
  • All development tools (pytest, pytest-cov, ruff, mypy)

Quick Start

Basic Attestation Verification

from fido_mds import FidoMetadataStore
from fido_mds.models.webauthn import Attestation
from fido2.utils import websafe_decode

# Initialize metadata store
mds = FidoMetadataStore()

# Parse attestation object and client data
attestation = Attestation.from_base64(attestation_object_b64)
client_data = websafe_decode(client_data_b64)

# Verify attestation
try:
    result = mds.verify_attestation(attestation, client_data)
    print(f"✅ Attestation verified: {result}")
except Exception as e:
    print(f"❌ Verification failed: {e}")

Android Key Attestation

from fido_mds.models.attestation import AndroidKeyAttestation
import hashlib

# Create verifier
verifier = AndroidKeyAttestation()

# Prepare data
client_data_hash = hashlib.sha256(client_data).digest()

# Verify
result = verifier.verify(
    statement=attestation.attestation_obj.att_stmt,
    auth_data=attestation.attestation_obj.auth_data,
    client_data_hash=client_data_hash
)

Documentation

  • DEVELOPMENT.md - Comprehensive development guide including:
    • Setup and installation
    • Development workflow
    • Testing guidelines
    • Code quality standards
    • Architecture overview
    • Special LLM section for AI-assisted development

Architecture

fido-mds/
├── models/
│   ├── attestation.py    # Attestation format implementations
│   ├── fido_mds.py       # FIDO MDS models
│   └── webauthn.py       # WebAuthn models
├── data/                 # Bundled metadata
├── tests/                # Test suite
│   ├── data.py          # Test attestation objects
│   └── test_*.py        # Test modules
├── helpers.py           # Utility functions
└── metadata_store.py    # Main API

Requirements

  • Python 3.10 or higher (tested with 3.13.3)
  • fido2 >= 2.0.0
  • pydantic >= 2.0
  • cryptography
  • pyOpenSSL
  • asn1crypto (for Android Key attestation)

Development

Running Tests

# Activate virtualenv
source /path/to/virtualenv/bin/activate

# Run all tests
make test

# Run specific test
pytest src/fido_mds/tests/test_verify.py -v

Code Quality

# Format code
make reformat

# Type checking
make typecheck

# Run all checks
make reformat && make typecheck && make test

See DEVELOPMENT.md for detailed development guidelines.

WebAuthn Specification Compliance

This package implements attestation verification according to:

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Run all quality checks (make reformat && make typecheck && make test)
  5. Submit a pull request

See DEVELOPMENT.md for detailed contribution guidelines.

Testing

The test suite includes real attestation objects from various authenticators:

  • Android Key: Google Pixel 8a, Samsung Tab S10+
  • FIDO U2F: YubiKey 4/5
  • Packed: YubiKey 5, Samsung Galaxy devices
  • Apple Anonymous: iPhone, MacBook with Touch ID
  • TPM: Windows Hello, Surface devices

All test data is sourced from actual WebAuthn registrations to ensure real-world compatibility.

Test Coverage

# Run all tests
make test  # 15/15 passing

# Run specific test file
pytest src/fido_mds/tests/test_verify.py -v

# Test with coverage (optional, requires pytest-cov)
# pip install pytest-cov
# pytest src --cov=fido_mds --cov-report=html

License

BSD 3-Clause License. See LICENSE file for details.

Credits

References

Changelog

October 2025

Complete Android Key Attestation Implementation

  • ✅ Full KeyDescription parsing - Complete ASN.1 structure parsing with proper error handling
  • ✅ Origin validation - Tag 702 (KM_ORIGIN_GENERATED) verification in hardwareEnforced
  • ✅ Purpose validation - Tag 1 (KM_PURPOSE_SIGN) verification in hardwareEnforced
  • ✅ Security field validation - Tag 600 (allApplications) rejection with correct DER encoding
  • ✅ Certificate chain validation - Public key matching against Google Hardware Attestation roots
  • ✅ Full structure scanning - Removed arbitrary byte limits, scans complete AuthorizationLists
  • ✅ WebAuthn compliance - Follows WebAuthn Level 2 and Android Key Attestation specifications

Security Improvements

  • 🔒 Fixed allApplications detection - Correct DER encoding (0xBF 0x84 0x58) instead of wrong pattern
  • 🔒 Public key matching - Validates root certificates by public key, not just subject name
  • 🔒 Complete field scanning - Removed dangerous [:50] and [:100] byte limits
  • 🔒 Certificate re-issuance handling - Properly handles Google root certificate updates

Test Coverage

  • ✅ Google Pixel 8a (Android Key attestation)
  • ✅ Samsung Tab S10+ (Android Key attestation)
  • ✅ YubiKey 4/5 (FIDO U2F and Packed)
  • ✅ Apple devices (iPhone, MacBook)
  • ✅ TPM attestation

Documentation

  • ✅ Comprehensive DEVELOPMENT.md with LLM-specific guidelines
  • ✅ Updated README with detailed Android Key attestation features
  • ✅ Architecture documentation
  • ✅ Security validation documentation

Support

For issues, questions, or contributions:


Note: This package bundles FIDO Alliance metadata. Please ensure you comply with the FIDO Alliance Metadata Service Terms of Use.

Metadata

Release files for fido-mds 2026.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fido-mds 2026.10
File Size Uploaded Provenance Actions
fido_mds-2026.10.tar.gz 4.0 MB With provenance Details for fido_mds-2026.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fido-mds 2026.10
File Interpreter ABI Platform Actions
fido_mds-2026.10-py3-none-any.whl Python 3 none any Details for fido_mds-2026.10-py3-none-any.whl

Total release size: 7.9 MB

Release files / fido_mds-2026.10.tar.gz

Download URL fido_mds-2026.10.tar.gz
Size 4.0 MB
Tags Source
SHA-256 checksum
How to use checksums
2cb6d8cee7dc4f34556b6d15e0b76ec3938c0f68ad8f00ebd317950c68f1f2f4
BLAKE2b-256 checksum
How to use checksums
6ce3c04af52fbeca4931eceb3ef147f26a293ca6371ad25f7eff9740452f5f8b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

Release files / fido_mds-2026.10-py3-none-any.whl

Download URL fido_mds-2026.10-py3-none-any.whl
Size 4.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
c83cbda4dcdb4451c8eea055a9edb452aad8b188d22a69bbdc8404d48c47b3db
BLAKE2b-256 checksum
How to use checksums
eb209ab3b54cc5fa4b00aa076e4ebb35aff53dfd4cf1c615d09d166462cac257
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

Security for fido-mds 2026.10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fido_mds-2026.10.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page