mds

README

go-ctap/mds

go-ctap/mds is a Go client for the FIDO Metadata Service (MDS3).

[!WARNING] This module is under active development. Its public API may change during v0.x.

Features

• downloads and verifies the signed FIDO metadata BLOB;
• validates the signing certificate chain and CRLs;
• rejects metadata rollback;
• caches verified metadata and limits network requests;
• looks up metadata by AAGUID;
• checks verified authenticator attestations against metadata roots and status reports.

Installation

go get github.com/go-ctap/mds@latest

See go.mod for the required Go version.

Quick start

client := mds.NewClient()

result, err := client.Lookup(ctx, aaguid, mds.LookupOptions{})
if err != nil {
    return err
}
if result.Found {
    fmt.Println(result.Entry.MetadataStatement.Description)
}

Lookup uses the official FIDO MDS endpoint by default.

Caching

The client always checks its verified cache before making a network request. It uses an in-memory cache and stores the signed BLOB in the platform user cache directory.

Use WithCacheDir when the application owns the cache location:

client := mds.NewClient(
    mds.WithCacheDir("/var/cache/my-service/fido-mds"),
)

Automatic refresh runs at most once per day. An explicit refresh is limited to one request per hour for each cache key:

result, err := client.Lookup(ctx, aaguid, mds.LookupOptions{
    Refresh: true,
})

The request includes localCopySerial when a local BLOB exists. If refresh fails, the client returns the last verified local BLOB and delays the next automatic attempt.

Attestation checks

AssessAttestation compares an already verified authenticator attestation certificate chain with the matching metadata statement. It reports trust facts and authenticator status issues.

Attestation parsing and format-level signature verification belong to github.com/go-ctap/ctap/attestation. The relying party remains responsible for its acceptance policy.

Testing

go test ./...
go vet ./...

License

Apache License 2.0. See LICENSE.

Documentation

Overview

Package mds fetches, verifies, caches, and queries FIDO Metadata Service blobs.

Index

• Constants
• Variables
• func AssessAttestation(evidence AttestationEvidence, metadata model.LookupResult, ...) model.AttestationTrustAssessment
• type AttestationEvidence
• type AttestationType
• type Blob
• type Cache
  • func NewCache() Cache
• type Client
  • func NewClient(options ...Option) *Client
  • func (c *Client) Lookup(ctx context.Context, aaguid uuid.UUID, opts LookupOptions) (appmds.LookupResult, error)
• type HTTPStatusError
  • func (e *HTTPStatusError) Error() string
  • func (e *HTTPStatusError) Unwrap() error
• type LookupOptions
• type Option
  • func WithCacheDir(dir string) Option

Constants

const (
	DefaultSource          = "https://mds.fidoalliance.org/"
	DefaultRefreshInterval = 24 * time.Hour
	DefaultMaxBlobBytes    = 64 << 20 // 64 MiB

)

Variables

var (
	ErrInvalidAAGUID = errors.New("invalid AAGUID")
	ErrFetch         = errors.New("fetch MDS blob")
	ErrVerify        = errors.New("verify MDS blob")
)

Functions

func AssessAttestation

func AssessAttestation(
	evidence AttestationEvidence,
	metadata model.LookupResult,
	currentTime time.Time,
) model.AttestationTrustAssessment

AssessAttestation evaluates attestation evidence against one verified MDS lookup result. It does not apply relying-party certification policy.

Types

type AttestationEvidence

type AttestationEvidence struct {
	AAGUID           uuid.UUID
	Type             AttestationType
	CertificateChain [][]byte
}

AttestationEvidence identifies the authenticator and carries the untrusted certificate chain extracted from a verified attestation statement.

type AttestationType

type AttestationType string

AttestationType describes the trust material exposed by a format-level attestation verifier. It deliberately does not prescribe relying-party certification policy.

const (
	AttestationTypeNone        AttestationType = "none"
	AttestationTypeSelf        AttestationType = "self"
	AttestationTypeBasic       AttestationType = "basic"
	AttestationTypeUnsupported AttestationType = "unsupported"
)

type Blob

type Blob struct {
	Number uint64

	// IssuedAt is best-effort metadata. It is read from the MDS JWT header iat
	// when present, otherwise from the standard payload iat parsed by
	// jwt.RegisteredClaims. It is zero when both are absent.
	IssuedAt time.Time

	Entries map[uuid.UUID]*appmds.PayloadEntry

	CachedAt time.Time
}

Blob is a verified and indexed MDS payload. Treat it as immutable after storing it in Cache.

type Cache

type Cache interface {
	Get(source string) (*Blob, bool)
	Set(source string, blob *Blob)
	Refresh(context.Context, string, func() (*Blob, bool, error)) (*Blob, bool, error)
}

Cache stores verified MDS blobs and coordinates refreshes by cache key.

func NewCache

func NewCache() Cache

NewCache creates a process-local MDS blob cache.

type Client

type Client struct {
	Source       string
	HTTPClient   *http.Client
	Cache        Cache
	CacheDir     string
	TrustAnchors []*x509.Certificate

	// MaxBlobBytes bounds metadata BLOB downloads. Zero means DefaultMaxBlobBytes.
	MaxBlobBytes int64

	// Now is injectable for deterministic tests.
	Now func() time.Time
}

Client fetches, caches, and looks up verified FIDO Metadata Service blobs. Signature, x5u/x5c, certificate-chain and CRL validation live in internal/mdsverify.

func NewClient

func NewClient(options ...Option) *Client

NewClient creates an MDS client with cache-first defaults.

func (*Client) Lookup

func (c *Client) Lookup(ctx context.Context, aaguid uuid.UUID, opts LookupOptions) (appmds.LookupResult, error)

Lookup returns verified MDS data for one AAGUID.

type HTTPStatusError

type HTTPStatusError struct {
	StatusCode int
}

HTTPStatusError reports a non-success response from the configured MDS endpoint.

func (*HTTPStatusError) Error

func (e *HTTPStatusError) Error() string

func (*HTTPStatusError) Unwrap

func (e *HTTPStatusError) Unwrap() error

type LookupOptions

type LookupOptions struct {
	// Refresh forces a conditional network refresh attempt, but still loads the
	// local copy first so localCopySerial and anti-rollback checks keep working.
	Refresh bool
}

LookupOptions configures one MDS lookup.

type Option

type Option func(*Client)

Option configures a Client created by NewClient.

func WithCacheDir

func WithCacheDir(dir string) Option

WithCacheDir stores verified MDS JWTs below dir.