hash

Documentation

Overview

Package hash turns passwords into storable strings and checks them again. Stored hashes carry their algorithm in a leading "$name$" segment, so a Registry can still verify a hash written by a superseded algorithm. That makes replacing bcrypt a configuration change, not a password reset.

Index

• Constants
• Variables
• type Algorithm
• type Bcrypt
  • func NewBcrypt(cost int) (*Bcrypt, error)
  • func (b *Bcrypt) Hash(password string) (string, error)
  • func (b *Bcrypt) Identifiers() []string
  • func (b *Bcrypt) Name() string
  • func (b *Bcrypt) Verify(encoded, password string) error
• type Registry
  • func NewRegistry(preferred Algorithm, others ...Algorithm) (*Registry, error)
  • func (r *Registry) Hash(password string) (string, error)
  • func (r *Registry) NeedsRehash(encoded string) bool
  • func (r *Registry) Verify(encoded, password string) error

Constants

const MaxBcryptPasswordLength = 72

MaxBcryptPasswordLength is the longest input accepted, in bytes. bcrypt silently truncates longer input, which would let a different password match.

const MinPasswordLength = 8

MinPasswordLength is the shortest password accepted, in characters.

TODO: length alone is weak. NIST SP 800-63B section 5.1.1.2 asks for a breached-password blocklist, which needs a data source this project does not have yet.

Variables

var (
	ErrMismatch         = errors.New("password does not match hash")
	ErrUnknownAlgorithm = errors.New("unknown password hash algorithm")
	ErrPasswordTooShort = fmt.Errorf("password must be at least %d characters", MinPasswordLength)
	ErrPasswordTooLong  = errors.New("password is too long for the hash algorithm")
)

Types

type Algorithm

type Algorithm interface {
	// Name identifies the scheme. A stored hash written by a different name is rehashed on login.
	Name() string
	// Identifiers lists the "$name$" segments this scheme recognizes in a stored hash.
	Identifiers() []string
	Hash(password string) (string, error)
	Verify(encoded, password string) error
}

Algorithm is one password hashing scheme.

type Bcrypt

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

func NewBcrypt

func NewBcrypt(cost int) (*Bcrypt, error)

func (*Bcrypt) Hash

func (b *Bcrypt) Hash(password string) (string, error)

func (*Bcrypt) Identifiers

func (b *Bcrypt) Identifiers() []string

Identifiers covers every bcrypt revision in the wild. All three verify identically.

func (*Bcrypt) Name

func (b *Bcrypt) Name() string

func (*Bcrypt) Verify

func (b *Bcrypt) Verify(encoded, password string) error

type Registry

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

Registry hashes with one preferred algorithm and verifies against every registered one.

func NewRegistry

func NewRegistry(preferred Algorithm, others ...Algorithm) (*Registry, error)

func (*Registry) Hash

func (r *Registry) Hash(password string) (string, error)

func (*Registry) NeedsRehash

func (r *Registry) NeedsRehash(encoded string) bool

NeedsRehash reports whether a stored hash was written by something other than the preferred algorithm. Callers rehash on a successful login, when the plaintext is in hand.

TODO: also rehash when the preferred algorithm's cost parameter has been raised.

func (*Registry) Verify

func (r *Registry) Verify(encoded, password string) error