bcrypt

Documentation

Overview

Package bcrypt provides helpful abstractions for an implementation of bcrypt and implements github.com/go-crypt/crypt interfaces.

This implementation is loaded by crypt.NewDefaultDecoder and crypt.NewDecoderAll.

Index

• Constants
• func Decode(encodedDigest string) (digest algorithm.Digest, err error)
• func DecodeVariant(v Variant) func(encodedDigest string) (digest algorithm.Digest, err error)
• func RegisterDecoder(r algorithm.DecoderRegister) (err error)
• func RegisterDecoderSHA256(r algorithm.DecoderRegister) (err error)
• func RegisterDecoderStandard(r algorithm.DecoderRegister) (err error)
• type Digest
  • func (d *Digest) Encode() string
  • func (d *Digest) Match(password string) (match bool)
  • func (d *Digest) MatchAdvanced(password string) (match bool, err error)
  • func (d *Digest) MatchBytes(passwordBytes []byte) (match bool)
  • func (d *Digest) MatchBytesAdvanced(passwordBytes []byte) (match bool, err error)
  • func (d *Digest) String() string
• type Hasher
  • func New(opts ...Opt) (hasher *Hasher, err error)
  • func NewSHA256(opts ...Opt) (hasher *Hasher, err error)
  • func (h *Hasher) Hash(password string) (digest algorithm.Digest, err error)
  • func (h *Hasher) HashWithSalt(password string, salt []byte) (digest algorithm.Digest, err error)
  • func (h *Hasher) MustHash(password string) (digest algorithm.Digest)
  • func (h *Hasher) Validate() (err error)
  • func (h *Hasher) WithOptions(opts ...Opt) (err error)
• type Opt
  • func WithCost(iterations int) Opt
  • func WithIterations(iterations int) Opt
  • func WithVariant(variant Variant) Opt
  • func WithVariantName(identifier string) Opt
• type Variant
  • func NewVariant(identifier string) (variant Variant)
  • func (v Variant) Encode(cost int, version string, salt, key []byte) (f string)
  • func (v Variant) EncodeInput(src, salt []byte) (dst []byte)
  • func (v Variant) PasswordMaxLength() int
  • func (v Variant) Prefix() (prefix string)
  • func (v Variant) String() (name string)

Constants

const (
	// EncodingFmt is the encoding format for this algorithm.
	EncodingFmt = "$%s$%d$%s%s"

	// EncodingFmtSHA256 is the encoding format for the SHA256 variant of this algorithm.
	EncodingFmtSHA256 = "$%s$v=2,t=%s,r=%d$%s$%s"

	// AlgName is the name for this algorithm.
	AlgName = "bcrypt"

	// AlgIdentifier is the identifier used in this algorithm.
	AlgIdentifier = "2b"

	// AlgIdentifierVariantSHA256 is the identifier used in encoded SHA256 variant of this algorithm.
	AlgIdentifierVariantSHA256 = "bcrypt-sha256"

	// AlgIdentifierVerA is the identifier used in this algorithm (version a).
	AlgIdentifierVerA = "2a"

	// AlgIdentifierVerX is the identifier used in this algorithm (version x).
	AlgIdentifierVerX = "2x"

	// AlgIdentifierVerY is the identifier used in this algorithm (version y).
	AlgIdentifierVerY = "2y"

	// AlgIdentifierUnversioned is the identifier used in this algorithm (no version).
	AlgIdentifierUnversioned = "2"

	// VariantNameStandard is the variant name of the bcrypt.VariantStandard.
	VariantNameStandard = "standard"

	// VariantNameSHA256 is the variant name of the bcrypt.VariantSHA256.
	VariantNameSHA256 = algorithm.DigestSHA256

	// IterationsMin is the minimum iterations accepted.
	IterationsMin = 10

	// IterationsMax is the maximum iterations accepted.
	IterationsMax = 31

	// IterationsDefault is the default iterations.
	IterationsDefault = 13

	// PasswordInputSizeMax is the maximum password input size accepted.
	PasswordInputSizeMax = 72
)

Functions

func Decode

func Decode(encodedDigest string) (digest algorithm.Digest, err error)

Decode the encoded digest into a algorithm.Digest.

func DecodeVariant

func DecodeVariant(v Variant) func(encodedDigest string) (digest algorithm.Digest, err error)

DecodeVariant the encoded digest into a algorithm.Digest provided it matches the provided bcrypt.Variant. If bcrypt.VariantNone is used all variants can be decoded.

func RegisterDecoder

func RegisterDecoder(r algorithm.DecoderRegister) (err error)

RegisterDecoder the decoder with the algorithm.DecoderRegister.

func RegisterDecoderSHA256

func RegisterDecoderSHA256(r algorithm.DecoderRegister) (err error)

RegisterDecoderSHA256 registers specifically the sha256 decoder variant with the algorithm.DecoderRegister.

func RegisterDecoderStandard

func RegisterDecoderStandard(r algorithm.DecoderRegister) (err error)

