webauthn

package
Version: v0.3.4 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2018 License: MIT Imports: 8 Imported by: 2

Documentation

Overview

webauthn is a high-level package that contains HTTP request handlers which can be used to implement webauthn in any application.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Authenticator

type Authenticator interface {
	WebAuthID() []byte
	WebAuthCredentialID() []byte
	WebAuthPublicKey() []byte
	WebAuthAAGUID() []byte
	WebAuthSignCount() uint32
}

Authenticator represents an authenticator that can be used by a user.

type AuthenticatorStore

type AuthenticatorStore interface {
	// AddAuthenticator should add the given authenticator to a user. The authenticator's type should not be depended
	// on; it is constructed by this package. All information should be stored in a way such that it is retrievable
	// in the future using GetAuthenticator and GetAuthenticators.
	AddAuthenticator(user User, authenticator Authenticator) error
	// GetAuthenticator gets a single Authenticator by the given id, as returned by Authenticator.WebAuthID.
	GetAuthenticator(id []byte) (Authenticator, error)
	// GetAuthenticators gets a list of all registered authenticators for this user. It might be the case that the user
	// has been constructed by this package and the only non-empty value is the WebAuthID. In this case, the store
	// should still return the authenticators as specified by the ID.
	GetAuthenticators(user User) ([]Authenticator, error)
}

AuthenticatorStore should be implemented by the storage layer to store authenticators.

type Config

type Config struct {
	// RelyingPartyName is a human-palatable identifier for the Relying Party, intended only for display. For example,
	// "ACME Corporation", "Wonderful Widgets, Inc." or "ОАО Примертех".
	RelyingPartyName string
	// RelyingPartyID is a unique identifier for the Relying Party entity. It must be a valid domain string that
	// identifies the Relying Party on whose behalf a registration or login is being performed. A public key credential
	// can only be used for authentication with the same RP ID it was registered with.
	// By default, it is set to the caller's origin effective domain. It may be overridden, as long as the RP ID is
	// a registrable domain suffix or is equal to the caller's effective domain.
	// For example, given a Relying Party whose origin is https://login.example.com:1337, then the following RP IDs
	// are valid: login.example.com (default) and example.com, but not m.login.example.com and not com.
	// In production, this value should be set. If it is not set, the implementation is INSECURE and the RP ID hash
	// supplied by the authenticator will not be checked.
	RelyingPartyID string
	// RelyingPartyOrigin is the RP origin that an authenticator response will be compared with. If it is empty,
	// the value will be ignored. However, this is INSECURE and should not be used in production.
	// For example, given a Relying Party whose origin is https://login.example.com:1337, this value should be set
	// to "https://login.example.com:1337".
	RelyingPartyOrigin string

	// AuthenticatorStore will be used to store authenticators of a user.
	AuthenticatorStore AuthenticatorStore

	// SessionKeyPrefixChallenge holds the prefix of the key of the challenge in the session. If it is not set, it will
	// be set to "webauthn.challenge".
	SessionKeyPrefixChallenge string
	// SessionKeyPrefixUserID holds the prefix of the key of the user ID in the session. If it is not set, it will be
	// set to "webauthn.user.id".
	SessionKeyPrefixUserID string

	// Timeout is the amount of time in milliseconds the user will be permitted to authenticate with their device on
	// registration and login. The default is 30000, i.e. 30 seconds.
	Timeout uint

	// Debug sets a few settings related to ease of debugging, such as sharing more error information to clients.
	Debug bool
}

Config holds all the configuration for WebAuthn

func (*Config) Validate

func (c *Config) Validate() error

Validate validates that all required fields in Config are set.

type Session

type Session interface {
	Set(name string, value interface{}) error
	Get(name string) (interface{}, error)
	Delete(name string) error
}

Session will be used by the request handlers to save temporary data, such as the challenge and user ID.

func WrapMap

func WrapMap(values map[interface{}]interface{}) Session

