Documentation
¶
Overview ¶
Package auth holds the credential building blocks: Argon2id password hashing, random tokens stored only as hashes, and login rate limiting.
Index ¶
- Constants
- Variables
- func DisplayPrefix(secret string) string
- func GeneratePassword() string
- func HashSecret(secret string) []byte
- func NewToken(kind TokenKind) (secret string, hash []byte, err error)
- func ParseToken(kind TokenKind, secret string) ([]byte, bool)
- func ReadSetupCode(dataDir string) (string, error)
- func ValidatePassword(password string) error
- type Hasher
- type LoginLimiter
- type Params
- type SetupCode
- type TokenKind
Constants ¶
const ( // MinPasswordLength and MaxPasswordLength are counted in characters. // There are no composition rules. 15 is the NIST SP 800-63B-4 minimum // for a password used as the only factor, which it is until MFA exists. MinPasswordLength = 15 MaxPasswordLength = 256 )
const SetupCodeFile = "setup-code"
SetupCodeFile is where a new Controller keeps its one-time setup code, in its data directory.
Variables ¶
var ErrWeakPassword = fmt.Errorf("passwords must be %d to %d characters long", MinPasswordLength, MaxPasswordLength)
ErrWeakPassword is returned for passwords outside the length limits.
Functions ¶
func DisplayPrefix ¶
DisplayPrefix returns the start of an API token, enough for a person to tell tokens apart without revealing the secret.
func GeneratePassword ¶
func GeneratePassword() string
GeneratePassword returns a random one-time password (130 bits) for an administrator to hand over.
func HashSecret ¶
HashSecret returns the SHA-256 of a secret, prefix included.
func NewToken ¶
NewToken returns a new secret of the given kind and the hash to store. Only the hash is ever persisted.
func ParseToken ¶
ParseToken checks that secret is well formed for kind and returns the hash to look it up by. Lookups compare SHA-256 hashes in the database, so response timing reveals nothing about stored secrets.
func ReadSetupCode ¶ added in v1.19.0
ReadSetupCode returns the setup code kept in dataDir, for an administrator on the Controller's machine. It fails with os.ErrNotExist once setup is done.
func ValidatePassword ¶
ValidatePassword checks a new password against the length limits.
Types ¶
type Hasher ¶
type Hasher struct {
// contains filtered or unexported fields
}
Hasher hashes and verifies passwords. Each hash uses Params.Memory, so a semaphore bounds how many run at once: a burst of logins cannot exhaust the Controller's memory.
type LoginLimiter ¶
type LoginLimiter struct {
// contains filtered or unexported fields
}
LoginLimiter slows down password guessing, per account and per client address. State lives only in memory: nothing about attempts, including addresses, is stored.
func NewLoginLimiter ¶
func NewLoginLimiter(now func() time.Time) *LoginLimiter
NewLoginLimiter returns a limiter; now may be nil for time.Now.
func (*LoginLimiter) Allow ¶
func (l *LoginLimiter) Allow(username, address string) time.Duration
Allow is called before checking a password. It returns zero if the attempt may proceed, or how long the caller must wait. Unknown usernames are limited exactly like real ones, so limits reveal nothing either.
func (*LoginLimiter) Failure ¶
func (l *LoginLimiter) Failure(username string)
Failure records a wrong password. From the sixth consecutive failure the account is locked, starting at one minute and doubling up to 15 minutes.
func (*LoginLimiter) Success ¶
func (l *LoginLimiter) Success(username string)
Success clears an account's failures.
type Params ¶
type Params struct {
// Memory in KiB.
Memory uint32
Iterations uint32
Parallelism uint8
SaltLength uint32
KeyLength uint32
}
Params are Argon2id cost parameters.
func DefaultParams ¶
func DefaultParams() Params
DefaultParams follow RFC 9106's second recommended option: 64 MiB, 3 passes, 4 lanes.
type SetupCode ¶ added in v1.19.0
type SetupCode struct {
// contains filtered or unexported fields
}
SetupCode guards first-run setup: whoever completes it becomes the first administrator, so it needs a code only someone with access to the Controller's machine can read. The code is written to a file (mode 0600), never logged, and removed once setup is done.
func NewSetupCode ¶ added in v1.19.0
NewSetupCode returns the setup code kept in dataDir.
func (*SetupCode) Check ¶ added in v1.19.0
Check reports whether code is the setup code, in constant time. Without a code (setup done, or never needed) nothing matches.
func (*SetupCode) Done ¶ added in v1.19.0
Done forgets and removes the code: setup cannot be done again.
Source Files