Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Account

type Account struct {
	// A user's username.
	Username string `json:"username"`

	// The user's hashed password, base64-encoded.
	Password string `json:"password"`

	// The user's password salt, base64-encoded; for
	// algorithms where external salt is needed.
	Salt string `json:"salt,omitempty"`
	// contains filtered or unexported fields
}

Account contains a username, password, and salt (if applicable).

type Authentication

type Authentication struct {
	// A set of authentication providers. If none are specified,
	// all requests will always be unauthenticated.
	ProvidersRaw caddy.ModuleMap `json:"providers,omitempty" caddy:"namespace=http.authentication.providers"`

	Providers map[string]Authenticator `json:"-"`
}

Authentication is a middleware which provides user authentication. Rejects requests with HTTP 401 if the request is not authenticated.

Its API is still experimental and may be subject to change.

func (Authentication) CaddyModule

func (Authentication) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Authentication) Provision

func (a *Authentication) Provision(ctx caddy.Context) error

Provision sets up a.

func (Authentication) ServeHTTP

func (a Authentication) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

type Authenticator

type Authenticator interface {
	Authenticate(http.ResponseWriter, *http.Request) (User, bool, error)
}

Authenticator is a type which can authenticate a request. If a request was not authenticated, it returns false. An error is only returned if authenticating the request fails for a technical reason (not for bad/missing credentials).

type BcryptHash

type BcryptHash struct{}

BcryptHash implements the bcrypt hash.

func (BcryptHash) CaddyModule

func (BcryptHash) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (BcryptHash) Compare

func (BcryptHash) Compare(hashed, plaintext, _ []byte) (bool, error)

Compare compares passwords.

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache enables caching of basic auth results. This is especially helpful for secure password hashes which can be expensive to compute on every HTTP request.

type Comparer

type Comparer interface {
	// Compare returns true if the result of hashing
	// plaintextPassword with salt is hashedPassword,
	// false otherwise. An error is returned only if
	// there is a technical/configuration error.
	Compare(hashedPassword, plaintextPassword, salt []byte) (bool, error)
}

Comparer is a type that can securely compare a plaintext password with a hashed password in constant-time. Comparers should hash the plaintext password and then use constant-time comparison.

type HTTPBasicAuth

type HTTPBasicAuth struct {
	// The algorithm with which the passwords are hashed. Default: bcrypt
	HashRaw json.RawMessage `json:"hash,omitempty" caddy:"namespace=http.authentication.hashes inline_key=algorithm"`

	// The list of accounts to authenticate.
	AccountList []Account `json:"accounts,omitempty"`

	// The name of the realm. Default: restricted
	Realm string `json:"realm,omitempty"`

	// If non-nil, a mapping of plaintext passwords to their
	// hashes will be cached in memory (with random eviction).
	// This can greatly improve the performance of traffic-heavy
	// servers that use secure password hashing algorithms, with
	// the downside that plaintext passwords will be stored in
	// memory for a longer time (this should not be a problem
	// as long as your machine is not compromised, at which point
	// all bets are off, since basicauth necessitates plaintext
	// passwords being received over the wire anyway).
	HashCache *Cache `json:"hash_cache,omitempty"`

	Accounts map[string]Account `json:"-"`
	Hash     Comparer           `json:"-"`
}

HTTPBasicAuth facilitates HTTP basic authentication.

func (HTTPBasicAuth) Authenticate

func (hba HTTPBasicAuth) Authenticate(w http.ResponseWriter, req *http.Request) (User, bool, error)

Authenticate validates the user credentials in req and returns the user, if valid.

func (HTTPBasicAuth) CaddyModule

func (HTTPBasicAuth) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*HTTPBasicAuth) Provision

func (hba *HTTPBasicAuth) Provision(ctx caddy.Context) error

Provision provisions the HTTP basic auth provider.

type ScryptHash

type ScryptHash struct {
	// scrypt's N parameter. If unset or 0, a safe default is used.
	N int `json:"N,omitempty"`

	// scrypt's r parameter. If unset or 0, a safe default is used.
	R int `json:"r,omitempty"`

	// scrypt's p parameter. If unset or 0, a safe default is used.
	P int `json:"p,omitempty"`

	// scrypt's key length parameter (in bytes). If unset or 0, a
	// safe default is used.
	KeyLength int `json:"key_length,omitempty"`
}

ScryptHash implements the scrypt KDF as a hash.

func (ScryptHash) CaddyModule

func (ScryptHash) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (ScryptHash) Compare

func (s ScryptHash) Compare(hashed, plaintext, salt []byte) (bool, error)

Compare compares passwords.

func (*ScryptHash) Provision

func (s *ScryptHash) Provision(_ caddy.Context) error

Provision sets up s.

func (*ScryptHash) SetDefaults

func (s *ScryptHash) SetDefaults()

SetDefaults sets safe default parameters, but does not overwrite existing values. Each default parameter is set independently; it does not check to ensure that r*p < 2^30. The defaults chosen are those as recommended in 2019 by https://godoc.org/golang.org/x/crypto/scrypt.

type User

type User struct {
	// The ID of the authenticated user.
	ID string

	// Any other relevant data about this
	// user. Keys should be adhere to Caddy
	// conventions (snake_casing), as all
	// keys will be made available as
	// placeholders.
	Metadata map[string]string
}

User represents an authenticated user.