shacrypt

Documentation

Overview

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

See https://www.akkadia.org/drepper/SHA-crypt.html for specification details.

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 RegisterDecoderSHA512(r algorithm.DecoderRegister) (err error)
• type Digest
  • func (d *Digest) Encode() (hash 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() (hasher *Hasher, err error)
  • func NewSHA512() (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 WithIterations(iterations int) Opt
  • func WithRounds(rounds int) Opt
  • func WithSHA256() Opt
  • func WithSHA512() Opt
  • func WithSaltLength(bytes int) Opt
  • func WithVariant(variant Variant) Opt
  • func WithVariantName(identifier string) Opt
• type Variant
  • func NewVariant(identifier string) Variant
  • func (v Variant) DefaultIterations() int
  • func (v Variant) HashFunc() algorithm.HashFunc
  • func (v Variant) Name() (s string)
  • func (v Variant) Prefix() (prefix string)
  • func (v Variant) String() (identifier string)

Constants

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

	// EncodingFmtRoundsOmitted is the encoding format for this algorithm when the rounds can be omitted.
	EncodingFmtRoundsOmitted = "$%s$%s$%s"

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

	// AlgIdentifierSHA256 is the identifier used in encoded SHA256 variants of this algorithm.
	AlgIdentifierSHA256 = "5"

	// AlgIdentifierSHA512 is the identifier used in encoded SHA512 variants of this algorithm.
	AlgIdentifierSHA512 = "6"

	// IterationsMin is the minimum number of iterations accepted.
	IterationsMin = 1000

	// IterationsMax is the maximum number of iterations accepted.
	IterationsMax = 999999999

	// IterationsDefaultSHA256 is the default number of iterations for SHA256.
	IterationsDefaultSHA256 = 1000000

	// IterationsDefaultSHA512 is the default number of iterations for SHA512.
	IterationsDefaultSHA512 = 500000

	// IterationsDefaultOmitted is the default number of iterations when the rounds are omitted.
	IterationsDefaultOmitted = 5000

	// SaltLengthMin is the minimum salt length.
	SaltLengthMin = 1

	// SaltLengthMax is the maximum salt length.
	SaltLengthMax = 16

	// SaltCharSet are the valid characters for the salt.
	SaltCharSet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789./"
)

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 Variant. If 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 RegisterDecoderSHA512

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

RegisterDecoderSHA512 registers specifically the sha512 decoder variant with the algorithm.DecoderRegister.

Types

type Digest

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

Digest is a digest which handles SHA-crypt hashes like SHA256 or SHA512.

func (*Digest) Encode

func (d *Digest) Encode() (hash string)

Encode this Digest as a string for storage.

func (*Digest) Match

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

Match returns true if the string password matches the current shacrypt.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 shacrypt.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 shacrypt.Digest hash utilizing fmt.Sprintf and shacrypt.EncodingFmt.

type Hasher

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

Hasher is a algorithm.Hash for SHA-crypt which can be initialized via shacrypt.New using a functional options pattern.

func New

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

New returns a *Hasher without any settings configured. This d to a SHA512 hash.Hash with 1000000 iterations. These settings can be overridden with the methods with the With prefix.

func NewSHA256

func NewSHA256() (hasher *Hasher, err error)

NewSHA256 returns a *Hasher with the SHA256 hash.Hash which d to 1000000 iterations. These settings can be overridden with the methods with the With prefix.

func NewSHA512

func NewSHA512() (hasher *Hasher, err error)

NewSHA512 returns a *Hasher with the SHA512 hash.Hash which d to 1000000 iterations. These settings can be overridden with the methods with the With prefix.

func (*Hasher) Hash

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

Hash performs the hashing operation and returns either a shacrypt.Digest as a 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 shacrypt.Hasher and returns an error.

func (*Hasher) WithOptions

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

WithOptions defines the options for this scrypt.Hasher.

type Opt

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

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

func WithIterations

func WithIterations(iterations int) Opt

WithIterations sets the iterations parameter of the resulting shacrypt.Digest. Minimum 1000, Maximum 999999999. Default is 1000000.

func WithRounds

func WithRounds(rounds int) Opt

WithRounds is an alias for shacrypt.WithIterations.

func WithSHA256

func WithSHA256() Opt

WithSHA256 adjusts this Hasher to utilize the SHA256 hash.Hash.

func WithSHA512

func WithSHA512() Opt

WithSHA512 adjusts this Hasher to utilize the SHA512 hash.Hash.

func WithSaltLength

func WithSaltLength(bytes int) Opt

WithSaltLength adjusts the salt size (in bytes) of the resulting shacrypt.Digest. Minimum 1, Maximum 16. Default is 16.

func WithVariant

func WithVariant(variant Variant) Opt

WithVariant configures the shacrypt.Variant of the resulting shacrypt.Digest. Default is shacrypt.VariantSHA512.

func WithVariantName

func WithVariantName(identifier string) Opt

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

type Variant

type Variant int

Variant is a variant of the shacrypt.Digest.

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

	// VariantSHA256 is a variant of the shacrypt.Digest which uses SHA-256.
	VariantSHA256

	// VariantSHA512 is a variant of the shacrypt.Digest which uses SHA-512.
	VariantSHA512
)

func NewVariant

func NewVariant(identifier string) Variant

NewVariant converts an identifier string to a shacrypt.Variant.

func (Variant) DefaultIterations

func (v Variant) DefaultIterations() int

DefaultIterations returns the default iterations for the particular variant.

func (Variant) HashFunc

func (v Variant) HashFunc() algorithm.HashFunc

HashFunc returns the internal HMAC HashFunc.

func (Variant) Name

func (v Variant) Name() (s string)

Name returns the Variant name.

func (Variant) Prefix

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

Prefix returns the shacrypt.Variant prefix identifier.

func (Variant) String

func (v Variant) String() (identifier string)

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