butcher

README

go-butcher

Butcher for progressive hashing password

Status: Prod ready

Follow compliance from OWASP Password Storage requirements.

Algorithms supported :

• Argon2id (default)
• Scrypt+Blake2b-512
• PBKDF2+SHA512

Output samples

'hAETWCB5IAJc8618VI9POngh6g0+rkEbUj/7pxZaAKuxPoRfilhA5+q1E+wifRoxLpEX7acA48KMmD/7OPJb5cTjxGP91Hv9z3vEBNOb095WPBo5yLn1w9mPnkfgKSv6MWKJRG0mGg'
'hAMBWCBD/40V1xzT/Kt0/40y0aeg60eHOyJFROiHuWkMvBIehlhA5U1h9I9fMSASOAcz4JpEQHEhwJGUlg8WpvqRnSG5gjruaa7LvNa7bMEHi1Qk5aVfpsisJBMlfxO5UaoLe1BC+A'
'hAIBWCBosL5P+aF/j2PmrIcE8W1Gxq+I2tMic0ON4xz1ZJkgr1hAUhaZ/2tI02iwD1H2DqTafepgdYfCHauWOzwkgTQsIcwvTTs1M8puQ5+UXl2cUA9f10EtjzM7vwaAHWU71Rrwhw'

Advices

• Try to use client side hash function before sending credentials to the server (Blake2b-512 / SHA3-512);
• use a 32 byte or 64 byte salt (actual size dependent on protection function);
• You should encrypt these results in your database to add hash privacy;
• Store pepper and encryption key in a HSM or Software Vault;
• For Paranoid (like me) => Implement perfect secrecy using NaCL box on top of HTTPS;

Documentation

Index

• Constants
• Variables
• func FixedNonce(salt []byte) func() []byte
• func Hash(password []byte) (string, error)
• func NeedsUpgrade(encoded []byte) bool
• func RandomNonce(length int) func() []byte
• func Verify(encoded []byte, password []byte) (bool, error)
• type Butcher
  • func New(options ...Option) (*Butcher, error)
  • func (b *Butcher) Hash(password []byte) (string, error)
  • func (b *Butcher) NeedsUpgrade(encoded []byte) bool
  • func (b *Butcher) Verify(encoded []byte, password []byte) (bool, error)
• type Option
  • func WithAlgorithm(algo hasher.Algorithm) Option
  • func WithPepper(value []byte) Option
  • func WithSaltFunc(factory func() []byte) Option

Constants

const (
	// DefaultAlgorithm defines the default algorithm to use when not specified
	DefaultAlgorithm = hasher.Argon2id
	// ExpectedAlgorithmVersion defines the lower supported version of the hashing strategy
	ExpectedAlgorithmVersion = uint8(0x01)
)

Variables

var (
	// ErrInvalidHash is raised when caller try to invoke not supported algorithm
	ErrInvalidHash = errors.New("butcher: invalid hash")
	// ErrStrategyNotSupported is raised when caller try to invoke not supported algorithm
	ErrStrategyNotSupported = errors.New("butcher: given strategy is not supported")
)

var (
	// DefaultSaltFunc defines the default salt generation factory to use when not specified
	DefaultSaltFunc = RandomNonce(32)
)

Functions

func FixedNonce

func FixedNonce(salt []byte) func() []byte

FixedNonce returns a nonce factory that returns the given salt

func Hash

func Hash(password []byte) (string, error)

Hash password using default instance

func NeedsUpgrade

func NeedsUpgrade(encoded []byte) bool

NeedsUpgrade returns the password hash upgrade need when DefaultAlgorithm is changed

func RandomNonce

func RandomNonce(length int) func() []byte

RandomNonce returns a nonce factory that returns a random length bound salt

func Verify

func Verify(encoded []byte, password []byte) (bool, error)

Verify password using default instance

Types

type Butcher

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

Butcher defines the hasher configuration

func New

func New(options ...Option) (*Butcher, error)

New butcher instance is buildded according options

func (*Butcher) Hash

func (b *Butcher) Hash(password []byte) (string, error)

Hash the given password with the hash strategy

func (*Butcher) NeedsUpgrade

func (b *Butcher) NeedsUpgrade(encoded []byte) bool

NeedsUpgrade returns the password hash upgrade need when DefaultAlgorithm is changed

func (*Butcher) Verify

func (b *Butcher) Verify(encoded []byte, password []byte) (bool, error)

Verify cleartext password with encoded one

type Option

type Option func(*Butcher)

Option is the butcher option setting function signature

func WithAlgorithm

func WithAlgorithm(algo hasher.Algorithm) Option

WithAlgorithm defines the algorithm to use for hashing password

func WithPepper

func WithPepper(value []byte) Option

WithPepper defines the password peppering value

func WithSaltFunc

func WithSaltFunc(factory func() []byte) Option

WithSaltFunc defines the salt factory value for salt generation