algorithm

Documentation

Overview

Package algorithm is a package which contains the individual algorithms and interfaces related to their implementation.

Index

• Constants
• Variables
• type DecodeFunc
• type Decoder
• type DecoderRegister
• type Digest
• type Hash
• type HashFunc
• type Matcher

Constants

const (
	// DigestSHA1 is te name for SHA1 digests.
	DigestSHA1 = "sha1"

	// DigestSHA224 is te name for SHA224 digests.
	DigestSHA224 = "sha224"

	// DigestSHA256 is te name for SHA256 digests.
	DigestSHA256 = "sha256"

	// DigestSHA384 is te name for SHA384 digests.
	DigestSHA384 = "sha384"

	// DigestSHA512 is te name for SHA512 digests.
	DigestSHA512 = "sha512"
)

const (
	// SaltLengthDefault is the default salt size for most implementations.
	SaltLengthDefault = 16

	// KeyLengthDefault is the default key size for most implementations.
	KeyLengthDefault = 32
)

const (
	ErrFmtInvalidIntParameter = "%w: parameter '%s' must be between %d%s and %d but is set to '%d'"
	ErrFmtDigestDecode        = "%s decode error: %w"
	ErrFmtDigestMatch         = "%s match error: %w"
	ErrFmtHasherHash          = "%s hashing error: %w"
	ErrFmtHasherValidation    = "%s validation error: %w"
)

Error format strings.

Variables

var (
	// ErrEncodedHashInvalidFormat is an error returned when an encoded hash has an invalid format.
	ErrEncodedHashInvalidFormat = errors.New("provided encoded hash has an invalid format")

	// ErrEncodedHashInvalidIdentifier is an error returned when an encoded hash has an invalid identifier for the
	// given digest.
	ErrEncodedHashInvalidIdentifier = errors.New("provided encoded hash has an invalid identifier")

	// ErrEncodedHashInvalidVersion is an error returned when an encoded hash has an unsupported or otherwise invalid
	// version.
	ErrEncodedHashInvalidVersion = errors.New("provided encoded hash has an invalid version")

	// ErrEncodedHashInvalidOption is an error returned when an encoded hash has an unsupported or otherwise invalid
	// option in the option field.
	ErrEncodedHashInvalidOption = errors.New("provided encoded hash has an invalid option")

	// ErrEncodedHashInvalidOptionKey is an error returned when an encoded hash has an unknown or otherwise invalid
	// option key in the option field.
	ErrEncodedHashInvalidOptionKey = errors.New("provided encoded hash has an invalid option key")

	// ErrEncodedHashInvalidOptionValue is an error returned when an encoded hash has an unknown or otherwise invalid
	// option value in the option field.
	ErrEncodedHashInvalidOptionValue = errors.New("provided encoded hash has an invalid option value")

	// ErrEncodedHashKeyEncoding is an error returned when an encoded hash has a salt with an invalid or unsupported
	// encoding.
	ErrEncodedHashKeyEncoding = errors.New("provided encoded hash has a key value that can't be decoded")

	// ErrEncodedHashSaltEncoding is an error returned when an encoded hash has a salt with an invalid or unsupported
	// encoding.
	ErrEncodedHashSaltEncoding = errors.New("provided encoded hash has a salt value that can't be decoded")

	// ErrKeyDerivation is returned when a Key function returns an error.
	ErrKeyDerivation = errors.New("failed to derive the key with the provided parameters")

	// ErrSaltEncoding is an error returned when a salt has an invalid or unsupported encoding.
	ErrSaltEncoding = errors.New("provided salt has a value that can't be decoded")

	// ErrPasswordInvalid is an error returned when a password has an invalid or unsupported properties. It is NOT
	// returned on password mismatches.
	ErrPasswordInvalid = errors.New("password is invalid")

	// ErrSaltInvalid is an error returned when a salt has an invalid or unsupported properties.
	ErrSaltInvalid = errors.New("salt is invalid")

	// ErrSaltReadRandomBytes is an error returned when generating the random bytes for salt resulted in an error.
	ErrSaltReadRandomBytes = errors.New("could not read random bytes for salt")

	// ErrParameterInvalid is an error returned when a parameter has an invalid value.
	ErrParameterInvalid = errors.New("parameter is invalid")
)

Types

type DecodeFunc

type DecodeFunc func(encodedDigest string) (digest Digest, err error)

DecodeFunc describes a function to decode an encoded digest into a algorithm.Digest.

type Decoder

type Decoder interface {
	Decode(encodedDigest string) (digest Digest, err error)
}

Decoder is a representation of a implementation that performs generic decoding. Currently this is just intended for use by implementers.

type DecoderRegister

type DecoderRegister interface {
	RegisterDecodeFunc(prefix string, decoder DecodeFunc) (err error)
	RegisterDecodePrefix(prefix, identifier string) (err error)

	Decoder
}

DecoderRegister describes an implementation that allows registering DecodeFunc's.

type Digest

type Digest interface {
	fmt.Stringer

	Matcher

	Encode() (hash string)
}

Digest represents a hashed password. It's implemented by all hashed password results so that when we pass a stored hash into its relevant type we can verify the password against the hash.

type Hash

type Hash interface {
	// Validate checks the hasher configuration to ensure it's valid. This should be used when the Hash is going to be
	// reused and you should use it in conjunction with MustHash.
	Validate() (err error)

	// Hash performs the hashing operation on a password and resets any relevant parameters such as a manually set salt.
	// It then returns a Digest and error.
	Hash(password string) (hashed Digest, err error)

	// HashWithSalt is an overload of Digest that also accepts a salt.
	HashWithSalt(password string, salt []byte) (hashed Digest, err error)

	// MustHash overloads the Hash method and panics if the error is not nil. It's recommended if you use this method to
	// utilize the Validate method first or handle the panic appropriately.
	MustHash(password string) (hashed Digest)
}

Hash is an interface which implements password hashing.

type HashFunc

type HashFunc func() hash.Hash

HashFunc is a function which returns a hash.Hash.

type Matcher

type Matcher interface {
	Match(password string) (match bool)
	MatchBytes(passwordBytes []byte) (match bool)
	MatchAdvanced(password string) (match bool, err error)
	MatchBytesAdvanced(passwordBytes []byte) (match bool, err error)
}

Matcher is an interface used to match passwords.