webauthn

Documentation

Overview

Contains the API functionality of the library. After creating and configuring a webauthn object, users can call the object to create and validate web authentication credentials.

Index

• func SelectAuthenticator(att string, rrk *bool, uv string) p.AuthenticatorSelection
• type Authenticator
  • func (a *Authenticator) UpdateCounter(authDataCount uint32)
• type Config
• type Credential
  • func MakeNewCredential(c *protocol.ParsedCredentialCreationData) (*Credential, error)
• type DiscoverableUserHandler
• type LoginOption
  • func WithAllowedCredentials(allowList []protocol.CredentialDescriptor) LoginOption
  • func WithAssertionExtensions(extensions protocol.AuthenticationExtensions) LoginOption
  • func WithUserVerification(userVerification protocol.UserVerificationRequirement) LoginOption
• type RegistrationOption
  • func WithAuthenticatorSelection(authenticatorSelection protocol.AuthenticatorSelection) RegistrationOption
  • func WithConveyancePreference(preference protocol.ConveyancePreference) RegistrationOption
  • func WithExclusions(excludeList []protocol.CredentialDescriptor) RegistrationOption
  • func WithExtensions(extension protocol.AuthenticationExtensions) RegistrationOption
  • func WithResidentKeyRequirement(requirement protocol.ResidentKeyRequirement) RegistrationOption
• type SessionData
• type User
• type WebAuthn
  • func New(config *Config) (*WebAuthn, error)
  • func (webauthn *WebAuthn) BeginDiscoverableLogin(opts ...LoginOption) (*protocol.CredentialAssertion, *SessionData, error)
  • func (webauthn *WebAuthn) BeginLogin(user User, opts ...LoginOption) (*protocol.CredentialAssertion, *SessionData, error)
  • func (webauthn *WebAuthn) BeginRegistration(user User, opts ...RegistrationOption) (*protocol.CredentialCreation, *SessionData, error)
  • func (webauthn *WebAuthn) CreateCredential(user User, session SessionData, ...) (*Credential, error)
  • func (webauthn *WebAuthn) FinishLogin(user User, session SessionData, response *http.Request) (*Credential, error)
  • func (webauthn *WebAuthn) FinishRegistration(user User, session SessionData, response *http.Request) (*Credential, error)
  • func (webauthn *WebAuthn) ValidateDiscoverableLogin(handler DiscoverableUserHandler, session SessionData, ...) (*Credential, error)
  • func (webauthn *WebAuthn) ValidateLogin(user User, session SessionData, ...) (*Credential, error)

Functions

func SelectAuthenticator

func SelectAuthenticator(att string, rrk *bool, uv string) p.AuthenticatorSelection

Allow for easy marhsalling of authenticator options that are provided to the user

Types

type Authenticator

type Authenticator struct {
	// The AAGUID of the authenticator. An AAGUID is defined as an array containing the globally unique
	// identifier of the authenticator model being sought.
	AAGUID []byte
	// SignCount -Upon a new login operation, the Relying Party compares the stored signature counter value
	// with the new signCount value returned in the assertion’s authenticator data. If this new
	// signCount value is less than or equal to the stored value, a cloned authenticator may
	// exist, or the authenticator may be malfunctioning.
	SignCount uint32
	// CloneWarning - This is a signal that the authenticator may be cloned, i.e. at least two copies of the
	// credential private key may exist and are being used in parallel. Relying Parties should incorporate
	// this information into their risk scoring. Whether the Relying Party updates the stored signature
	// counter value in this case, or not, or fails the authentication ceremony or not, is Relying Party-specific.
	CloneWarning bool
}

func (*Authenticator) UpdateCounter

func (a *Authenticator) UpdateCounter(authDataCount uint32)

VerifyCounter Step 17 of §7.2. about verifying attestation. If the signature counter value authData.signCount is nonzero or the value stored in conjunction with credential’s id attribute is nonzero, then run the following sub-step:

If the signature counter value authData.signCount is

→ Greater than the signature counter value stored in conjunction with credential’s id attribute.
Update the stored signature counter value, associated with credential’s id attribute, to be the value of
authData.signCount.

→ Less than or equal to the signature counter value stored in conjunction with credential’s id attribute.
This is a signal that the authenticator may be cloned, see CloneWarning above for more information.

type Config

type Config struct {
	RPDisplayName string
	RPID          string
	RPOrigin      string
	RPIcon        string
	// Defaults for generating options
	AttestationPreference  protocol.ConveyancePreference
	AuthenticatorSelection protocol.AuthenticatorSelection

	Timeout int
	Debug   bool
}

The config values required for proper

type Credential

type Credential struct {
	// A probabilistically-unique byte sequence identifying a public key credential source and its authentication assertions.
	ID []byte
	// The public key portion of a Relying Party-specific credential key pair, generated by an authenticator and returned to
	// a Relying Party at registration time (see also public key credential). The private key portion of the credential key
	// pair is known as the credential private key. Note that in the case of self attestation, the credential key pair is also
	// used as the attestation key pair, see self attestation for details.
	PublicKey []byte
	// The attestation format used (if any) by the authenticator when creating the credential.
	AttestationType string
	// The Authenticator information for a given certificate
	Authenticator Authenticator
}

Credential contains all needed information about a WebAuthn credential for storage

func MakeNewCredential

func MakeNewCredential(c *protocol.ParsedCredentialCreationData) (*Credential, error)

MakeNewCredential will return a credential pointer on successful validation of a registration response

type DiscoverableUserHandler

type DiscoverableUserHandler func(rawID, userHandle []byte) (user User, err error)