RegisterDecoderStandard registers specifically the standard decoder variant with the algorithm.DecoderRegister.

Types

type Digest

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

Digest is a digest which handles bcrypt hashes.

func (*Digest) Encode

func (d *Digest) Encode() string

Encode returns the encoded form of this bcrypt.Digest.

func (*Digest) Match

func (d *Digest) Match(password string) (match bool)

Match returns true if the string password matches the current bcrypt.Digest.

func (*Digest) MatchAdvanced

func (d *Digest) MatchAdvanced(password string) (match bool, err error)

MatchAdvanced is the same as Match except if there is an error it returns that as well.

func (*Digest) MatchBytes

func (d *Digest) MatchBytes(passwordBytes []byte) (match bool)

MatchBytes returns true if the []byte passwordBytes matches the current bcrypt.Digest.

func (*Digest) MatchBytesAdvanced

func (d *Digest) MatchBytesAdvanced(passwordBytes []byte) (match bool, err error)

MatchBytesAdvanced is the same as MatchBytes except if there is an error it returns that as well.

func (*Digest) String

func (d *Digest) String() string

String returns the storable format of the bcrypt.Digest encoded hash.

type Hasher

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

Hasher is a crypt.Hash for bcrypt which can be initialized via bcrypt.New using a functional options pattern.

func New

func New(opts ...Opt) (hasher *Hasher, err error)

New returns a new bcrypt.Hasher with the provided functional options applied.

func NewSHA256

func NewSHA256(opts ...Opt) (hasher *Hasher, err error)

NewSHA256 returns a new bcrypt.Hasher with the provided functional options applied as well as the bcrypt.VariantSHA256 applied via the bcrypt.WithVariant bcrypt.Opt.

func (*Hasher) Hash

func (h *Hasher) Hash(password string) (digest algorithm.Digest, err error)

Hash performs the hashing operation and returns either an algorithm.Digest or an error.

func (*Hasher) HashWithSalt

func (h *Hasher) HashWithSalt(password string, salt []byte) (digest algorithm.Digest, err error)

HashWithSalt overloads the Hash method allowing the user to provide a salt. It's recommended instead to configure the salt size and let this be a random value generated using crypto/rand.

func (*Hasher) MustHash

func (h *Hasher) MustHash(password string) (digest algorithm.Digest)

MustHash overloads the Hash method and panics if the error is not nil. It's recommended if you use this option to utilize the Validate method first or handle the panic appropriately.

func (*Hasher) Validate

func (h *Hasher) Validate() (err error)

Validate checks the settings/parameters for this bcrypt.Hasher and returns an error.

func (*Hasher) WithOptions

func (h *Hasher) WithOptions(opts ...Opt) (err error)

WithOptions applies the provided functional options provided as an bcrypt.Opt to the bcrypt.Hasher.

type Opt

type Opt func(h *Hasher) (err error)

Opt describes the functional option pattern for the bcrypt.Hasher.

func WithCost

func WithCost(iterations int) Opt

WithCost is an alias for bcrypt.WithIterations.

func WithIterations

func WithIterations(iterations int) Opt

WithIterations sets the iterations parameter of the resulting bcrypt.Digest. Minimum is 10, Maximum is 31. Default is 12.

func WithVariant

func WithVariant(variant Variant) Opt

WithVariant is used to configure the bcrypt.Variant of the resulting bcrypt.Digest. Default is bcrypt.VariantStandard.

func WithVariantName

func WithVariantName(identifier string) Opt

WithVariantName uses the variant name or identifier to configure the bcrypt.Variant of the resulting bcrypt.Digest. Default is bcrypt.VariantStandard.

type Variant

type Variant int

Variant is a variant of the bcrypt.Digest.

const (
	// VariantNone is a variant of the bcrypt.Digest which is unknown.
	VariantNone Variant = iota

	// VariantStandard is the standard variant of bcrypt.Digest.
	VariantStandard

	// VariantSHA256 is the variant of bcrypt.Digest which hashes the password with HMAC-SHA256.
	VariantSHA256
)

func NewVariant

func NewVariant(identifier string) (variant Variant)

NewVariant converts an identifier string to a bcrypt.Variant.

func (Variant) Encode

func (v Variant) Encode(cost int, version string, salt, key []byte) (f string)

Encode formats the variant encoded bcrypt.Digest.

func (Variant) EncodeInput

func (v Variant) EncodeInput(src, salt []byte) (dst []byte)

EncodeInput returns the appropriate algorithm input.

func (Variant) PasswordMaxLength

func (v Variant) PasswordMaxLength() int

PasswordMaxLength returns -1 if the variant has no max length, otherwise returns the maximum password length.

func (Variant) Prefix

func (v Variant) Prefix() (prefix string)

Prefix returns the bcrypt.Variant prefix identifier.

func (Variant) String

func (v Variant) String() (name string)

String implements the fmt.Stringer returning a string representation of the bcrypt.Variant.