webauthn

Documentation

Overview

AAGUID naming. The AAGUID identifies the authenticator model, but the bytes are meaningless without a lookup; this curated table covers the passkey providers and security keys developers actually see in 2026. It is community-sourced (provider documentation and the public passkey AAGUID lists) and deliberately small — unknown values render as plain UUIDs, never as guesses.

Attestation object parsing (WebAuthn Level 3 §6.5): the outer CBOR map (fmt / attStmt / authData) plus format-specific explanation of the attestation statement for every format registered with IANA that shows up in real registrations.

Authenticator data parsing (WebAuthn Level 3 §6.1): the fixed 37-byte header, optional attested credential data, and optional CTAP2 extensions.

clientDataJSON parsing (WebAuthn Level 3 §5.8.1). The JSON itself is trivial; the value is in the cross-checks — challenge entropy, origin scheme, ceremony type — because this small object is where most "verification failed" tickets are actually born.

SafetyNet JWS splitting. The android-safetynet response is a compact JWS (three base64url segments); v0.1.0 decodes the header and payload JSON so the verdict fields are readable, without verifying the signature.

x5c attestation certificate summaries. Attestation statements carry DER certificates inside CBOR byte strings; crypto/x509 (standard library) parses them and this file distills what a debugging session needs: who issued what to whom, when it expires, and whether the FIDO AAGUID certificate extension agrees with the authenticator data.

Index

• func AAGUIDName(b []byte) string
• func FormatAAGUID(b []byte) string
• type Attestation
  • func ParseAttestationObject(raw []byte) (*Attestation, error)
• type AttestedCredential
• type AuthenticatorData
  • func ParseAuthenticatorData(raw []byte) (*AuthenticatorData, error)
  • func (ad *AuthenticatorData) CheckRPID(rpID string) bool
• type CertSummary
  • func SummarizeX5C(v *cbor.Value) ([]CertSummary, error)
• type ClientData
  • func ParseClientData(raw []byte) (*ClientData, error)
  • func (cd *ClientData) OriginMatchesRPID(rpID string) bool
• type Flags
  • func (f Flags) Explain() []string
  • func (f Flags) Names() []string
• type SafetyNetJWS
  • func ParseSafetyNetJWS(raw []byte) (*SafetyNetJWS, error)
• type Statement

Functions

func AAGUIDName

func AAGUIDName(b []byte) string

AAGUIDName looks up a friendly name for an AAGUID. The all-zero AAGUID is special: authenticators send it when attestation is anonymized, so it identifies a privacy decision rather than a device.

func FormatAAGUID

func FormatAAGUID(b []byte) string

FormatAAGUID renders 16 bytes in canonical 8-4-4-4-12 UUID form.

Types

type Attestation

type Attestation struct {
	Length    int                `json:"length"`
	Format    string             `json:"format"`
	AuthData  *AuthenticatorData `json:"auth_data"`
	Statement *Statement         `json:"statement"`
}

Attestation is a decoded attestationObject.

func ParseAttestationObject

func ParseAttestationObject(raw []byte) (*Attestation, error)

ParseAttestationObject decodes a raw attestationObject blob.

type AttestedCredential

type AttestedCredential struct {
	AAGUID       hexval.Hex `json:"aaguid"`
	AAGUIDName   string     `json:"aaguid_name,omitempty"`
	CredentialID hexval.Hex `json:"credential_id"`
	PublicKey    *cose.Key  `json:"public_key"`
}

AttestedCredential is the attested credential data block that follows the header when the AT flag is set.

type AuthenticatorData

type AuthenticatorData struct {
	Length     int                 `json:"length"`
	RPIDHash   hexval.Hex          `json:"rp_id_hash"`
	Flags      Flags               `json:"flags"`
	SignCount  uint32              `json:"sign_count"`
	Credential *AttestedCredential `json:"attested_credential,omitempty"`

	// ExtensionsDiag is the CTAP2 extensions map in diagnostic notation;
	// Extensions keeps the decoded value for structured inspection.
	ExtensionsDiag string      `json:"extensions_diag,omitempty"`
	Extensions     *cbor.Value `json:"-"`

	// Notes explain well-known extension values; Warnings flag problems.
	Notes    []string `json:"notes,omitempty"`
	Warnings []string `json:"warnings,omitempty"`
}

AuthenticatorData is a fully parsed authenticator data blob.

func ParseAuthenticatorData

func ParseAuthenticatorData(raw []byte) (*AuthenticatorData, error)

ParseAuthenticatorData decodes raw authenticator data bytes.

func (*AuthenticatorData) CheckRPID

func (ad *AuthenticatorData) CheckRPID(rpID string) bool

CheckRPID hashes a candidate RP ID and compares it to rpIdHash. This is the single most common ceremony failure: the server's expected RP ID and the browser origin disagree, and every hash beyond that point mismatches.

type CertSummary

