webauthn

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 10, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package webauthn implements the server-side (relying party) parts of WebAuthn used for passkey registration and authentication: ceremony option types, credential wire-format parsing (see the transport subpackage), CBOR attestation-object and authenticator-data parsing with COSE credential-key extraction, and ceremony validation.

Attestation statements are not verified; the package is intended for relying parties that request attestation "none".

Index

Constants

View Source
const (
	FlagUserPresent            byte = 0x01
	FlagUserVerified           byte = 0x04
	FlagBackupEligible         byte = 0x08
	FlagBackedUp               byte = 0x10
	FlagAttestedCredentialData byte = 0x40
	FlagExtensionData          byte = 0x80
)

Authenticator data flag bits (WebAuthn §6.1).

View Source
const (
	WebauthnCreateType     = "webauthn.create"
	WebauthnGetType        = "webauthn.get"
	ExpectedCredentialType = "public-key"
)

Variables

The classification lists group validation errors that are caused by bad client input, for mapping to Bad Request responses.

Functions

func NewVerifier

func NewVerifier(
	algorithm cose.Algorithm,
	publicKey crypto.PublicKey,
) (motmedelCryptoInterfaces.Verifier, error)

NewVerifier returns a verifier for WebAuthn assertion signatures produced with the given COSE algorithm and credential public key. ECDSA signatures are expected in the ASN.1 DER encoding WebAuthn uses (not the raw encoding of COSE signatures).

func ValidateAssertionPublicKeyCredential

func ValidateAssertionPublicKeyCredential(
	credential *AssertionPublicKeyCredential,
	rawClientDataJson []byte,
	rawAuthenticatorData []byte,
	expectedCollectedClientDataChallenge []byte,
	expectedCollectedClientDataOrigin string,
	expectedRpId string,
	previousSignatureCount uint32,
	verifier motmedelCryptoInterfaces.Verifier,
) error

ValidateAssertionPublicKeyCredential validates an authentication ceremony's credential, including its signature over the raw authenticator data and client data hash.

func ValidateAttestationPublicKeyCredential

func ValidateAttestationPublicKeyCredential(
	credential *AttestationPublicKeyCredential,
	expectedCollectedClientDataChallenge []byte,
	expectedCollectedClientDataOrigin string,
	expectedRpId string,
	allowedPublicKeyAlgorithms []cose.Algorithm,
) error

ValidateAttestationPublicKeyCredential validates a registration ceremony's credential. The allowed algorithms are checked against the alg parameter of the COSE credential public key in the attestation object's authenticator data.

TODO: Verify attestation statements (packed, tpm, android-key, apple, …) against their formats' verification procedures instead of accepting any statement unverified; until then, only relying parties requesting attestation "none" are properly supported.

func ValidateAuthenticatorData

func ValidateAuthenticatorData(
	authenticatorData *AuthenticatorData,
	expectedRpId string,
	previousSignatureCount uint32,
	validateAttestedCredential bool,
	verifyUser bool,
) error

ValidateAuthenticatorData validates authenticator data against the expected relying party id, signature count, and flag requirements.

func ValidateCollectedClientData

func ValidateCollectedClientData(
	clientData *CollectedClientData,
	expectedType string,
	expectedChallenge []byte,
	expectedOrigin string,
) error

ValidateCollectedClientData validates the client data of a ceremony against the expected type, challenge, and origin.

Types

type AttestationObject

type AttestationObject struct {
	Format               string
	AttestationStatement map[any]any
	AuthenticatorData    *AuthenticatorData
	RawAuthenticatorData []byte
}

AttestationObject is a parsed attestation object (WebAuthn §6.5.4). The attestation statement is kept as decoded CBOR without being verified.

func ParseAttestationObject

func ParseAttestationObject(data []byte) (*AttestationObject, error)

ParseAttestationObject parses a CBOR-encoded attestation object and the authenticator data within it.

type AttestedCredentialData

type AttestedCredentialData struct {
	Aaguid       []byte
	CredentialId []byte
	// PublicKey is the parsed COSE credential public key.
	PublicKey crypto.PublicKey
	// PublicKeyAlgorithm is the alg parameter of the COSE credential public key, or 0 when the
	// key carries none.
	PublicKeyAlgorithm cose.Algorithm
	// RawPublicKey is the CBOR-encoded COSE_Key exactly as carried in the authenticator data.
	RawPublicKey []byte
}

AttestedCredentialData is the attested credential data of a registration ceremony's authenticator data (WebAuthn §6.5.1).

type AuthenticatorAssertionResponse

type AuthenticatorAssertionResponse struct {
	ClientDataJson    CollectedClientData
	AuthenticatorData AuthenticatorData
	Signature         []byte
	UserHandle        []byte
}

AuthenticatorAssertionResponse is an authenticator's response to an authentication ceremony (WebAuthn §5.2.2).

func (AuthenticatorAssertionResponse) GetAuthenticatorData

func (a AuthenticatorAssertionResponse) GetAuthenticatorData() *AuthenticatorData

func (AuthenticatorAssertionResponse) GetClientDataJson

func (a AuthenticatorAssertionResponse) GetClientDataJson() *CollectedClientData

type AuthenticatorAttestationResponse

type AuthenticatorAttestationResponse struct {
	ClientDataJson    CollectedClientData
	AttestationObject *AttestationObject
	Transports        []string
}

