webauthn: github.com/koesie10/webauthn/webauthn Index | Files

package webauthn

import "github.com/koesie10/webauthn/webauthn"

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

Index

Package Files

config.go doc.go login.go registration.go session.go user.go webauthn.go

type Authenticator Uses

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 Uses

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 Uses

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 Uses

func (c *Config) Validate() error

Validate validates that all required fields in Config are set.

type Session Uses

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 Uses

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

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

type User Uses

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 Uses

type WebAuthn struct {
    Config *Config
}

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

func New Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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.

Package webauthn imports 8 packages (graph). Updated 2018-09-28. Refresh now. Tools for package owners.