github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth

No package summary is available.

Package

Files: 5. Third party imports: 6. Imports from organisation: 0. Tests: 0. Benchmarks: 0.

Vars

Types

Account

Account contains a username and password.

Field name	Field type	Comment
Username	`string`	A user's username.
Password	`string`	The user's hashed password, in Modular Crypt Format (with `$` prefix) or base64-encoded.
password	`[]byte`	No comment on field.

Authentication

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

After a successful authentication, the placeholder {http.auth.user.id} will be set to the username, and also {http.auth.user.*} placeholders may be set for any authentication modules that provide user metadata.

In case of an error, the placeholder {http.auth.<provider>.error} will be set to the error message returned by the authentication provider.

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

Field name	Field type	Comment
ProvidersRaw	`caddy.ModuleMap`	A set of authentication providers. If none are specified, all requests will always be unauthenticated.
Providers	`map[string]Authenticator`	No comment on field.
logger	`*zap.Logger`	No comment on field.

Authenticator

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).

Field name	Field type	Comment
type	`any`	No comment on field.

BcryptHash

BcryptHash implements the bcrypt hash.

Cache

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.

Field name	Field type	Comment
mu	`*sync.RWMutex`	No comment on field.
g	`*singleflight.Group`	No comment on field.
cache	`map[string]bool`	map of concatenated hashed password + plaintext password, to result

Comparer

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.

Field name	Field type	Comment
type	`any`	No comment on field.

HTTPBasicAuth

HTTPBasicAuth facilitates HTTP basic authentication.

Field name	Field type	Comment
HashRaw	`json.RawMessage`	The algorithm with which the passwords are hashed. Default: bcrypt
AccountList	`[]Account`	The list of accounts to authenticate.
Realm	`string`	The name of the realm. Default: restricted
HashCache	`*Cache`	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). Note that a cache hit does not mean it is a valid password.
Accounts	`map[string]Account`	No comment on field.
Hash	`Comparer`	No comment on field.
fakePassword	`[]byte`	fakePassword is used when a given user is not found, so that timing side-channels can be mitigated: it gives us something to hash and compare even if the user does not exist, which should have similar timing as a user account that does exist.

Hasher

Hasher is a type that can generate a secure hash given a plaintext. Hashing modules which implement this interface can be used with the hash-password subcommand as well as benefitting from anti-timing features. A hasher also returns a fake hash which can be used for timing side-channel mitigation.

Field name	Field type	Comment
type	`any`	No comment on field.

User

User represents an authenticated user.

Field name	Field type	Comment
ID	`string`	The ID of the authenticated user.
Metadata	`map[string]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.

Functions

func (*Authentication) Provision

Provision sets up a.

Uses: fmt.Errorf.

func (*HTTPBasicAuth) Provision

Provision provisions the HTTP basic auth provider.

Uses: base64.StdEncoding, fmt.Errorf, json.RawMessage, singleflight.Group, strings.HasPrefix, sync.RWMutex.

func (Authentication) CaddyModule

CaddyModule returns the Caddy module information.

func (Authentication) ServeHTTP

Uses: caddyhttp.Error, fmt.Errorf, http.StatusUnauthorized, zap.Error, zap.String, zapcore.ErrorLevel.

func (BcryptHash) CaddyModule

CaddyModule returns the Caddy module information.

func (BcryptHash) Compare

Compare compares passwords.

Uses: bcrypt.CompareHashAndPassword, bcrypt.ErrMismatchedHashAndPassword.

func (BcryptHash) FakeHash

FakeHash returns a fake hash.

func (BcryptHash) Hash

Hash hashes plaintext using a random salt.

Uses: bcrypt.GenerateFromPassword.

func (HTTPBasicAuth) Authenticate

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

func (HTTPBasicAuth) CaddyModule

CaddyModule returns the Caddy module information.

Private functions

func cmdHashPassword

References: bufio.NewReader, bytes.Equal, fmt.Errorf, fmt.Fprint, fmt.Fprintln, fmt.Println, os.Exit, os.Interrupt, os.Signal, os.Stderr, os.Stdin, signal.Notify, signal.Stop, term.GetState, term.IsTerminal, term.ReadPassword, term.Restore.

func init

func parseCaddyfile

parseCaddyfile sets up the handler from Caddyfile tokens. Syntax:

basic_auth [<matcher>] [<hash_algorithm> [<realm>]] {
    <username> <hashed_password>
    ...
}

If no hash algorithm is supplied, bcrypt will be assumed.

References: caddyconfig.JSON, caddyconfig.JSONModuleObject.

func makeRoom

makeRoom deletes about 1/10 of the items in the cache in order to keep its size under control. It must not be called without a lock on c.mu.

References: weakrand.Intn.

func correctPassword

References: hex.EncodeToString.

func promptForCredentials

References: fmt.Sprintf.