type CertSummary struct {
	Subject    string     `json:"subject"`
	Issuer     string     `json:"issuer"`
	Serial     string     `json:"serial"`
	NotBefore  string     `json:"not_before"`
	NotAfter   string     `json:"not_after"`
	IsCA       bool       `json:"is_ca"`
	SelfSigned bool       `json:"self_signed"`
	KeyAlgo    string     `json:"key_algo"`
	SHA256     hexval.Hex `json:"sha256"`
	AAGUID     hexval.Hex `json:"aaguid,omitempty"` // from id-fido-gen-ce-aaguid, if present
	ParseError string     `json:"parse_error,omitempty"`
}

CertSummary is one certificate of an x5c chain, leaf first.

func SummarizeX5C

func SummarizeX5C(v *cbor.Value) ([]CertSummary, error)

SummarizeX5C summarizes an attStmt x5c array (leaf first per WebAuthn). A certificate that fails to parse becomes an entry with ParseError set, so one rotten cert does not hide the rest of the chain.

type ClientData

type ClientData struct {
	Length       int        `json:"length"`
	Type         string     `json:"type"`
	ChallengeRaw string     `json:"challenge"`
	Challenge    hexval.Hex `json:"challenge_bytes,omitempty"`
	Origin       string     `json:"origin"`
	CrossOrigin  *bool      `json:"cross_origin,omitempty"`
	TopOrigin    string     `json:"top_origin,omitempty"`

	// ExtraKeys lists fields beyond the specified ones. Clients are allowed
	// to add fields, and servers must tolerate them — worth seeing.
	ExtraKeys []string `json:"extra_keys,omitempty"`
	Warnings  []string `json:"warnings,omitempty"`
}

ClientData is a decoded clientDataJSON.

func ParseClientData

func ParseClientData(raw []byte) (*ClientData, error)

ParseClientData decodes clientDataJSON bytes.

func (*ClientData) OriginMatchesRPID

func (cd *ClientData) OriginMatchesRPID(rpID string) bool

OriginMatchesRPID reports whether the origin's host equals the RP ID or is a subdomain of it — the "registrable suffix" rule that decides whether the browser would even have accepted this RP ID.

type Flags

type Flags struct {
	Raw  byte `json:"raw"`
	UP   bool `json:"up"`   // bit 0: user present
	RFU1 bool `json:"rfu1"` // bit 1: reserved
	UV   bool `json:"uv"`   // bit 2: user verified
	BE   bool `json:"be"`   // bit 3: backup eligible (passkey syncable)
	BS   bool `json:"bs"`   // bit 4: backup state (currently backed up)
	RFU2 bool `json:"rfu2"` // bit 5: reserved
	AT   bool `json:"at"`   // bit 6: attested credential data included
	ED   bool `json:"ed"`   // bit 7: extension data included
}

Flags is the decoded authenticator-data flags byte.

func (Flags) Explain

func (f Flags) Explain() []string

Explain returns a sentence-fragment description of the set flags.

func (Flags) Names

func (f Flags) Names() []string

Names returns the set flags as their spec abbreviations, in bit order.

type SafetyNetJWS

type SafetyNetJWS struct {
	HeaderAlg       string `json:"header_alg"`
	CertCount       int    `json:"cert_count"`
	Nonce           string `json:"nonce,omitempty"`
	TimestampMs     int64  `json:"timestamp_ms,omitempty"`
	APKPackageName  string `json:"apk_package_name,omitempty"`
	CTSProfileMatch *bool  `json:"cts_profile_match,omitempty"`
	BasicIntegrity  *bool  `json:"basic_integrity,omitempty"`
}

SafetyNetJWS is the decoded (not verified) SafetyNet attestation JWS.

func ParseSafetyNetJWS

func ParseSafetyNetJWS(raw []byte) (*SafetyNetJWS, error)

ParseSafetyNetJWS splits and decodes a compact JWS.

type Statement

type Statement struct {
	Alg     *int64        `json:"alg,omitempty"`
	AlgName string        `json:"alg_name,omitempty"`
	Sig     hexval.Hex    `json:"sig,omitempty"`
	X5C     []CertSummary `json:"x5c,omitempty"`

	// android-safetynet only.
	Ver string        `json:"ver,omitempty"`
	JWS *SafetyNetJWS `json:"jws,omitempty"`

	// tpm only: sizes of the sub-structures v0.1.0 does not yet decode.
	CertInfoLen int `json:"cert_info_len,omitempty"`
	PubAreaLen  int `json:"pub_area_len,omitempty"`

	// Notes explain what the statement means; Warnings flag problems.
	Notes    []string `json:"notes,omitempty"`
	Warnings []string `json:"warnings,omitempty"`

	// RawDiag is the full attStmt in diagnostic notation.
	RawDiag string `json:"raw_diag"`
}

Statement is the format-specific attestation statement, normalized to the fields the registered formats share. Raw diagnostic notation is kept so unknown formats still show everything.