WrapMap can be used to create a Session for e.g. a gorilla/sessions type.

type User

type User interface {
	// WebAuthID should return the ID of the user. This could for example be the binary encoding of an int.
	WebAuthID() []byte
	// WebAuthName should return the name of the user.
	WebAuthName() string
	// WebAuthDisplayName should return the display name of the user.
	WebAuthDisplayName() string
}

User should be implemented by users used in the request handlers.

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(c *Config) (*WebAuthn, error)

New creates a new WebAuthn based on the given Config. The Config will be validated and an error will be returned if it is invalid.

func (*WebAuthn) FinishLogin

func (w *WebAuthn) FinishLogin(r *http.Request, rw http.ResponseWriter, user User, session Session) Authenticator

FinishLogin is a HTTP request handler which should receive the response of navigator.credentials.get(). If user is non-nil, it will be checked that the authenticator is owned by that user. If the request is valid, the authenticator will be returned and nothing will have been written to http.ResponseWriter. If authenticator is nil, an error has been written to http.ResponseWriter and should be returned as-is.

func (*WebAuthn) FinishRegistration

func (w *WebAuthn) FinishRegistration(r *http.Request, rw http.ResponseWriter, user User, session Session) Authenticator

FinishRegistration is a HTTP request handler which should receive the response of navigator.credentials.create(). If the request is valid, AuthenticatorStore.AddAuthenticator will be called and an empty response with HTTP status code 201 (Created) will be written to the http.ResponseWriter. If authenticator is nil, an error has been written to http.ResponseWriter and should be returned as-is.

func (*WebAuthn) GetLoginOptions added in v0.3.3

func (w *WebAuthn) GetLoginOptions(user User, session Session) (*protocol.CredentialRequestOptions, error)

GetLoginOptions will return the options that need to be passed to navigator.credentials.get(). This should be returned to the user via e.g. JSON over HTTP. For convenience, use StartLogin.

func (*WebAuthn) GetRegistrationOptions added in v0.3.3

func (w *WebAuthn) GetRegistrationOptions(user User, session Session) (*protocol.CredentialCreationOptions, error)

GetRegistrationOptions will return the options that need to be passed to navigator.credentials.create(). This should be returned to the user via e.g. JSON over HTTP. For convenience, use StartRegistration.

func (*WebAuthn) ParseAndFinishLogin added in v0.3.3

func (w *WebAuthn) ParseAndFinishLogin(assertionResponse protocol.AssertionResponse, user User, session Session) (Authenticator, error)

ParseAndFinishLogin should receive the response of navigator.credentials.get(). If user is non-nil, it will be checked that the authenticator is owned by that user. If the request is valid, the authenticator will be returned. For convenience, use FinishLogin.

func (*WebAuthn) ParseAndFinishRegistration added in v0.3.3

func (w *WebAuthn) ParseAndFinishRegistration(attestationResponse protocol.AttestationResponse, user User, session Session) (Authenticator, error)

ParseAndFinishRegistration should receive the response of navigator.credentials.create(). If the request is valid, AuthenticatorStore.AddAuthenticator will be called and the authenticator that was registered will be returned. For convenience, use FinishRegistration.

func (*WebAuthn) StartLogin

func (w *WebAuthn) StartLogin(r *http.Request, rw http.ResponseWriter, user User, session Session)

StartLogin is a HTTP request handler which writes the options to be passed to navigator.credentials.get() to the http.ResponseWriter. The user argument is optional and can be nil, in which case the allowCredentials option will not be set and AuthenticatorStore.GetAuthenticators will not be called.

func (*WebAuthn) StartRegistration

func (w *WebAuthn) StartRegistration(r *http.Request, rw http.ResponseWriter, user User, session Session)

StartRegistration is a HTTP request handler which writes the options to be passed to navigator.credentials.create() to the http.ResponseWriter.

Jump to

Keyboard shortcuts

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