DiscoverableUserHandler returns a *User given the provided userHandle.

type LoginOption

type LoginOption func(*protocol.PublicKeyCredentialRequestOptions)

LoginOption is used to provide parameters that modify the default Credential Assertion Payload that is sent to the user.

func WithAllowedCredentials

func WithAllowedCredentials(allowList []protocol.CredentialDescriptor) LoginOption

Updates the allowed credential list with Credential Descripiptors, discussed in §5.10.3 (https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialdescriptor) with user-supplied values

func WithAssertionExtensions

func WithAssertionExtensions(extensions protocol.AuthenticationExtensions) LoginOption

Request additional extensions for assertion

func WithUserVerification

func WithUserVerification(userVerification protocol.UserVerificationRequirement) LoginOption

Request a user verification preference

type RegistrationOption

type RegistrationOption func(*protocol.PublicKeyCredentialCreationOptions)

func WithAuthenticatorSelection

func WithAuthenticatorSelection(authenticatorSelection protocol.AuthenticatorSelection) RegistrationOption

Provide non-default parameters regarding the authenticator to select.

func WithConveyancePreference

func WithConveyancePreference(preference protocol.ConveyancePreference) RegistrationOption

Provide non-default parameters regarding whether the authenticator should attest to the credential.

func WithExclusions

func WithExclusions(excludeList []protocol.CredentialDescriptor) RegistrationOption

Provide non-default parameters regarding credentials to exclude from retrieval.

func WithExtensions

func WithExtensions(extension protocol.AuthenticationExtensions) RegistrationOption

Provide extension parameter to registration options

func WithResidentKeyRequirement

func WithResidentKeyRequirement(requirement protocol.ResidentKeyRequirement) RegistrationOption

WithResidentKeyRequirement sets both the resident key and require resident key protocol options. This could conflict with webauthn.WithAuthenticatorSelection if it doesn't come after it.

type SessionData

type SessionData struct {
	Challenge            string                               `json:"challenge"`
	UserID               []byte                               `json:"user_id"`
	AllowedCredentialIDs [][]byte                             `json:"allowed_credentials,omitempty"`
	UserVerification     protocol.UserVerificationRequirement `json:"userVerification"`
	Extensions           protocol.AuthenticationExtensions    `json:"extensions,omitempty"`
}

SessionData is the data that should be stored by the Relying Party for the duration of the web authentication ceremony

type User

type User interface {
	// User ID according to the Relying Party
	WebAuthnID() []byte
	// User Name according to the Relying Party
	WebAuthnName() string
	// Display Name of the user
	WebAuthnDisplayName() string
	// User's icon url
	WebAuthnIcon() string
	// Credentials owned by the user
	WebAuthnCredentials() []Credential
}

User is built to interface with the Relying Party's User entry and elaborate the fields and methods needed for WebAuthn

type WebAuthn

type WebAuthn struct {
	Config *Config
}

WebAuthn is the primary interface of this package and contains the request handlers that should be called.

func New

func New(config *Config) (*WebAuthn, error)

Create a new WebAuthn object given the proper config flags

func (*WebAuthn) BeginDiscoverableLogin

func (webauthn *WebAuthn) BeginDiscoverableLogin(opts ...LoginOption) (*protocol.CredentialAssertion, *SessionData, error)

BeginDiscoverableLogin begins a client-side discoverable login, previously known as Resident Key logins.

func (*WebAuthn) BeginLogin

func (webauthn *WebAuthn) BeginLogin(user User, opts ...LoginOption) (*protocol.CredentialAssertion, *SessionData, error)

Creates the CredentialAssertion data payload that should be sent to the user agent for beginning the login/assertion process. The format of this data can be seen in §5.5 of the WebAuthn specification (https://www.w3.org/TR/webauthn/#assertion-options). These default values can be amended by providing additional LoginOption parameters. This function also returns sessionData, that must be stored by the RP in a secure manner and then provided to the FinishLogin function. This data helps us verify the ownership of the credential being retreived.

func (*WebAuthn) BeginRegistration

func (webauthn *WebAuthn) BeginRegistration(user User, opts ...RegistrationOption) (*protocol.CredentialCreation, *SessionData, error)

Generate a new set of registration data to be sent to the client and authenticator.

func (*WebAuthn) CreateCredential

func (webauthn *WebAuthn) CreateCredential(user User, session SessionData, parsedResponse *protocol.ParsedCredentialCreationData) (*Credential, error)

CreateCredential verifies a parsed response against the user's credentials and session data.

func (*WebAuthn) FinishLogin

func (webauthn *WebAuthn) FinishLogin(user User, session SessionData, response *http.Request) (*Credential, error)

Take the response from the client and validate it against the user credentials and stored session data

func (*WebAuthn) FinishRegistration

func (webauthn *WebAuthn) FinishRegistration(user User, session SessionData, response *http.Request) (*Credential, error)

Take the response from the authenticator and client and verify the credential against the user's credentials and session data.

func (*WebAuthn) ValidateDiscoverableLogin

func (webauthn *WebAuthn) ValidateDiscoverableLogin(handler DiscoverableUserHandler, session SessionData, parsedResponse *protocol.ParsedCredentialAssertionData) (*Credential, error)

ValidateDiscoverableLogin is an overloaded version of ValidateLogin that allows for discoverable credentials.

func (*WebAuthn) ValidateLogin

func (webauthn *WebAuthn) ValidateLogin(user User, session SessionData, parsedResponse *protocol.ParsedCredentialAssertionData) (*Credential, error)

ValidateLogin takes a parsed response and validates it against the user credentials and session data