protocol

type AllAcceptedCredentialsUser ¶ added in v0.16.0

type AllAcceptedCredentialsUser interface {
	WebAuthnID() []byte
	WebAuthnCredentialIDs() [][]byte
}

AllAcceptedCredentialsUser is an interface that can be implemented by a user to provide information about their accepted credentials.

type AndroidKeyAuthorizationScope ¶ added in v0.18.0

type AndroidKeyAuthorizationScope int

AndroidKeyAuthorizationScope selects the authorization lists of the Android key attestation certificate extension which the §8.4 origin and purpose requirements are evaluated against.

§8.4 assigns this choice to the Relying Party: "For the following, use only the teeEnforced authorization list if the RP wants to accept only keys from a trusted execution environment, otherwise use the union of teeEnforced and softwareEnforced."

Specification: §8.4. Android Key Attestation Statement Format (https://www.w3.org/TR/webauthn/#sctn-android-key-attestation)

const (
	// AndroidKeyAuthorizationScopeDefault is the zero value of [AndroidKeyAuthorizationScope] and has no matching
	// rule in §8.4. It evaluates as [AndroidKeyAuthorizationScopeTEEEnforced] wherever it is used. webauthn.Config
	// rewrites it to that explicit constant during validation, so a Relying Party can tell an unset field apart
	// from a deliberate choice of the same scope.
	AndroidKeyAuthorizationScopeDefault AndroidKeyAuthorizationScope = iota

	// AndroidKeyAuthorizationScopeTEEEnforced evaluates the origin and purpose requirements against the teeEnforced
	// authorization list alone, accepting only keys generated within a trusted execution environment.
	AndroidKeyAuthorizationScopeTEEEnforced

	// AndroidKeyAuthorizationScopeUnion evaluates the origin and purpose requirements against the union of the
	// teeEnforced and softwareEnforced authorization lists, which additionally accepts software backed keys.
	AndroidKeyAuthorizationScopeUnion
)

type AndroidKeyPolicy ¶ added in v0.18.0

type AndroidKeyPolicy struct {
	// AuthorizationScope selects the authorization lists of the attestation certificate extension which the origin
	// and purpose requirements are evaluated against.
	AuthorizationScope AndroidKeyAuthorizationScope
}

AndroidKeyPolicy configures the Android Key Attestation Statement Format verification procedure.

Specification: §8.4. Android Key Attestation Statement Format (https://www.w3.org/TR/webauthn/#sctn-android-key-attestation)

type AppleAnonymousAttestation ¶

type AppleAnonymousAttestation struct {
	Nonce []byte `asn1:"tag:1,explicit"`
}

AppleAnonymousAttestation represents the attestation format for Apple, who have not yet published a schema for the extension (as of JULY 2021.)

type AttestationFormat ¶ added in v0.11.0

type AttestationFormat string

AttestationFormat is an internal representation of the relevant inputs for registration.

Specification: §5.4 Options for Credential Creation (https://w3c.github.io/webauthn/#dom-publickeycredentialcreationoptions-attestationformats) Registry: https://www.iana.org/assignments/webauthn/webauthn.xhtml

const (
	// AttestationFormatPacked is the "packed" attestation statement format is a WebAuthn-optimized format for
	// attestation. It uses a very compact but still extensible encoding method. This format is implementable by
	// authenticators with limited resources (i.e., secure elements).
	AttestationFormatPacked AttestationFormat = "packed"

	// AttestationFormatTPM is the TPM attestation statement format returns an attestation statement in the same format
	// as the packed attestation statement format, although the rawData and signature fields are computed differently.
	AttestationFormatTPM AttestationFormat = "tpm"

	// AttestationFormatAndroidKey is the attestation statement format for platform authenticators on versions "N", and
	// later, which may provide this proprietary "hardware attestation" statement.
	AttestationFormatAndroidKey AttestationFormat = "android-key"

	// AttestationFormatAndroidSafetyNet is the attestation statement format that Android-based platform authenticators
	// MAY produce an attestation statement based on the Android SafetyNet API.
	AttestationFormatAndroidSafetyNet AttestationFormat = "android-safetynet"

	// AttestationFormatFIDOUniversalSecondFactor is the attestation statement format that is used with FIDO U2F
	// authenticators.
	AttestationFormatFIDOUniversalSecondFactor AttestationFormat = "fido-u2f"

	// AttestationFormatApple is the attestation statement format that is used with Apple devices' platform
	// authenticators.
	AttestationFormatApple AttestationFormat = "apple"

	// AttestationFormatCompound is used to pass multiple, self-contained attestation statements in a single ceremony.
	AttestationFormatCompound AttestationFormat = "compound"

	// AttestationFormatNone is the attestation statement format that is used to replace any authenticator-provided
	// attestation statement when a WebAuthn Relying Party indicates it does not wish to receive attestation information.
	AttestationFormatNone AttestationFormat = none
)

type AttestationObject ¶

type AttestationObject struct {
	// The authenticator data, including the newly created public key. See [AuthenticatorData] for more info.
	AuthData AuthenticatorData

	// The byteform version of the authenticator data, used in part for signature validation.
	RawAuthData []byte `json:"authData"`

	// The format of the Attestation data.
	Format string `json:"fmt"`

	// The attestation statement data sent back if attestation is requested.
	AttStatement map[string]any `json:"attStmt,omitempty"`

	// SubStatements holds the sub-statements of a compound attestation statement, which §8.9 encodes as an array
	// rather than as the map every other format uses for its attestation statement. It is populated by
	// [AttestationObject.UnmarshalCBOR] when, and only when, Format is "compound", and for such an attestation
	// AttStatement is empty because the wire format carries no map to put there.
	//
	// Specification: §8.9. Compound Attestation Statement Format (https://www.w3.org/TR/webauthn-3/#sctn-compound-attestation)
	SubStatements []NonCompoundAttestationObject `json:"-"`

	// Type is the attestation type as conveyed by the authenticator, one of the values defined by
	// [metadata.AuthenticatorAttestationType] (i.e. "basic_full", "basic_surrogate", "attca", "anonca", "none").
	// It is populated as a side-effect of a successful [AttestationObject.VerifyAttestation]; before that the field
	// is empty. This field is excluded from serialization because the attestation object wire format does not carry
	// this value; it is derived by the format-specific verifier.
	Type string `json:"-"`
}

AttestationObject is the raw attestationObject.

Authenticators SHOULD also provide some form of attestation, if possible. If an authenticator does, the basic requirement is that the authenticator can produce, for each credential public key, an attestation statement verifiable by the WebAuthn Relying Party. Typically, this attestation statement contains a signature by an attestation private key over the attested credential public key and a challenge, as well as a certificate or similar data providing provenance information for the attestation public key, enabling the Relying Party to make a trust decision. However, if an attestation key pair is not available, then the authenticator MAY either perform self attestation of the credential public key with the corresponding credential private key, or otherwise perform no attestation. All this information is returned by authenticators any time a new public key credential is generated, in the overall form of an attestation object.

Specification: §6.5. Attestation (https://www.w3.org/TR/webauthn/#sctn-attestation)

func (a *AttestationObject) UnmarshalCBOR(data []byte) (err error)

func (a *AttestationObject) Verify(relyingPartyID string, clientDataHash []byte, userVerificationRequired bool, userPresenceRequired bool, mds metadata.Provider, credParams []CredentialParameter, policy AttestationPolicy, signature SignaturePolicy) (err error)

func (a *AttestationObject) VerifyAttestation(clientDataHash []byte, mds metadata.Provider, policy AttestationPolicy, signature SignaturePolicy) (err error)

type AttestationPolicy ¶ added in v0.18.0

type AttestationPolicy struct {
	// AndroidKey configures the Android Key Attestation Statement Format verification procedure.
	AndroidKey AndroidKeyPolicy

	// Compound configures the Compound Attestation Statement Format verification procedure.
	Compound CompoundPolicy
}

AttestationPolicy carries the Relying Party policy decisions which §8 of the specification delegates to the Relying Party rather than fixing. The zero value selects the most restrictive behavior available for each policy it carries.

type AttestedCredentialData ¶

type AttestedCredentialData struct {
	// AAGUID is the 16-byte Authenticator Attestation GUID, a unique identifier indicating the type of the
	// authenticator (i.e. make and model).
	AAGUID []byte `json:"aaguid"`

	// CredentialID is the credential identifier whose length is prepended as a 16-bit unsigned big-endian integer.
	CredentialID []byte `json:"credential_id"`

	// CredentialPublicKey is the CBOR-encoded credential public key using the COSE_Key format defined in
	// Section 7 of [RFC9052].
	CredentialPublicKey []byte `json:"public_key"`
}

AttestedCredentialData is a variable-length byte array added to the authenticator data when generating an attestation object for a credential.

Specification: §6.5.2. Attested Credential Data (https://www.w3.org/TR/webauthn/#sctn-attested-credential-data)

type AuthenticationExtensions ¶

type AuthenticationExtensions struct {
	// AppID is the FIDO AppID Extension input. Authentication only.
	AppID string `json:"appid,omitempty"`

	// AppIDExclude is the FIDO AppID Exclusion Extension input. Registration only.
	AppIDExclude string `json:"appidExclude,omitempty"`

	// CredProps requests the Credential Properties Extension. Registration only.
	CredProps bool `json:"credProps,omitempty"`

	// PRF is the Pseudo-random function Extension input. It is a pointer because an empty dictionary is a
	// meaningful input for this extension and only this extension: a Relying Party sends "prf":{} at registration
	// to ask whether the pseudo-random function is available for the credential being created, and the client
	// answers with the 'enabled' output. A value type combined with omitzero cannot express the difference between
	// an absent member and a member present but empty, so a non-nil pointer to a zero value is what carries the
	// bare availability probe.
	PRF *PRFInputs `json:"prf,omitempty"`

	// LargeBlob is the Large blob storage Extension input.
	LargeBlob LargeBlobInputs `json:"largeBlob,omitzero"`

	// RemoteClientDataJSON is the Remote Client Data JSON Extension input. This member is set by a remote desktop
	// web client and a Relying Party should not normally set it. See [ExtensionRemoteClientDataJSON], which records
	// that this extension is not yet ratified.
	RemoteClientDataJSON string `json:"remoteClientDataJSON,omitempty"`

	// CredentialProtectionPolicy is the CTAP credProtect policy. Registration only.
	CredentialProtectionPolicy CredentialProtectionPolicy `json:"credentialProtectionPolicy,omitempty"`

	// EnforceCredentialProtectionPolicy requires the credProtect policy is honoured. Registration only.
	EnforceCredentialProtectionPolicy bool `json:"enforceCredentialProtectionPolicy,omitempty"`

	// MinPinLength requests the authenticator minimum PIN length. Registration only.
	MinPinLength bool `json:"minPinLength,omitempty"`

	// CredBlob is the blob to store with the credential. Registration only.
	CredBlob URLEncodedBase64 `json:"credBlob,omitempty"`

	// GetCredBlob requests the blob stored with the credential. Authentication only.
	GetCredBlob bool `json:"getCredBlob,omitempty"`

	// HMACCreateSecret requests provisioning of the CTAP hmac-secret. Registration only.
	HMACCreateSecret bool `json:"hmacCreateSecret,omitempty"`

	// HMACGetSecret requests evaluation of the CTAP hmac-secret. Authentication only.
	HMACGetSecret HMACGetSecretInputs `json:"hmacGetSecret,omitzero"`

	// UVM requests the user verification methods used for the operation.
	UVM bool `json:"uvm,omitempty"`

	// Extra carries extension inputs this library does not model. Entries are merged into the top-level object
	// when marshalling and unrecognised members are collected here when unmarshalling. An entry whose key matches
	// a modelled extension is an error, as the intent would be ambiguous.
	Extra map[string]any `json:"-"`
}

AuthenticationExtensions represents the AuthenticationExtensionsClientInputs IDL. It contains additional parameters requesting additional processing by the client and authenticator.

Members are marshalled in the AuthenticationExtensionsClientInputsJSON form, i.e. buffer sources are base64url encoded strings, which is the form consumed by PublicKeyCredential.parseCreationOptionsFromJSON().

A JSON member whose key matches a modelled name only by case (e.g. "CredProps" for "credProps") is bound to that modelled field, not collected into AuthenticationExtensions.Extra: encoding/json resolves the case-insensitive match during the first decoding pass, before UnmarshalJSON ever sees the untyped member map. If such a member's value has the wrong type for the modelled field, unmarshalling fails outright rather than falling back to Extra. encoding/json (v1, the only version this module may use) offers no way to defer that binding.

Specification: §5.7.1. Authentication Extensions Client Inputs (https://www.w3.org/TR/webauthn-3/#iface-authentication-extensions-client-inputs)

Specification: §10.1. Client Extensions (https://www.w3.org/TR/webauthn-3/#sctn-defined-client-extensions)

func ParseAuthenticationExtensions(in map[string]any) (out AuthenticationExtensions, err error)

func (e AuthenticationExtensions) IsZero() bool

func (e AuthenticationExtensions) Map() (out map[string]any, err error)

func (e AuthenticationExtensions) MarshalJSON() (data []byte, err error)

func (e AuthenticationExtensions) Requested() (names []string)

func (e AuthenticationExtensions) Session() SessionExtensions

func (e *AuthenticationExtensions) UnmarshalJSON(data []byte) (err error)

func (e AuthenticationExtensions) Validate(c CeremonyType) (err error)

type AuthenticationExtensionsClientOutputs ¶

type AuthenticationExtensionsClientOutputs struct {
	// AppID indicates the FIDO AppID Extension was acted upon.
	AppID *bool `json:"appid,omitempty"`

	// AppIDExclude indicates the FIDO AppID Exclusion Extension was acted upon.
	AppIDExclude *bool `json:"appidExclude,omitempty"`

	// CredProps reports the properties of a newly created credential.
	CredProps *CredentialPropertiesOutput `json:"credProps,omitempty"`

	// PRF reports the availability and results of the pseudo-random function extension.
	PRF *PRFOutputs `json:"prf,omitempty"`

	// LargeBlob reports large blob support at registration, or the read or written blob at authentication.
	LargeBlob *LargeBlobOutputs `json:"largeBlob,omitempty"`

	// RemoteClientDataJSON indicates the Remote Client Data JSON Extension was acted upon, which means the local
	// client delegated every Relying Party ID and origin check to a remote host. See
	// [ExtensionRemoteClientDataJSON], which records that this extension is not yet ratified.
	RemoteClientDataJSON *bool `json:"remoteClientDataJSON,omitempty"`

	// HMACCreateSecret indicates the CTAP hmac-secret was provisioned at registration.
	HMACCreateSecret *bool `json:"hmacCreateSecret,omitempty"`

	// HMACGetSecret reports the CTAP hmac-secret evaluation results.
	HMACGetSecret *HMACGetSecretOutputs `json:"hmacGetSecret,omitempty"`

	// Extra carries extension outputs this library does not model.
	Extra map[string]any `json:"-"`
	// contains filtered or unexported fields
}

AuthenticationExtensionsClientOutputs represents the AuthenticationExtensionsClientOutputs IDL, returned by the client after a create() or get() call.

Every modelled member is a pointer so an absent value is distinguishable from a false or empty one; the unsolicited output check performed by AuthenticationExtensionsClientOutputs.Verify depends on that distinction.

A JSON member whose key matches a modelled name only by case (e.g. "AppID" for "appid") is bound to that modelled field, not collected into AuthenticationExtensionsClientOutputs.Extra: encoding/json resolves the case-insensitive match during the first decoding pass, before UnmarshalJSON ever sees the untyped member map. If such a member's value has the wrong type for the modelled field, unmarshalling fails outright rather than falling back to Extra. encoding/json (v1, the only version this module may use) offers no way to defer that binding.

Specification: §5.9. Authentication Extensions Client Outputs (https://www.w3.org/TR/webauthn-3/#iface-authentication-extensions-client-outputs)

func (o AuthenticationExtensionsClientOutputs) IsZero() bool

func (o AuthenticationExtensionsClientOutputs) Map() (out map[string]any, err error)

func (o AuthenticationExtensionsClientOutputs) MarshalJSON() (data []byte, err error)

func (o AuthenticationExtensionsClientOutputs) Present() (names []string)

func (o *AuthenticationExtensionsClientOutputs) UnmarshalJSON(data []byte) (err error)

func (o AuthenticationExtensionsClientOutputs) Verify(session SessionExtensions, ceremony CeremonyType, policy UnsolicitedOutputPolicy) error

type AuthenticatorAssertionResponse ¶

type AuthenticatorAssertionResponse struct {
	AuthenticatorResponse

	AuthenticatorData URLEncodedBase64 `json:"authenticatorData"`
	Signature         URLEncodedBase64 `json:"signature"`
	UserHandle        URLEncodedBase64 `json:"userHandle,omitempty"`
}

The AuthenticatorAssertionResponse contains the raw authenticator assertion data and is parsed into ParsedAssertionResponse.

type AuthenticatorAttachment ¶

type AuthenticatorAttachment string

AuthenticatorAttachment represents the IDL enum of the same name, and is used as part of the Authenticator Selection Criteria.

This enumeration’s values describe authenticators' attachment modalities. Relying Parties use this to express a preferred authenticator attachment modality when calling navigator.credentials.create() to create a credential.

If this member is present, eligible authenticators are filtered to only authenticators attached with the specified §5.4.5 Authenticator Attachment Enumeration (enum AuthenticatorAttachment). The value SHOULD be a member of AuthenticatorAttachment but client platforms MUST ignore unknown values, treating an unknown value as if the member does not exist.

Specification: §5.4.4. Authenticator Selection Criteria (https://www.w3.org/TR/webauthn/#dom-authenticatorselectioncriteria-authenticatorattachment)

Specification: §5.4.5. Authenticator Attachment Enumeration (https://www.w3.org/TR/webauthn/#enum-attachment)

const (
	// Platform represents a platform authenticator is attached using a client device-specific transport, called
	// platform attachment, and is usually not removable from the client device. A public key credential bound to a
	// platform authenticator is called a platform credential.
	Platform AuthenticatorAttachment = "platform"

	// CrossPlatform represents a roaming authenticator is attached using cross-platform transports, called
	// cross-platform attachment. Authenticators of this class are removable from, and can "roam" among, client devices.
	// A public key credential bound to a roaming authenticator is called a roaming credential.
	CrossPlatform AuthenticatorAttachment = "cross-platform"
)

type AuthenticatorAttestationResponse ¶

type AuthenticatorAttestationResponse struct {
	// The byte slice of clientDataJSON, which becomes CollectedClientData.
	AuthenticatorResponse

	Transports []string `json:"transports,omitempty"`

	AuthenticatorData URLEncodedBase64 `json:"authenticatorData"`

	PublicKey URLEncodedBase64 `json:"publicKey"`

	PublicKeyAlgorithm int64 `json:"publicKeyAlgorithm"`

	// AttestationObject is the byte slice version of attestationObject.
	// This attribute contains an attestation object, which is opaque to, and
	// cryptographically protected against tampering by, the client. The
	// attestation object contains both authenticator data and an attestation
	// statement. The former contains the AAGUID, a unique credential ID, and
	// the credential public key. The contents of the attestation statement are
	// determined by the attestation statement format used by the authenticator.
	// It also contains any additional information that the Relying Party's server
	// requires to validate the attestation statement, as well as to decode and
	// validate the authenticator data along with the JSON-serialized client data.
	AttestationObject URLEncodedBase64 `json:"attestationObject"`
}

AuthenticatorAttestationResponse is the initial unpacked 'response' object received by the relying party. This contains the clientDataJSON object, which will be marshalled into CollectedClientData, and the 'attestationObject', which contains information about the authenticator, and the newly minted public key credential. The information in both objects are used to verify the authenticity of the ceremony and new credential.

See: https://www.w3.org/TR/webauthn/#typedefdef-publickeycredentialjson

func (ccr *AuthenticatorAttestationResponse) Parse() (p *ParsedAttestationResponse, err error)

type AuthenticatorData ¶

type AuthenticatorData struct {
	RPIDHash []byte                         `json:"rpid"`
	Flags    AuthenticatorFlags             `json:"flags"`
	Counter  uint32                         `json:"sign_count"`
	AttData  AttestedCredentialData         `json:"att_data"`
	ExtData  []byte                         `json:"ext_data"`
	Ext      *AuthenticatorExtensionOutputs `json:"ext,omitempty"`
}

AuthenticatorData represents the IDL with the same name.

The authenticator data structure encodes contextual bindings made by the authenticator. These bindings are controlled by the authenticator itself, and derive their trust from the WebAuthn Relying Party's assessment of the security properties of the authenticator. In one extreme case, the authenticator may be embedded in the client, and its bindings may be no more trustworthy than the client data. At the other extreme, the authenticator may be a discrete entity with high-security hardware and software, connected to the client over a secure channel. In both cases, the Relying Party receives the authenticator data in the same format, and uses its knowledge of the authenticator to make trust decisions.

The authenticator data has a compact but extensible encoding. This is desired since authenticators can be devices with limited capabilities and low power requirements, with much simpler software stacks than the client platform.

Specification: §6.1. Authenticator Data (https://www.w3.org/TR/webauthn/#sctn-authenticator-data)

func (a *AuthenticatorData) Unmarshal(rawAuthData []byte) (err error)

func (a *AuthenticatorData) Verify(rpIdHash []byte, appIDHash []byte, userVerificationRequired bool, userPresenceRequired bool) (err error)

type AuthenticatorExtensionOutputs ¶ added in v0.18.0

type AuthenticatorExtensionOutputs struct {
	// CredProtect is the credential protection policy applied to the credential. Registration only.
	CredProtect *CredentialProtectionPolicy `json:"credProtect,omitempty"`

	// MinPinLength is the authenticator's current minimum PIN length. Registration only.
	MinPinLength *uint `json:"minPinLength,omitempty"`

	// CredBlobSet reports whether the requested blob was stored. Registration only.
	CredBlobSet *bool `json:"-"`

	// CredBlob is the blob stored with the credential. Authentication only.
	CredBlob []byte `json:"credBlob,omitempty"`

	// HMACSecret reports whether the hmac-secret was provisioned. Registration only.
	HMACSecret *bool `json:"-"`

	// HMACSecretOutput is the encrypted hmac-secret output. Authentication only.
	HMACSecretOutput []byte `json:"-"`

	// UVM reports the user verification methods used for the operation.
	UVM []UserVerificationMethod `json:"uvm,omitempty"`

	// Extra carries authenticator extension outputs this library does not model, and the values of modelled
	// extensions that arrived with an unexpected type.
	Extra map[string]any `json:"-"`
}

AuthenticatorExtensionOutputs is the decoded form of the extension outputs carried in the authenticator data. WebAuthn Level 3 defines no authenticator extensions; every member below is defined by CTAP 2.1 or CTAP 2.2 and registered in the IANA "WebAuthn Extension Identifiers" registry.

Specification: §6.1. Authenticator Data (https://www.w3.org/TR/webauthn-3/#sctn-authenticator-data)

Registry: https://www.iana.org/assignments/webauthn/webauthn.xhtml

func ParseAuthenticatorExtensionOutputs(data []byte) (out *AuthenticatorExtensionOutputs, err error)

func (o *AuthenticatorExtensionOutputs) Verify(session SessionExtensions, ceremony CeremonyType) error

type AuthenticatorFlags ¶

type AuthenticatorFlags byte

AuthenticatorFlags A byte of information returned during during ceremonies in the authenticatorData that contains bits that give us information about the whether the user was present and/or verified during authentication, and whether there is attestation or extension data present. Bit 0 is the least significant bit.

Specification: §6.1. Authenticator Data - Flags (https://www.w3.org/TR/webauthn/#flags)

const (
	// FlagUserPresent Bit 00000001 in the byte sequence. Tells us if user is present. Also referred to as the UP flag.
	FlagUserPresent AuthenticatorFlags = 1 << iota // Referred to as UP.

	// FlagRFU1 is a reserved for future use flag.
	FlagRFU1

	// FlagUserVerified Bit 00000100 in the byte sequence. Tells us if user is verified
	// by the authenticator using a biometric or PIN. Also referred to as the UV flag.
	FlagUserVerified

	// FlagBackupEligible Bit 00001000 in the byte sequence. Tells us if a backup is eligible for device. Also referred
	// to as the BE flag.
	FlagBackupEligible // Referred to as BE.

	// FlagBackupState Bit 00010000 in the byte sequence. Tells us if a backup state for device. Also referred to as the
	// BS flag.
	FlagBackupState

	// FlagRFU2 is a reserved for future use flag.
	FlagRFU2

	// FlagAttestedCredentialData Bit 01000000 in the byte sequence. Indicates whether
	// the authenticator added attested credential data. Also referred to as the AT flag.
	FlagAttestedCredentialData

	// FlagHasExtensions Bit 10000000 in the byte sequence. Indicates if the authenticator data has extensions. Also
	// referred to as the ED flag.
	FlagHasExtensions
)

func (flag AuthenticatorFlags) HasAttestedCredentialData() bool

func (flag AuthenticatorFlags) HasBackupEligible() bool

func (flag AuthenticatorFlags) HasBackupState() bool

func (flag AuthenticatorFlags) HasExtensions() bool

func (flag AuthenticatorFlags) HasUserPresent() bool

func (flag AuthenticatorFlags) HasUserVerified() bool

func (flag AuthenticatorFlags) UserPresent() bool

func (flag AuthenticatorFlags) UserVerified() bool

type AuthenticatorResponse ¶

type AuthenticatorResponse struct {
	// From the spec https://www.w3.org/TR/webauthn/#dom-authenticatorresponse-clientdatajson
	// This attribute contains a JSON serialization of the client data passed to the authenticator
	// by the client in its call to either create() or get().
	ClientDataJSON URLEncodedBase64 `json:"clientDataJSON"`
}

AuthenticatorResponse represents the IDL with the same name.

Authenticators respond to Relying Party requests by returning an object derived from the AuthenticatorResponse interface

Specification: §5.2. Authenticator Responses (https://www.w3.org/TR/webauthn/#iface-authenticatorresponse)

type AuthenticatorSelection ¶

type AuthenticatorSelection struct {
	// AuthenticatorAttachment If this member is present, eligible authenticators are filtered to only
	// authenticators attached with the specified AuthenticatorAttachment enum.
	AuthenticatorAttachment AuthenticatorAttachment `json:"authenticatorAttachment,omitempty"`

	// RequireResidentKey this member describes the Relying Party's requirements regarding resident
	// credentials. If the parameter is set to true, the authenticator MUST create a client-side-resident
	// public key credential source when creating a public key credential.
	RequireResidentKey *bool `json:"requireResidentKey,omitempty"`

	// ResidentKey this member describes the Relying Party's requirements regarding resident
	// credentials per Webauthn Level 2.
	ResidentKey ResidentKeyRequirement `json:"residentKey,omitempty"`

	// UserVerification This member describes the Relying Party's requirements regarding user verification for
	// the create() operation. Eligible authenticators are filtered to only those capable of satisfying this
	// requirement.
	UserVerification UserVerificationRequirement `json:"userVerification,omitempty"`
}

AuthenticatorSelection represents the AuthenticatorSelectionCriteria IDL.

WebAuthn Relying Parties may use the AuthenticatorSelectionCriteria dictionary to specify their requirements regarding authenticator attributes.

Specification: §5.4.4. Authenticator Selection Criteria (https://www.w3.org/TR/webauthn/#dictionary-authenticatorSelection)

func (s AuthenticatorSelection) IsZero() bool

type AuthenticatorTransport ¶

type AuthenticatorTransport string

AuthenticatorTransport represents the IDL enum with the same name.

Authenticators may implement various transports for communicating with clients. This enumeration defines hints as to how clients might communicate with a particular authenticator in order to obtain an assertion for a specific credential. Note that these hints represent the WebAuthn Relying Party's best belief as to how an authenticator may be reached. A Relying Party will typically learn of the supported transports for a public key credential via getTransports().

Specification: §5.8.4. Authenticator Transport Enumeration (https://www.w3.org/TR/webauthn/#enumdef-authenticatortransport)

const (
	// USB indicates the respective authenticator can be contacted over removable USB.
	USB AuthenticatorTransport = "usb"

	// NFC indicates the respective authenticator can be contacted over Near Field Communication (NFC).
	NFC AuthenticatorTransport = "nfc"

	// BLE indicates the respective authenticator can be contacted over Bluetooth Smart (Bluetooth Low Energy / BLE).
	BLE AuthenticatorTransport = "ble"

	// SmartCard indicates the respective authenticator can be contacted over ISO/IEC 7816 smart card with contacts.
	//
	// WebAuthn Level 3.
	SmartCard AuthenticatorTransport = "smart-card"

	// Hybrid indicates the respective authenticator can be contacted using a combination of (often separate)
	// data-transport and proximity mechanisms. This supports, for example, authentication on a desktop computer using
	// a smartphone.
	//
	// WebAuthn Level 3.
	Hybrid AuthenticatorTransport = "hybrid"

	// Internal indicates the respective authenticator is contacted using a client device-specific transport, i.e., it
	// is a platform authenticator. These authenticators are not removable from the client device.
	Internal AuthenticatorTransport = "internal"
)

type CeremonyType ¶

type CeremonyType string

CeremonyType represents the type of WebAuthn ceremony being performed.

Specification: §5.8.1. Client Data Used in WebAuthn Signatures (https://www.w3.org/TR/webauthn/#dom-collectedclientdata-type)

const (
	// CreateCeremony is the ceremony type for credential registration ("webauthn.create").
	CreateCeremony CeremonyType = "webauthn.create"

	// AssertCeremony is the ceremony type for authentication assertion ("webauthn.get").
	AssertCeremony CeremonyType = "webauthn.get"
)

type ClientCapabilities ¶ added in v0.18.0

type ClientCapabilities map[ClientCapability]bool

ClientCapabilities represents the record a client returns from PublicKeyCredential.getClientCapabilities(), which maps a capability to whether the client currently supports it.

It is a map rather than a struct so a capability this release does not model, including every extension key, survives a round trip through the Relying Party's own transport rather than being dropped on the way in.

Read it with ClientCapabilities.Supported rather than by indexing. A key which is absent from the record is not the same as a key reported false: the specification allows no assumption about the availability of a feature the client did not mention, and indexing a Go map cannot express that difference.

Specification: §5.1.7. Availability of client capabilities (https://www.w3.org/TR/webauthn-3/#sctn-getClientCapabilities)

func (c ClientCapabilities) Extension(identifier string) (supported, reported bool)

func (c ClientCapabilities) Supported(capability ClientCapability) (supported, reported bool)

type ClientCapability ¶ added in v0.18.0

type ClientCapability string

ClientCapability represents an entry of the ClientCapability enumeration, which names a capability a client may report through PublicKeyCredential.getClientCapabilities(). A Relying Party typically has the client send the result to the server so it can pick a ceremony the client can actually complete, for example offering conditional mediation only where it is available.

The IDL types the keys of the reported record as DOMString rather than as this enumeration, so a value which is not one of the constants below is not an error: a client may report a capability ratified after this release, and it also reports one key per supported extension, named by ExtensionClientCapability. Values are therefore deliberately not validated, which is the same call PublicKeyCredentialHints makes for the same reason.

What a client reports is advisory. It is a statement by software the Relying Party does not control, sent over a channel the Relying Party does not control, so it belongs in flow selection and never in a security decision. The ceremony verification steps are what establish security properties.

WebAuthn Level 3.

Specification: §5.8.7. Client Capability Enumeration (https://www.w3.org/TR/webauthn-3/#enum-clientCapability)

const (
	// ClientCapabilityConditionalCreate indicates the client supports conditionally mediated registration, i.e. a
	// create() call with a mediation of conditional.
	ClientCapabilityConditionalCreate ClientCapability = "conditionalCreate"

	// ClientCapabilityConditionalGet indicates the client supports conditionally mediated authentication, i.e. a
	// get() call with a mediation of conditional, which is what backs autofill of a passkey.
	ClientCapabilityConditionalGet ClientCapability = "conditionalGet"

	// ClientCapabilityHybridTransport indicates the client supports the hybrid transport, i.e. using a nearby
	// device such as a phone as an authenticator.
	ClientCapabilityHybridTransport ClientCapability = "hybridTransport"

	// ClientCapabilityPasskeyPlatformAuthenticator indicates a passkey capable platform authenticator is available,
	// whether attached to the client device or reachable over the hybrid transport.
	ClientCapabilityPasskeyPlatformAuthenticator ClientCapability = "passkeyPlatformAuthenticator"

	// ClientCapabilityUserVerifyingPlatformAuthenticator indicates a user verifying platform authenticator is
	// available on the client device.
	ClientCapabilityUserVerifyingPlatformAuthenticator ClientCapability = "userVerifyingPlatformAuthenticator"

	// ClientCapabilityRelatedOrigins indicates the client supports Related Origin Requests, i.e. that it will read
	// the document a Relying Party serves at [WellKnownPathWebAuthn].
	//
	// Specification: §5.11. Related Origin Requests (https://www.w3.org/TR/webauthn-3/#sctn-related-origins)
	ClientCapabilityRelatedOrigins ClientCapability = "relatedOrigins"

	// ClientCapabilitySignalAllAcceptedCredentials indicates the client supports the
	// signalAllAcceptedCredentials() method.
	ClientCapabilitySignalAllAcceptedCredentials ClientCapability = "signalAllAcceptedCredentials"

	// ClientCapabilitySignalCurrentUserDetails indicates the client supports the signalCurrentUserDetails() method.
	ClientCapabilitySignalCurrentUserDetails ClientCapability = "signalCurrentUserDetails"

	// ClientCapabilitySignalUnknownCredential indicates the client supports the signalUnknownCredential() method.
	ClientCapabilitySignalUnknownCredential ClientCapability = "signalUnknownCredential"
)

func ExtensionClientCapability(identifier string) ClientCapability

func (c ClientCapability) Extension() (identifier string, ok bool)

type CollectedClientData ¶

type CollectedClientData struct {
	// Type contains the string "webauthn.create" when creating new credentials, and "webauthn.get" when getting an
	// assertion from an existing credential. The purpose of this member is to prevent certain types of signature
	// confusion attacks (where an attacker substitutes one legitimate signature for another).
	Type CeremonyType `json:"type"`

	// Challenge contains the base64url encoding of the challenge provided by the Relying Party.
	Challenge string `json:"challenge"`

	// Origin contains the fully qualified origin of the requester, as provided to the authenticator by the client.
	Origin string `json:"origin"`

	// TopOrigin contains the fully qualified top-level origin of the requester when the client is cross-origin.
	// This is only present when CrossOrigin is true.
	//
	// WebAuthn Level 3.
	TopOrigin string `json:"topOrigin,omitempty"`

	// CrossOrigin indicates whether the calling context is an iframe that is not same-origin with its ancestor.
	//
	// WebAuthn Level 3.
	CrossOrigin bool `json:"crossOrigin,omitempty"`

	// TokenBinding contains information about the state of the Token Binding protocol.
	//
	// WebAuthn Level 3 removes this member from the CollectedClientData dictionary. It is retained because a client
	// implementing Level 1 or Level 2 may still include it, and a member present in the client data has to be
	// modelled to be validated; it is not something a Relying Party should expect to receive.
	//
	// Deprecated: removed from the CollectedClientData dictionary by WebAuthn Level 3.
	TokenBinding *TokenBinding `json:"tokenBinding,omitempty"`

	// Hint is an opaque field that may be added by the client. Chromium-based browsers include this field to remind
	// implementers not to perform string comparison on the clientDataJSON.
	Hint string `json:"new_keys_may_be_added_here,omitempty"`
}

CollectedClientData represents the contextual bindings of both the WebAuthn Relying Party and the client. It is a key-value mapping whose keys are strings. Values can be any type that has a valid encoding in JSON. Its structure is defined by the following Web IDL.

Specification: §5.8.1. Client Data Used in WebAuthn Signatures (https://www.w3.org/TR/webauthn/#dictdef-collectedclientdata)

func (c *CollectedClientData) Verify(storedChallenge string, ceremony CeremonyType, rpOrigins, rpOpaqueOrigins, rpTopOrigins []string, rpTopOriginsVerify TopOriginVerificationMode, allowCrossOrigin bool) (err error)

type CompoundPolicy ¶ added in v0.18.0

type CompoundPolicy struct {
	// SubStatementScope selects the sub-statements of the compound attestation which must be verified for the
	// attestation to be accepted.
	SubStatementScope CompoundSubStatementScope
}

CompoundPolicy configures the Compound Attestation Statement Format verification procedure.

Specification: §8.9. Compound Attestation Statement Format (https://www.w3.org/TR/webauthn-3/#sctn-compound-attestation)

type CompoundSubStatementScope ¶ added in v0.18.0

type CompoundSubStatementScope int

CompoundSubStatementScope selects the sub-statements of a compound attestation which must be verified for the attestation to be accepted.

§8.9 assigns this choice to the Relying Party: the handling of a sub-statement which fails verification, and the number of sub-statements which must succeed, are matters of Relying Party policy.

The scope applies only to the outcome of the verification procedures. The syntax of the compound statement itself is not a matter of policy, so a statement which doesn't satisfy the §8.9 CDDL, nests a compound sub-statement, or names a format this library doesn't implement is rejected under every scope.

Specification: §8.9. Compound Attestation Statement Format (https://www.w3.org/TR/webauthn-3/#sctn-compound-attestation)

const (
	// CompoundSubStatementScopeDefault is the zero value of [CompoundSubStatementScope] and has no matching rule in
	// §8.9. It evaluates as [CompoundSubStatementScopeAll] wherever it is used. webauthn.Config rewrites it to that
	// explicit constant during validation, so a Relying Party can tell an unset field apart from a deliberate choice
	// of the same scope.
	CompoundSubStatementScopeDefault CompoundSubStatementScope = iota

	// CompoundSubStatementScopeAll requires every sub-statement to be verified, and rejects the attestation on the
	// first sub-statement which fails.
	CompoundSubStatementScopeAll

	// CompoundSubStatementScopeAny requires a single sub-statement to be verified, and rejects the attestation only
	// when none of them can be. A sub-statement is verified when its format's verification procedure succeeds and
	// the trust path it produces is accepted by the Metadata Service, so a failure of either is tolerated provided
	// another sub-statement satisfies both.
	CompoundSubStatementScopeAny
)

type ConveyancePreference ¶

type ConveyancePreference string

ConveyancePreference is the type representing the AttestationConveyancePreference IDL.

WebAuthn Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation.

Specification: §5.4.7. Attestation Conveyance Preference Enumeration (https://www.w3.org/TR/webauthn/#enum-attestation-convey)

const (
	// PreferNoAttestation is a ConveyancePreference value.
	//
	// This value indicates that the Relying Party is not interested in authenticator attestation. For example, in order
	// to potentially avoid having to obtain user consent to relay identifying information to the Relying Party, or to
	// save a round trip to an Attestation CA or Anonymization CA.
	//
	// This is the default value.
	//
	// Specification: §5.4.7. Attestation Conveyance Preference Enumeration (https://www.w3.org/TR/webauthn/#dom-attestationconveyancepreference-none)
	PreferNoAttestation ConveyancePreference = none

	// PreferIndirectAttestation is a ConveyancePreference value.
	//
	// This value indicates that the Relying Party prefers an attestation conveyance yielding verifiable attestation
	// statements, but allows the client to decide how to obtain such attestation statements. The client MAY replace the
	// authenticator-generated attestation statements with attestation statements generated by an Anonymization CA, in
	// order to protect the user’s privacy, or to assist Relying Parties with attestation verification in a
	// heterogeneous ecosystem.
	//
	// Note: There is no guarantee that the Relying Party will obtain a verifiable attestation statement in this case.
	// For example, in the case that the authenticator employs self attestation.
	//
	// Specification: §5.4.7. Attestation Conveyance Preference Enumeration (https://www.w3.org/TR/webauthn/#dom-attestationconveyancepreference-indirect)
	PreferIndirectAttestation ConveyancePreference = "indirect"

	// PreferDirectAttestation is a ConveyancePreference value.
	//
	// This value indicates that the Relying Party wants to receive the attestation statement as generated by the
	// authenticator.
	//
	// Specification: §5.4.7. Attestation Conveyance Preference Enumeration (https://www.w3.org/TR/webauthn/#dom-attestationconveyancepreference-direct)
	PreferDirectAttestation ConveyancePreference = "direct"

	// PreferEnterpriseAttestation is a ConveyancePreference value.
	//
	// This value indicates that the Relying Party wants to receive an attestation statement that may include uniquely
	// identifying information. This is intended for controlled deployments within an enterprise where the organization
	// wishes to tie registrations to specific authenticators. User agents MUST NOT provide such an attestation unless
	// the user agent or authenticator configuration permits it for the requested RP ID.
	//
	// If permitted, the user agent SHOULD signal to the authenticator (at invocation time) that enterprise
	// attestation is requested, and convey the resulting AAGUID and attestation statement, unaltered, to the Relying
	// Party.
	//
	// Specification: §5.4.7. Attestation Conveyance Preference Enumeration (https://www.w3.org/TR/webauthn/#dom-attestationconveyancepreference-enterprise)
	PreferEnterpriseAttestation ConveyancePreference = "enterprise"
)

type Credential ¶

type Credential struct {
	// ID is The credential’s identifier. The requirements for the
	// identifier are distinct for each type of credential. It might
	// represent a username for username/password tuples, for example.
	ID string `json:"id"`
	// Type is the value of the object’s interface object's [[type]] slot,
	// which specifies the credential type represented by this object.
	// This should be type "public-key" for Webauthn credentials.
	Type string `json:"type"`
}

Credential is the basic credential type from the Credential Management specification that is inherited by WebAuthn's PublicKeyCredential type.

Specification: Credential Management §2.2. The Credential Interface (https://www.w3.org/TR/credential-management/#credential)

type CredentialAssertion ¶

type CredentialAssertion struct {
	Response  PublicKeyCredentialRequestOptions `json:"publicKey"`
	Mediation CredentialMediationRequirement    `json:"mediation,omitempty"`
}

CredentialAssertion is the top-level request object for credential assertion (login). It wraps PublicKeyCredentialRequestOptions and an optional mediation requirement. This is the object that should be serialized and sent to the client to initiate the navigator.credentials.get() call.

Specification: §5.5. Options for Assertion Generation (https://www.w3.org/TR/webauthn/#dictionary-assertion-options)

type CredentialAssertionResponse ¶

type CredentialAssertionResponse struct {
	PublicKeyCredential

	AssertionResponse AuthenticatorAssertionResponse `json:"response"`
}

The CredentialAssertionResponse is the raw response returned to the Relying Party from an authenticator when we request a credential for login/assertion.

func (car CredentialAssertionResponse) Parse() (par *ParsedCredentialAssertionData, err error)

type CredentialCreation ¶

type CredentialCreation struct {
	Response  PublicKeyCredentialCreationOptions `json:"publicKey"`
	Mediation CredentialMediationRequirement     `json:"mediation,omitempty"`
}

CredentialCreation is the top-level request object for credential registration. It wraps PublicKeyCredentialCreationOptions and an optional mediation requirement. This is the object that should be serialized and sent to the client to initiate the navigator.credentials.create() call.

Specification: §5.4. Options for Credential Creation (https://www.w3.org/TR/webauthn/#dictionary-makecredentialoptions)

type CredentialCreationResponse ¶

type CredentialCreationResponse struct {
	PublicKeyCredential

	AttestationResponse AuthenticatorAttestationResponse `json:"response"`
}

CredentialCreationResponse is the raw response returned to the Relying Party from the client for a credential registration ceremony. It contains the AuthenticatorAttestationResponse which holds the attestation object and client data.

Specification: §5.4. Options for Credential Creation (https://www.w3.org/TR/webauthn/#sctn-credentialcreationoptions-extension)

func (ccr CredentialCreationResponse) Parse() (pcc *ParsedCredentialCreationData, err error)

type CredentialDescriptor ¶

type CredentialDescriptor struct {
	// The valid credential types.
	Type CredentialType `json:"type"`

	// CredentialID The ID of a credential to allow/disallow.
	CredentialID URLEncodedBase64 `json:"id"`

	// The authenticator transports that can be used.
	Transport []AuthenticatorTransport `json:"transports,omitempty"`

	// AttestationType is the attestation type from the originating Credential (one of "basic_full",
	// "basic_surrogate", "attca", "anonca", "ecdaa", "none"). Used internally only; not serialized.
	AttestationType string `json:"-"`

	// AttestationFormat is the attestation statement format from the originating Credential (one of "packed",
	// "tpm", "android-key", "android-safetynet", "fido-u2f", "apple", "compound", "none"). Used internally only;
	// not serialized. Prior releases overloaded [CredentialDescriptor.AttestationType] with this value; callers
	// that construct descriptors directly should populate this field instead.
	AttestationFormat string `json:"-"`
}

CredentialDescriptor represents the PublicKeyCredentialDescriptor IDL.

This dictionary contains the attributes that are specified by a caller when referring to a public key credential as an input parameter to the create() or get() methods. It mirrors the fields of the PublicKeyCredential object returned by the latter methods.

Specification: §5.10.3. Credential Descriptor (https://www.w3.org/TR/webauthn/#credential-dictionary)

func (c CredentialDescriptor) SignalUnknownCredential(rpid string) *SignalUnknownCredential

type CredentialEntity ¶

type CredentialEntity struct {
	// A human-palatable name for the entity. Its function depends on what the PublicKeyCredentialEntity represents:
	//
	// When inherited by PublicKeyCredentialRpEntity it is a human-palatable identifier for the Relying Party,
	// intended only for display. For example, "ACME Corporation", "Wonderful Widgets, Inc." or "ОАО Примертех".
	//
	// When inherited by PublicKeyCredentialUserEntity, it is a human-palatable identifier for a user account. It is
	// intended only for display, i.e., aiding the user in determining the difference between user accounts with similar
	// displayNames. For example, "alexm", "alex.p.mueller@example.com" or "+14255551234".
	Name string `json:"name"`
}

CredentialEntity represents the PublicKeyCredentialEntity IDL and it describes a user account, or a WebAuthn Relying Party with which a public key credential is associated.

Specification: §5.4.1. Public Key Entity Description (https://www.w3.org/TR/webauthn/#dictionary-pkcredentialentity)

type CredentialMediationRequirement ¶ added in v0.12.0

type CredentialMediationRequirement string

CredentialMediationRequirement represents mediation requirements for clients. When making a request via get(options) or create(options), developers can set a case-by-case requirement for user mediation by choosing the appropriate CredentialMediationRequirement enum value.

See https://www.w3.org/TR/credential-management-1/#mediation-requirements

const (
	// MediationDefault lets the browser choose the mediation flow completely as if it wasn't specified at all.
	MediationDefault CredentialMediationRequirement = ""

	// MediationSilent indicates user mediation is suppressed for the given operation. If the operation can be performed
	// without user involvement, wonderful. If user involvement is necessary, then the operation will return null rather
	// than involving the user.
	MediationSilent CredentialMediationRequirement = "silent"

	// MediationOptional indicates if credentials can be handed over for a given operation without user mediation, they
	// will be. If user mediation is required, then the user agent will involve the user in the decision.
	MediationOptional CredentialMediationRequirement = "optional"

	// MediationConditional indicates for get(), discovered credentials are presented to the user in a non-modal dialog
	// along with an indication of the origin which is requesting credentials. If the user makes a gesture outside of
	// the dialog, the dialog closes without resolving or rejecting the Promise returned by the get() method and without
	// causing a user-visible error condition. If the user makes a gesture that selects a credential, that credential is
	// returned to the caller. The prevent silent access flag is treated as being true regardless of its actual value:
	// the conditional behavior always involves user mediation of some sort if applicable credentials are discovered.
	MediationConditional CredentialMediationRequirement = "conditional"

	// MediationRequired indicates the user agent will not hand over credentials without user mediation, even if the
	// prevent silent access flag is unset for an origin.
	MediationRequired CredentialMediationRequirement = "required"
)

type CredentialParameter ¶

type CredentialParameter struct {
	Type      CredentialType                       `json:"type" msg:"typ,omitempty"`
	Algorithm webauthncose.COSEAlgorithmIdentifier `json:"alg" msg:"alg,omitempty"`
}

CredentialParameter is the credential type and algorithm that the relying party wants the authenticator to create.

func (z *CredentialParameter) DecodeMsg(dc *msgp.Reader) (err error)

func (z CredentialParameter) EncodeMsg(en *msgp.Writer) (err error)

func (z CredentialParameter) MarshalMsg(b []byte) (o []byte, err error)

func (z CredentialParameter) Msgsize() (s int)

func (z *CredentialParameter) UnmarshalMsg(bts []byte) (o []byte, err error)

type CredentialPropertiesOutput ¶ added in v0.18.0

type CredentialPropertiesOutput struct {
	// RK reports whether the created credential is a client-side discoverable credential. A false value is
	// meaningful and distinct from the client not reporting the property at all.
	RK *bool `json:"rk,omitempty"`
}

CredentialPropertiesOutput represents the CredentialPropertiesOutput IDL. The editor's draft defines no member other than rk.

Specification: §10.1.3. Credential Properties Extension (https://www.w3.org/TR/webauthn-3/#sctn-authenticator-credential-properties-extension)

type CredentialProtectionPolicy ¶ added in v0.18.0

type CredentialProtectionPolicy string

CredentialProtectionPolicy represents the credential protection policy values of the CTAP credProtect extension.

Registry: https://www.iana.org/assignments/webauthn/webauthn.xhtml

const (
	// CredentialProtectionPolicyUserVerificationOptional is credProtect value 0x01.
	CredentialProtectionPolicyUserVerificationOptional CredentialProtectionPolicy = "userVerificationOptional"

	// CredentialProtectionPolicyUserVerificationOptionalWithCredentialIDList is credProtect value 0x02.
	CredentialProtectionPolicyUserVerificationOptionalWithCredentialIDList CredentialProtectionPolicy = "userVerificationOptionalWithCredentialIDList"

	// CredentialProtectionPolicyUserVerificationRequired is credProtect value 0x03.
	CredentialProtectionPolicyUserVerificationRequired CredentialProtectionPolicy = "userVerificationRequired"
)

func (p CredentialProtectionPolicy) Value() (value uint64, ok bool)

type CredentialType ¶

type CredentialType string

CredentialType represents the PublicKeyCredentialType IDL and is used with the CredentialDescriptor IDL.

This enumeration defines the valid credential types. It is an extension point; values can be added to it in the future, as more credential types are defined. The values of this enumeration are used for versioning the Authentication Assertion and attestation structures according to the type of the authenticator.

Currently one credential type is defined, namely "public-key".

Specification: §5.8.2. Credential Type Enumeration (https://www.w3.org/TR/webauthn/#enumdef-publickeycredentialtype)

Specification: §5.8.3. Credential Descriptor (https://www.w3.org/TR/webauthn/#dictionary-credential-descriptor)

const (
	// PublicKeyCredentialType - Currently one credential type is defined, namely "public-key".
	PublicKeyCredentialType CredentialType = "public-key"
)

type CurrentUserDetailsUser ¶ added in v0.18.0

type CurrentUserDetailsUser interface {
	WebAuthnID() []byte
	WebAuthnName() string
	WebAuthnDisplayName() string
}

CurrentUserDetailsUser is an interface that can be implemented by a user to provide the details a Relying Party signals after they change. It is a subset of github.com/go-webauthn/webauthn/webauthn.User, which therefore satisfies it without any additional method.

type ECDSASignatureEncoding ¶ added in v0.18.0

type ECDSASignatureEncoding int

ECDSASignatureEncoding selects the ASN.1 encodings which are accepted for an ECDSA signature.

The specification requires a signature to be valid under the algorithm the ceremony names, and the registered ECDSA algorithms are defined over the DER encoding. Some authenticators nonetheless emit a signature whose integers carry the padding BER permits and DER forbids, which a conforming verifier rejects. Tolerating that encoding is a deviation from the specification rather than a choice it delegates, so it's offered here as a Relying Party decision with the conforming behavior as the default.

const (
	// ECDSASignatureEncodingDefault is the zero value of [ECDSASignatureEncoding]. It evaluates as
	// [ECDSASignatureEncodingDER] wherever it is used. webauthn.Config rewrites it to that explicit constant during
	// validation, so a Relying Party can tell an unset field apart from a deliberate choice of the same encoding.
	ECDSASignatureEncodingDefault ECDSASignatureEncoding = iota

	// ECDSASignatureEncodingDER accepts only the DER encoding, which is the encoding the specification requires.
	ECDSASignatureEncodingDER

	// ECDSASignatureEncodingBER additionally accepts a signature whose integers are encoded under BER, by decoding
	// it and re-encoding the two integers it carries as DER before verification. Verification itself is unchanged:
	// the same signature over the same data by the same key is required, and only the encoding the verifier is
	// handed differs.
	//
	// The relaxation is confined to the minimal encoding requirement DER places on an INTEGER. A signature which is
	// not a SEQUENCE of exactly two positive integers, which carries a non-minimal or indefinite length, or which
	// has trailing data is rejected under this encoding as it is under [ECDSASignatureEncodingDER]. A signature
	// which cannot be decoded fails the ceremony rather than being passed on to be verified unchanged.
	//
	// This is insecure and not recommended. Accepting a non-DER signature makes the encoding of a signature
	// malleable, in that byte sequences which are not equal verify against the same message, and it accepts an
	// authenticator which does not conform to the specification. Select it only where a population of
	// authenticators known to emit such signatures has to be supported.
	ECDSASignatureEncodingBER
)

type Error ¶

type Error struct {
	// Short name for the type of error that has occurred.
	Type string `json:"type"`

	// Additional details about the error.
	Details string `json:"error"`

	// Information to help debug the error.
	DevInfo string `json:"debug"`

	// Inner error.
	Err error `json:"-"`
}

Error is a struct that describes specific error conditions in a structured format.

func ValidateMetadata(ctx context.Context, mds metadata.Provider, aaguid uuid.UUID, attestationType, attestationFormat string, x5cs []any) (protoErr *Error)

func (e *Error) Error() string

func (e *Error) Unwrap() error

func (e *Error) WithDetails(details string) *Error

func (e *Error) WithError(err error) *Error

func (e *Error) WithInfo(info string) *Error

type ErrorUnknownCredential ¶ added in v0.16.0

type ErrorUnknownCredential struct {
	Err *Error
}

ErrorUnknownCredential is a special Error which signals the fact the provided credential is unknown. The reason this specific error type is useful is so that the relying-party can send a signal to the Authenticator that the credential has been removed.

func (e *ErrorUnknownCredential) Error() string

func (e *ErrorUnknownCredential) Unwrap() error

func (e *ErrorUnknownCredential) WithDetails(details string) *ErrorUnknownCredential

func (e *ErrorUnknownCredential) WithError(err error) *ErrorUnknownCredential

func (e *ErrorUnknownCredential) WithInfo(info string) *ErrorUnknownCredential

type HMACGetSecretInputs ¶ added in v0.18.0

type HMACGetSecretInputs struct {
	Salt1 URLEncodedBase64 `json:"salt1"`
	Salt2 URLEncodedBase64 `json:"salt2,omitempty"`
}

HMACGetSecretInputs represents the inputs of the CTAP hmac-secret extension during authentication.

Registry: https://www.iana.org/assignments/webauthn/webauthn.xhtml

func (i HMACGetSecretInputs) IsZero() bool

type HMACGetSecretOutputs ¶ added in v0.18.0

type HMACGetSecretOutputs struct {
	// Output1 is the HMAC secret evaluated over the first salt.
	Output1 URLEncodedBase64 `json:"output1,omitempty"`

	// Output2 is the HMAC secret evaluated over the second salt, present only when a second salt was supplied.
	Output2 URLEncodedBase64 `json:"output2,omitempty"`
}

HMACGetSecretOutputs represents the outputs of the CTAP hmac-secret extension during authentication.

Registry: https://www.iana.org/assignments/webauthn/webauthn.xhtml

type LargeBlobInputs ¶ added in v0.18.0

type LargeBlobInputs struct {
	Support LargeBlobSupport `json:"support,omitempty"`
	Read    bool             `json:"read,omitempty"`
	Write   URLEncodedBase64 `json:"write,omitempty"`
}

LargeBlobInputs represents the AuthenticationExtensionsLargeBlobInputsJSON IDL. Support is only valid during registration; Read and Write are only valid during authentication and are mutually exclusive.

Specification: §10.1.5. Large blob storage extension (https://www.w3.org/TR/webauthn-3/#sctn-large-blob-extension)

func (i LargeBlobInputs) IsZero() bool

type LargeBlobOutputs ¶ added in v0.18.0

type LargeBlobOutputs struct {
	// Supported reports whether the created credential supports large blob storage. It is only present at
	// registration, in answer to the 'support' input. A false value is meaningful and distinct from the client
	// not reporting support at all; [AuthenticationExtensionsClientOutputs.Verify] rejects both when support was
	// requested as required.
	Supported *bool `json:"supported,omitempty"`

	// Blob is the stored blob, present at authentication in answer to a 'read' input.
	Blob URLEncodedBase64 `json:"blob,omitempty"`

	// Written reports whether the blob supplied by a 'write' input was stored. A false value is meaningful and
	// distinct from the client not reporting the outcome at all.
	Written *bool `json:"written,omitempty"`
}

LargeBlobOutputs represents the AuthenticationExtensionsLargeBlobOutputsJSON IDL.

Specification: §10.1.5. Large blob storage extension (https://www.w3.org/TR/webauthn-3/#sctn-large-blob-extension)

type LargeBlobSupport ¶ added in v0.18.0

type LargeBlobSupport string

LargeBlobSupport represents the LargeBlobSupport IDL enumeration used by the large blob storage extension during registration.

Specification: §10.1.5. Large blob storage extension (https://www.w3.org/TR/webauthn-3/#sctn-large-blob-extension)

const (
	// LargeBlobSupportRequired indicates the credential MUST support the large blob storage extension. The client
	// fails the ceremony when no eligible authenticator supports it.
	LargeBlobSupportRequired LargeBlobSupport = "required"

	// LargeBlobSupportPreferred indicates the credential SHOULD support the large blob storage extension.
	LargeBlobSupportPreferred LargeBlobSupport = "preferred"
)

type NonCompoundAttestationObject ¶ added in v0.16.0

type NonCompoundAttestationObject struct {
	// The format of the Attestation data.
	Format string `json:"fmt"`

	// The attestation statement data sent back if attestation is requested.
	AttStatement map[string]any `json:"attStmt,omitempty"`
}

NonCompoundAttestationObject is a subset of AttestationObject used within compound attestation statements. Each sub-statement in a compound attestation has its own format and attestation statement but shares authenticator data with the parent.

Specification: §8.9. Compound Attestation Statement Format (https://www.w3.org/TR/webauthn-3/#sctn-compound-attestation)

type PRFInputs ¶ added in v0.18.0

type PRFInputs struct {
	Eval             PRFValues            `json:"eval,omitzero"`
	EvalByCredential map[string]PRFValues `json:"evalByCredential,omitempty"`
}

PRFInputs represents the AuthenticationExtensionsPRFInputsJSON IDL.

Every member is optional. A zero value is the bare availability probe, i.e. the "prf":{} input a Relying Party sends at registration to learn whether the pseudo-random function is available for the credential; the client answers with the 'enabled' output. This is why AuthenticationExtensions.PRF is a pointer while its LargeBlobInputs and HMACGetSecretInputs siblings are not.

EvalByCredential is only valid during authentication; the client throws a NotSupportedError when it is present during registration. Its keys are base64url encoded credential IDs which MUST each match an entry of the allowed credentials.

Specification: §10.1.4. Pseudo-random function extension (https://www.w3.org/TR/webauthn-3/#prf-extension)

func (i PRFInputs) IsZero() bool

type PRFOutputs ¶ added in v0.18.0

type PRFOutputs struct {
	// Enabled reports whether the pseudo-random function is available for the credential. It is the answer to the
	// bare "prf":{} input a Relying Party sends at registration. A false value is meaningful and distinct from
	// the client not reporting availability at all.
	Enabled *bool `json:"enabled,omitempty"`

	// Results carries the outputs of evaluating the pseudo-random function over the requested salts. Second is
	// only set when a second salt was supplied.
	Results *PRFValues `json:"results,omitempty"`
}

PRFOutputs represents the AuthenticationExtensionsPRFOutputsJSON IDL.

Specification: §10.1.4. Pseudo-random function extension (https://www.w3.org/TR/webauthn-3/#prf-extension)

type PRFValues ¶ added in v0.18.0

type PRFValues struct {
	First  URLEncodedBase64 `json:"first"`
	Second URLEncodedBase64 `json:"second,omitempty"`
}

PRFValues represents the AuthenticationExtensionsPRFValuesJSON IDL. The byte values are conveyed to the client base64url encoded.

Specification: §10.1.4. Pseudo-random function extension (https://www.w3.org/TR/webauthn-3/#prf-extension)

func (v PRFValues) IsZero() bool

type ParsedAssertionResponse ¶

type ParsedAssertionResponse struct {
	CollectedClientData CollectedClientData
	AuthenticatorData   AuthenticatorData
	Signature           []byte
	UserHandle          []byte
}

ParsedAssertionResponse is the parsed form of AuthenticatorAssertionResponse.

type ParsedAttestationResponse ¶

type ParsedAttestationResponse struct {
	CollectedClientData CollectedClientData
	AttestationObject   AttestationObject
	Transports          []AuthenticatorTransport
}

ParsedAttestationResponse is the parsed version of AuthenticatorAttestationResponse.

type ParsedCredential ¶

type ParsedCredential struct {
	ID   string `cbor:"id"`
	Type string `cbor:"type"`
}

ParsedCredential is the parsed PublicKeyCredential interface, inherits from Credential, and contains the attributes that are returned to the caller when a new credential is created, or a new assertion is requested.

type ParsedCredentialAssertionData ¶

type ParsedCredentialAssertionData struct {
	ParsedPublicKeyCredential

	Response ParsedAssertionResponse
	Raw      CredentialAssertionResponse
}

The ParsedCredentialAssertionData is the parsed CredentialAssertionResponse that has been marshalled into a format that allows us to verify the client and authenticator data inside the response.

func ParseCredentialRequestResponse(response *http.Request) (*ParsedCredentialAssertionData, error)

func ParseCredentialRequestResponseBody(body io.Reader) (par *ParsedCredentialAssertionData, err error)

func ParseCredentialRequestResponseBytes(data []byte) (par *ParsedCredentialAssertionData, err error)

func (p *ParsedCredentialAssertionData) Verify(storedChallenge string, relyingPartyID, appID string, rpOrigins, rpOpaqueOrigins, rpTopOrigins []string, rpTopOriginsVerify TopOriginVerificationMode, allowCrossOrigin, verifyUser, verifyUserPresence bool, credentialBytes []byte, signature SignaturePolicy) error

type ParsedCredentialCreationData ¶

type ParsedCredentialCreationData struct {
	ParsedPublicKeyCredential

	Response ParsedAttestationResponse
	Raw      CredentialCreationResponse
}

ParsedCredentialCreationData is the parsed form of CredentialCreationResponse. It is the result of parsing the raw response from the authenticator and can be used with ParsedCredentialCreationData.Verify to complete the registration ceremony verification.

func ParseCredentialCreationResponse(request *http.Request) (*ParsedCredentialCreationData, error)

func ParseCredentialCreationResponseBody(body io.Reader) (pcc *ParsedCredentialCreationData, err error)

func ParseCredentialCreationResponseBytes(data []byte) (pcc *ParsedCredentialCreationData, err error)

func (pcc *ParsedCredentialCreationData) Verify(storedChallenge string, relyingPartyID string, rpOrigins, rpOpaqueOrigins, rpTopOrigins []string, rpTopOriginsVerify TopOriginVerificationMode, allowCrossOrigin, verifyUser, verifyUserPresence bool, mds metadata.Provider, credParams []CredentialParameter, policy AttestationPolicy, signature SignaturePolicy) (clientDataHash []byte, err error)

type ParsedPublicKeyCredential ¶

type ParsedPublicKeyCredential struct {
	ParsedCredential

	RawID                   []byte                                `json:"rawId"`
	ClientExtensionResults  AuthenticationExtensionsClientOutputs `json:"clientExtensionResults,omitzero"`
	AuthenticatorAttachment AuthenticatorAttachment               `json:"authenticatorAttachment,omitempty"`
}

ParsedPublicKeyCredential is the parsed form of PublicKeyCredential with typed fields.

func (ppkc ParsedPublicKeyCredential) GetAppID(session SessionExtensions, credentialAttestationFormat string) (appID string, err error)

type PublicKeyCredential ¶

type PublicKeyCredential struct {
	Credential

	RawID                   URLEncodedBase64                      `json:"rawId"`
	ClientExtensionResults  AuthenticationExtensionsClientOutputs `json:"clientExtensionResults,omitzero"`
	AuthenticatorAttachment string                                `json:"authenticatorAttachment,omitempty"`
}

PublicKeyCredential represents the IDL of the same name and contains the raw response returned to the Relying Party from the client's call to navigator.credentials.create() or navigator.credentials.get().

Specification: §5.1. PublicKeyCredential Interface (https://www.w3.org/TR/webauthn/#iface-pkcredential)

type PublicKeyCredentialCreationOptions ¶

type PublicKeyCredentialCreationOptions struct {
	RelyingParty           RelyingPartyEntity         `json:"rp"`
	User                   UserEntity                 `json:"user"`
	Challenge              URLEncodedBase64           `json:"challenge"`
	Parameters             []CredentialParameter      `json:"pubKeyCredParams,omitempty"`
	Timeout                int                        `json:"timeout,omitempty"`
	CredentialExcludeList  []CredentialDescriptor     `json:"excludeCredentials,omitempty"`
	AuthenticatorSelection AuthenticatorSelection     `json:"authenticatorSelection,omitzero"`
	Hints                  []PublicKeyCredentialHints `json:"hints,omitempty"`
	Attestation            ConveyancePreference       `json:"attestation,omitempty"`
	AttestationFormats     []AttestationFormat        `json:"attestationFormats,omitempty"`
	Extensions             AuthenticationExtensions   `json:"extensions,omitzero"`

	// Origin binds the ceremony to the single origin the response must declare. Used internally only; not
	// serialized, as the origin is not a member of the IDL and is never conveyed to the client. It is recorded in
	// the [github.com/go-webauthn/webauthn/webauthn.SessionData] instead, which the Finish step verifies the
	// collected client data against in place of the configured origins.
	Origin string `json:"-"`
}

PublicKeyCredentialCreationOptions represents the IDL of the same name.

In order to create a Credential via create(), the caller specifies a few parameters in a PublicKeyCredentialCreationOptions object.

WebAuthn Level 3: hints,attestationFormats.

Specification: §5.4. Options for Credential Creation (https://www.w3.org/TR/webauthn/#dictionary-makecredentialoptions)

type PublicKeyCredentialHints ¶ added in v0.11.0

type PublicKeyCredentialHints string

PublicKeyCredentialHints represents an entry of the hints member, which conveys the Relying Party's belief about how the user will satisfy the request, in descending order of preference.

The IDL types the hints member as a sequence of strings rather than as this enumeration, and requires clients to ignore values they do not recognise, so values are deliberately not validated against the constants below: a Relying Party may send a hint ratified after this release, or one a particular user agent understands. Clients also ignore the second and later appearances of a repeated hint.

Hints may contradict the authenticator attachment and the transports of the allowed credentials. Where they do, a client which implements hints gives the hints precedence; see PublicKeyCredentialHints.AuthenticatorAttachment for how a registration ceremony pairs the two for the benefit of clients which do not.

WebAuthn Level 3.

Specification: §5.8.7. User-agent Hints Enumeration (https://www.w3.org/TR/webauthn-3/#enum-hints)

const (
	// PublicKeyCredentialHintSecurityKey is a PublicKeyCredentialHint that indicates that the Relying Party believes
	// that users will satisfy this request with a physical security key. For example, an enterprise Relying Party may
	// set this hint if they have issued security keys to their employees and will only accept those authenticators for
	// registration and authentication.
	//
	// For compatibility with older user agents, when this hint is used in PublicKeyCredentialCreationOptions, the
	// authenticatorAttachment SHOULD be set to cross-platform.
	PublicKeyCredentialHintSecurityKey PublicKeyCredentialHints = "security-key"

	// PublicKeyCredentialHintClientDevice is a PublicKeyCredentialHint that indicates that the Relying Party believes
	// that users will satisfy this request with a platform authenticator attached to the client device.
	//
	// For compatibility with older user agents, when this hint is used in PublicKeyCredentialCreationOptions, the
	// authenticatorAttachment SHOULD be set to platform.
	PublicKeyCredentialHintClientDevice PublicKeyCredentialHints = "client-device"

	// PublicKeyCredentialHintHybrid is a PublicKeyCredentialHint that indicates that the Relying Party believes that
	// users will satisfy this request with general-purpose authenticators such as smartphones. For example, a consumer
	// Relying Party may believe that only a small fraction of their customers possesses dedicated security keys. This
	// option also implies that the local platform authenticator should not be promoted in the UI.
	//
	// For compatibility with older user agents, when this hint is used in PublicKeyCredentialCreationOptions, the
	// authenticatorAttachment SHOULD be set to cross-platform.
	PublicKeyCredentialHintHybrid PublicKeyCredentialHints = "hybrid"
)

func (h PublicKeyCredentialHints) AuthenticatorAttachment() AuthenticatorAttachment

type PublicKeyCredentialRequestOptions ¶

type PublicKeyCredentialRequestOptions struct {
	Challenge          URLEncodedBase64            `json:"challenge"`
	Timeout            int                         `json:"timeout,omitempty"`
	RelyingPartyID     string                      `json:"rpId,omitempty"`
	AllowedCredentials []CredentialDescriptor      `json:"allowCredentials,omitempty"`
	UserVerification   UserVerificationRequirement `json:"userVerification,omitempty"`
	Hints              []PublicKeyCredentialHints  `json:"hints,omitempty"`
	Extensions         AuthenticationExtensions    `json:"extensions,omitzero"`

	// Origin binds the ceremony to the single origin the response must declare. Used internally only; not
	// serialized, as the origin is not a member of the IDL and is never conveyed to the client. It is recorded in
	// the [github.com/go-webauthn/webauthn/webauthn.SessionData] instead, which the Finish step verifies the
	// collected client data against in place of the configured origins.
	Origin string `json:"-"`
}

The PublicKeyCredentialRequestOptions dictionary supplies get() with the data it needs to generate an assertion. Its challenge member MUST be present, while its other members are OPTIONAL.

WebAuthn Level 3: hints.

Specification: §5.5. Options for Assertion Generation (https://www.w3.org/TR/webauthn/#dictionary-assertion-options)

func (a *PublicKeyCredentialRequestOptions) GetAllowedCredentialIDs() [][]byte

type RelatedOriginLabeler ¶ added in v0.18.0

type RelatedOriginLabeler func(origin string) (label string, err error)

RelatedOriginLabeler derives the registrable domain label of an origin, which is the unit a client counts against MaximumRelatedOriginLabels. Origins which share a label cost only one between them, which is what lets a Relying Party list the same brand across many country code top level domains cheaply.

DefaultRelatedOriginLabeler is used when none is supplied. Supply your own to count labels exactly for a deployment which uses a multi-label public suffix; see that function for why the default cannot.

type RelatedOrigins ¶ added in v0.18.0

type RelatedOrigins struct {
	Origins []string `json:"origins"`
}

RelatedOrigins is the document a Relying Party serves at WellKnownPathWebAuthn to declare which origins may run ceremonies against its Relying Party ID.

Build one with NewRelatedOrigins, which validates and normalizes the origins, then serve it with whichever of RelatedOrigins.Bytes, RelatedOrigins.WriteTo or RelatedOrigins.WriteResponse suits the surrounding code. The type is also an http.Handler, so it can be mounted on a router directly:

related, err := protocol.NewRelatedOrigins("https://example.com", "https://example.com.au")
if err != nil {
	return err
}

mux.Handle(protocol.WellKnownPathWebAuthn, related)

A [WebAuthn.RelatedOrigins] method in the webauthn package builds this from the configured origins.

Specification: §5.11. Related Origin Requests (https://www.w3.org/TR/webauthn-3/#sctn-related-origins)

func NewRelatedOrigins(origins ...string) (related *RelatedOrigins, err error)

func NewRelatedOriginsWithLabeler(labeler RelatedOriginLabeler, origins ...string) (related *RelatedOrigins, err error)

func (r RelatedOrigins) Bytes() (data []byte, err error)

func (r RelatedOrigins) MarshalJSON() (data []byte, err error)

func (r RelatedOrigins) ServeHTTP(w http.ResponseWriter, request *http.Request)

func (r RelatedOrigins) WriteResponse(w http.ResponseWriter) (err error)

func (r RelatedOrigins) WriteTo(w io.Writer) (n int64, err error)

type RelyingPartyEntity ¶

type RelyingPartyEntity struct {
	CredentialEntity

	// A unique identifier for the Relying Party entity, which sets the RP ID.
	ID string `json:"id"`
}

The RelyingPartyEntity represents the PublicKeyCredentialRpEntity IDL and is used to supply additional Relying Party attributes when creating a new credential.

Specification: §5.4.2. Relying Party Parameters for Credential Generation (https://www.w3.org/TR/webauthn/#dictionary-rp-credential-params)

type ResidentKeyRequirement ¶ added in v0.2.0

type ResidentKeyRequirement string

ResidentKeyRequirement represents the IDL of the same name.

This enumeration’s values describe the Relying Party's requirements for client-side discoverable credentials (formerly known as resident credentials or resident keys).

Specifies the extent to which the Relying Party desires to create a client-side discoverable credential. For historical reasons the naming retains the deprecated “resident” terminology. The value SHOULD be a member of ResidentKeyRequirement but client platforms MUST ignore unknown values, treating an unknown value as if the member does not exist. If no value is given then the effective value is required if requireResidentKey is true or discouraged if it is false or absent.

Specification: §5.4.4. Authenticator Selection Criteria (https://www.w3.org/TR/webauthn/#dom-authenticatorselectioncriteria-residentkey)

Specification: §5.4.6. Resident Key Requirement Enumeration (https://www.w3.org/TR/webauthn/#enumdef-residentkeyrequirement)

const (
	// ResidentKeyRequirementDiscouraged indicates the Relying Party prefers creating a server-side credential, but will
	// accept a client-side discoverable credential. This is the default.
	ResidentKeyRequirementDiscouraged ResidentKeyRequirement = "discouraged"

	// ResidentKeyRequirementPreferred indicates to the client we would prefer a discoverable credential.
	ResidentKeyRequirementPreferred ResidentKeyRequirement = "preferred"

	// ResidentKeyRequirementRequired indicates the Relying Party requires a client-side discoverable credential, and is
	// prepared to receive an error if a client-side discoverable credential cannot be created.
	ResidentKeyRequirementRequired ResidentKeyRequirement = "required"
)

type SafetyNetResponse ¶

type SafetyNetResponse struct {
	Nonce                      string `json:"nonce"`
	TimestampMs                int64  `json:"timestampMs"`
	ApkPackageName             string `json:"apkPackageName"`
	ApkDigestSha256            string `json:"apkDigestSha256"`
	CtsProfileMatch            bool   `json:"ctsProfileMatch"`
	ApkCertificateDigestSha256 []any  `json:"apkCertificateDigestSha256"`
	BasicIntegrity             bool   `json:"basicIntegrity"`
}

type ServerResponse ¶

type ServerResponse struct {
	// Status indicates whether the operation succeeded or failed.
	Status ServerResponseStatus `json:"status"`

	// Message provides additional details about an error if Status is "failed".
	Message string `json:"errorMessage"`
}

ServerResponse is a response from a FIDO conformance server.

type ServerResponseStatus ¶

type ServerResponseStatus string

ServerResponseStatus is the status code returned by a FIDO conformance server.

const (
	// StatusOk indicates the server operation was successful.
	StatusOk ServerResponseStatus = "ok"

	// StatusFailed indicates the server operation failed.
	StatusFailed ServerResponseStatus = "failed"
)

type SessionExtensions ¶ added in v0.18.0

type SessionExtensions struct {
	// Requested lists the extension identifiers the Relying Party asked for, as reported by
	// [AuthenticationExtensions.Requested]. An extension output whose identifier is absent from this list was not
	// solicited.
	Requested []string `json:"requested,omitempty"`

	// AppID is the FIDO AppID Extension input, required to determine the Relying Party ID of a credential
	// registered through the legacy FIDO U2F JavaScript API.
	AppID string `json:"appid,omitempty"`

	// AppIDExclude is the FIDO AppID Exclusion Extension input.
	AppIDExclude string `json:"appidExclude,omitempty"`

	// LargeBlob is the large blob support requirement requested at registration. A value of
	// [LargeBlobSupportRequired] is asserted against the extension output.
	LargeBlob LargeBlobSupport `json:"largeBlob,omitempty"`

	// LargeBlobRead records that a large blob read was requested at authentication.
	LargeBlobRead bool `json:"largeBlobRead,omitempty"`

	// LargeBlobWrite records that a large blob write was requested at authentication. Only the intent is recorded;
	// the payload itself is excluded because it can be large and has no verification role beyond this flag.
	LargeBlobWrite bool `json:"largeBlobWrite,omitempty"`

	// CredentialProtectionPolicy is the CTAP credProtect policy requested at registration. It is asserted against
	// the authenticator extension output when EnforceCredentialProtectionPolicy is set.
	CredentialProtectionPolicy CredentialProtectionPolicy `json:"credentialProtectionPolicy,omitempty"`

	// EnforceCredentialProtectionPolicy records that the requested credential protection policy must be honoured.
	EnforceCredentialProtectionPolicy bool `json:"enforceCredentialProtectionPolicy,omitempty"`

	// CredBlob records that a blob was submitted for storage with the credential at registration. As with
	// LargeBlobWrite only the intent is recorded, because the blob is Relying Party data with no verification role
	// beyond this flag.
	CredBlob bool `json:"credBlob,omitempty"`

	// Extra carries the inputs of extensions this library does not model, so a Relying Party can verify the
	// outputs of its own extensions. Whatever is placed here is persisted verbatim; keep it small.
	Extra map[string]any `json:"extra,omitempty"`
}

SessionExtensions is the subset of AuthenticationExtensions a Relying Party must persist between the begin and finish steps of a ceremony in order to verify the extension outputs it receives.

The per-ceremony PRF salts and the large blob write payload are deliberately excluded. The salts are secrets with no verification role and the payload can be large; both are represented by their identifier in Requested.

func (e SessionExtensions) IsZero() bool

type SignalAllAcceptedCredentials ¶ added in v0.16.0

type SignalAllAcceptedCredentials struct {
	AllAcceptedCredentialIDs []URLEncodedBase64 `json:"allAcceptedCredentialIds"`
	RPID                     string             `json:"rpId"`
	UserID                   URLEncodedBase64   `json:"userId"`
}

SignalAllAcceptedCredentials is a struct which represents the CDDL of the same name.

func NewSignalAllAcceptedCredentials(rpid string, user AllAcceptedCredentialsUser) *SignalAllAcceptedCredentials

type SignalCurrentUserDetails ¶ added in v0.16.0

type SignalCurrentUserDetails struct {
	DisplayName string           `json:"displayName"`
	Name        string           `json:"name"`
	RPID        string           `json:"rpId"`
	UserID      URLEncodedBase64 `json:"userId"`
}

SignalCurrentUserDetails is a struct which represents the CDDL of the same name.

func NewSignalCurrentUserDetails(rpid string, user CurrentUserDetailsUser) *SignalCurrentUserDetails

type SignalUnknownCredential ¶ added in v0.16.0

type SignalUnknownCredential struct {
	CredentialID URLEncodedBase64 `json:"credentialId"`
	RPID         string           `json:"rpId"`
}

SignalUnknownCredential is a struct which represents the CDDL of the same name.

type SignaturePolicy ¶ added in v0.18.0

type SignaturePolicy struct {
	// ECDSAEncoding selects the ASN.1 encodings which are accepted for an ECDSA signature.
	ECDSAEncoding ECDSASignatureEncoding
}

SignaturePolicy carries the Relying Party policy decisions for verifying the signatures of a ceremony. It applies to the attestation signature of a registration and to the assertion signature of an authentication alike, as an authenticator which deviates from the specification in how it encodes one generally does so in both. The zero value selects the behavior the specification requires.

type TopOriginVerificationMode ¶ added in v0.11.0

type TopOriginVerificationMode int

TopOriginVerificationMode determines how the Relying Party validates the topOrigin field in CollectedClientData. This is relevant for cross-origin iframe scenarios where the top-level browsing context's origin differs from the embedded origin making the WebAuthn API call.

WebAuthn Level 3.

const (
	// TopOriginDefaultVerificationMode is the zero value of [TopOriginVerificationMode] and has no matching rule in
	// the verifier; passing it directly to [CollectedClientData.Verify] returns an "unknown Top Origin verification
	// mode" error. High-level callers using [webauthn.Config] have this value coerced to
	// [TopOriginExplicitVerificationMode] by config validation, which is the recommended default.
	TopOriginDefaultVerificationMode TopOriginVerificationMode = iota

	// TopOriginAutoVerificationMode accepts the Top Origin if it matches any entry in either the allowed Top Origins
	// list or the allowed Origins list. The two lists are unioned (RPTopOrigins ∪ RPOrigins). This is the most
	// permissive of the three active modes and should only be used when an RP deliberately wants cross-origin and
	// same-origin embeddings to share an allow-list.
	TopOriginAutoVerificationMode

	// TopOriginImplicitVerificationMode accepts the Top Origin only if it matches an entry in the allowed Origins
	// list (RPOrigins). The RPTopOrigins list is ignored in this mode.
	TopOriginImplicitVerificationMode

	// TopOriginExplicitVerificationMode accepts the Top Origin only if it matches an entry in the allowed Top Origins
	// list (RPTopOrigins). The RPOrigins list is ignored in this mode. This is the strictest mode and the one
	// [webauthn.Config] coerces the zero value to.
	TopOriginExplicitVerificationMode
)

type URLEncodedBase64 ¶

type URLEncodedBase64 []byte

URLEncodedBase64 represents a byte slice holding URL-encoded base64 data. When fields of this type are unmarshalled from JSON, the data is base64 decoded into a byte slice.

func CreateChallenge() (challenge URLEncodedBase64, err error)

func (e URLEncodedBase64) MarshalJSON() ([]byte, error)

func (e URLEncodedBase64) String() string

func (e *URLEncodedBase64) UnmarshalJSON(data []byte) error

type UnsolicitedOutputPolicy ¶ added in v0.18.0

type UnsolicitedOutputPolicy int

UnsolicitedOutputPolicy determines how a client extension output that the Relying Party did not request is handled during the finish step of a ceremony.

const (
	// UnsolicitedOutputPolicyReject fails the ceremony when the client returns an extension output the Relying
	// Party did not request. This is the zero value and therefore the default.
	UnsolicitedOutputPolicyReject UnsolicitedOutputPolicy = iota

	// UnsolicitedOutputPolicyIgnore accepts and ignores extension outputs the Relying Party did not request. Use
	// this only when a client is known to return outputs unprompted.
	UnsolicitedOutputPolicyIgnore
)

type UserEntity ¶

type UserEntity struct {
	CredentialEntity
	// A human-palatable name for the user account, intended only for display.
	// For example, "Alex P. Müller" or "田中 倫". The Relying Party SHOULD let
	// the user choose this, and SHOULD NOT restrict the choice more than necessary.
	DisplayName string `json:"displayName"`

	// ID is the user handle of the user account entity. To ensure secure operation,
	// authentication and authorization decisions MUST be made on the basis of this id
	// member, not the displayName nor name members. See Section 6.1 of
	// [RFC8266](https://www.w3.org/TR/webauthn/#biblio-rfc8266).
	ID any `json:"id"`
}

The UserEntity represents the PublicKeyCredentialUserEntity IDL and is used to supply additional user account attributes when creating a new credential.

Specification: §5.4.3 User Account Parameters for Credential Generation (https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialuserentity)

type UserVerificationMethod ¶ added in v0.18.0

type UserVerificationMethod struct {
	UserVerificationMethod uint32 `json:"userVerificationMethod"`
	KeyProtectionType      uint32 `json:"keyProtectionType"`
	MatcherProtectionType  uint32 `json:"matcherProtectionType"`
}

UserVerificationMethod is a single entry of the CTAP uvm extension output.

Registry: https://www.iana.org/assignments/webauthn/webauthn.xhtml

type UserVerificationRequirement ¶

type UserVerificationRequirement string

UserVerificationRequirement is a representation of the UserVerificationRequirement IDL enum.

A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs.

Specification: §5.8.6. User Verification Requirement Enumeration (https://www.w3.org/TR/webauthn/#enum-userVerificationRequirement)

const (
	// VerificationRequired User verification is required to create/release a credential.
	VerificationRequired UserVerificationRequirement = "required"

	// VerificationPreferred User verification is preferred to create/release a credential.
	VerificationPreferred UserVerificationRequirement = "preferred" // This is the default.

	// VerificationDiscouraged The authenticator should not verify the user for the credential.
	VerificationDiscouraged UserVerificationRequirement = "discouraged"
)