AuthenticatorAttestationResponse is an authenticator's response to a registration ceremony (WebAuthn §5.2.1). The authenticator data is the one embedded in the attestation object.

func (AuthenticatorAttestationResponse) GetAuthenticatorData

func (a AuthenticatorAttestationResponse) GetAuthenticatorData() *AuthenticatorData

func (AuthenticatorAttestationResponse) GetClientDataJson

type AuthenticatorData

type AuthenticatorData struct {
	RpIdHash           []byte
	Flags              byte
	SignCount          uint32
	AttestedCredential *AttestedCredentialData
	Extensions         map[any]any
}

AuthenticatorData is parsed authenticator data (WebAuthn §6.1).

func ParseAuthenticatorData

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

ParseAuthenticatorData parses the binary authenticator data format. The embedded COSE credential public key is delimited by CBOR decoding, separating it from any extension data that follows it.

func (*AuthenticatorData) UserPresent

func (a *AuthenticatorData) UserPresent() bool

func (*AuthenticatorData) UserVerified

func (a *AuthenticatorData) UserVerified() bool

type AuthenticatorResponse

type AuthenticatorResponse interface {
	GetClientDataJson() *CollectedClientData
	GetAuthenticatorData() *AuthenticatorData
}

AuthenticatorResponse is implemented by both authenticator response types.

type AuthenticatorSelection

type AuthenticatorSelection struct {
	AuthenticatorAttachment string `json:"authenticatorAttachment,omitzero"`
	ResidentKey             string `json:"residentKey,omitzero"`
	RequireResidentKey      bool   `json:"requireResidentKey,omitzero"`
}

AuthenticatorSelection restricts which authenticators may take part in a registration ceremony (WebAuthn §5.4.4).

func (*AuthenticatorSelection) MarshalJSON

func (a *AuthenticatorSelection) MarshalJSON() ([]byte, error)

type CollectedClientData

type CollectedClientData struct {
	Type        string
	Challenge   []byte
	Origin      string
	CrossOrigin bool
	// TopOrigin is not part of the specification, but is sent by clients.
	TopOrigin string
}

CollectedClientData is the parsed client data of a ceremony (WebAuthn §5.8.1).

type PublicKeyCredential

type PublicKeyCredential[T AuthenticatorAttestationResponse | AuthenticatorAssertionResponse] struct {
	Id              []byte
	Type            string
	RawId           []byte
	Response        T
	ClientExtension map[string]any
}

PublicKeyCredential is a parsed credential from a navigator.credentials call (WebAuthn §5.1).

type PublicKeyCredentialCreationOptions

type PublicKeyCredentialCreationOptions struct {
	RelyingParty *RelyingParty                  `json:"rp"`
	User         *PublicKeyCredentialUserEntity `json:"user"`

	Challenge        []byte                      `json:"challenge"`
	PubKeyCredParams []*PublicKeyCredentialParam `json:"pubKeyCredParams"`

	Timeout                uint64                           `json:"timeout,omitzero"`
	ExcludeCredentials     []*PublicKeyCredentialDescriptor `json:"excludeCredentials,omitzero"`
	AuthenticatorSelection *AuthenticatorSelection          `json:"authenticatorSelection,omitzero"`
	Attestation            string                           `json:"attestation,omitzero"`
	Extensions             map[string]any                   `json:"extensions,omitzero"`
}

PublicKeyCredentialCreationOptions are the options of a registration ceremony (WebAuthn §5.4).

type PublicKeyCredentialDescriptor

type PublicKeyCredentialDescriptor struct {
	Id         string   `json:"id"`
	Type       string   `json:"type"`
	Transports []string `json:"transports,omitzero"`
}

PublicKeyCredentialDescriptor identifies an existing credential (WebAuthn §5.8.3).

type PublicKeyCredentialParam

type PublicKeyCredentialParam struct {
	Type string `json:"type"`
	Alg  int    `json:"alg"`
}

PublicKeyCredentialParam expresses an accepted credential type and COSE algorithm (WebAuthn §5.3).

type PublicKeyCredentialRequestOptions

type PublicKeyCredentialRequestOptions struct {
	Challenge          []byte                           `json:"challenge"`
	Timeout            uint64                           `json:"timeout,omitzero"`
	RpId               string                           `json:"rpId,omitzero"`
	AllowedCredentials []*PublicKeyCredentialDescriptor `json:"allowedCredentials,omitzero"`
	UserVerification   string                           `json:"userVerification,omitzero"`
	Extensions         map[string]any                   `json:"extensions,omitzero"`
}

PublicKeyCredentialRequestOptions are the options of an authentication ceremony (WebAuthn §5.5).

type PublicKeyCredentialUserEntity

type PublicKeyCredentialUserEntity struct {
	Name        string `json:"name"`
	Id          []byte `json:"id"`
	DisplayName string `json:"displayName"`
}

PublicKeyCredentialUserEntity identifies the user account a credential is registered to (WebAuthn §5.4.3).

type RelyingParty

type RelyingParty struct {
	Name string `json:"name"`
	Id   string `json:"id,omitzero"`
}

RelyingParty identifies the relying party in creation options (WebAuthn §5.4.2).

Directories

Path Synopsis
Package transport contains the JSON wire-format counterparts of the webauthn package's domain types, with base64url-encoded binary fields, and the conversions from wire format to parsed domain values.
Package transport contains the JSON wire-format counterparts of the webauthn package's domain types, with base64url-encoded binary fields, and the conversions from wire format to parsed domain values.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL