Documentation
¶
Overview ¶
Package gosecure provides hashing, checking and associated functions for passphrases and JWT tokens. Tokens allow for session data to be passed in by a client having been encoded earlier. With both hashes and tokens secure cryptographic functions are used. All functions can be called in a time boxed fashion with guarantees about minimum execution time using the Timebox function.
Index ¶
Examples ¶
Constants ¶
const ( MinimumLength = 8 MinimumTime = time.Millisecond * 100 )
Default minimums for password length and comparison time.
Variables ¶
var ErrFailedToHashArgon2Id = errors.New("hash failure")
ErrFailedToHashArgon2Id is returned if the Argon2id hashing algorithm panics.
var ErrMismatchedPassphrase = errors.New("mismatched passphrase")
ErrMismatchedPassphrase is returned if a passphrase and hash do not match.
var ErrPassphraseTooShort = errors.New("passphrase too short")
ErrPassphraseTooShort is returned if a passphrase to be hashed is shorter that Authenticator.MinimumLength.
Functions ¶
func GUID ¶ added in v2.2.0
func GUID() string
GUID generator based on V4 UUIDs. GUID will panic if there is an error reading from rand.Reader since this means the IDs being generated cannot be unique.
Example ¶
guid := gosecure.GUID() // Replace non `-` characters with an * guid = regexp.MustCompile(`[^-]`).ReplaceAllString(guid, "*") fmt.Println(guid)
Output: ********-****-****-****-************
func GUIDFrom ¶ added in v2.2.0
GUIDFrom uses the given reader to generate the GUID. Used primarily for testing. Will panic if there is an error reading from the reader.
func Int ¶
func Int[T Integers](n T) T
Int will take an integer and generate a cryptographically secure random number x such that 0 >= x < n. Int will panic on any errors.
Example ¶
i := gosecure.Int(5) fmt.Println(i < 5)
Output: true
Types ¶
type Algorithm ¶
type Algorithm interface {
// Hash a passphrase. An error is returned if there is a problem creating
// the hash.
Hash(passphrase string) ([]byte, error)
// Compare a passphrase to a previously hashed passphrase. An error is
// returned if the passphrase and hash don't match, or there is an issue
// comparing the two.
Compare(passphrase string, hash []byte) error
}
Algorithm that allows for hashing of passphrases, and comparison of passphrases against hashes.
type Argon2id ¶
Argon2id hashing algorithm. If no parameters are defined then the default are used.
func (*Argon2id) Compare ¶
Compare a passphrase to a hash. If the passphrase matches the hash then this function will return nil. A mismatched passphrase will result in ErrMismatchedPassphrase. All other errors indicate something went wrong comparing the hash and passphrase.
func (*Argon2id) Hash ¶
Hash a passphrase. The argon2id.DefaultParams are used if no Params are set.
func (*Argon2id) Register ¶ added in v2.2.0
func (a *Argon2id) Register(opts *gofigure.Configuration)
Register Argon2id with gofigure.
Example ¶
var settings struct{ Argon2id gosecure.Argon2id }
config := gofigure.NewConfiguration("EXAMPLE")
settings.Argon2id.Register(config)
// Ordinarily this would be config.Parse().
err := config.ParseUsing([]string{"--argon2id-parallelism", "2"})
if err != nil {
fmt.Println(config.Format(err))
fmt.Println(config.Usage())
}
fmt.Println(*settings.Argon2id.Params)
Output: {2 1 2 16 32}
type Authenticator ¶
type Authenticator struct {
// MinimumTime is the shortest amount of time the Authenticator will take
// to compare a passphrase and hash. This helps to mitigate timing attacks.
MinimumTime time.Duration
// MinimumLength is the shortest passphrase the Authenticator will allow
// when hashing passphrases.
MinimumLength int
// contains filtered or unexported fields
}
Authenticator used to hash passphrases and compare passphrases against hashes. The Authenticator can use multiple comparison algorithms to allow algorithm migration.
func NewAuthenticator ¶
func NewAuthenticator(algorithm Algorithm) *Authenticator
NewAuthenticator returns a new Authenticator type with the hash and compare algorithms set to the given algorithm. If an invalid or nil algorithm is provided then the algorithm will default to Bcrypt.
Example ¶
p := gosecure.NewAuthenticator(&gosecure.Bcrypt{})
h, err := p.Hash("password")
if err != nil {
fmt.Println(err)
}
start := time.Now()
err = p.Compare("password", h)
d := time.Since(start)
switch {
case err != nil:
fmt.Println(err)
case d < gosecure.MinimumTime:
fmt.Println("Finished too early")
default:
fmt.Println("Passwords match")
}
Output: Passwords match
func (*Authenticator) Add ¶
func (a *Authenticator) Add(algorithm Algorithm)
Add an Algorithm to the set of comparison algorithms.
type Bcrypt ¶
type Bcrypt struct {
Cost int
}
Bcrypt hashing algorithm.
func (*Bcrypt) Compare ¶
Compare a passphrase to a previously hashed passphrase. If the passphrase matches the hash then this function will return nil. A mismatched passphrase will result in ErrMismatchedPassphrase. All other errors indicate something went wrong comparing the hash and passphrase.
func (*Bcrypt) Hash ¶
Hash a passphrase using the cost set on this Bcrypt instance. The actual cost used is as per the golang.org/x/crypto/bcrypt documentation.
func (*Bcrypt) Register ¶ added in v2.2.0
func (b *Bcrypt) Register(opts *gofigure.Configuration)
Register Bcrypt with gofigure.
Example ¶
var settings struct{ Bcrypt gosecure.Bcrypt }
config := gofigure.NewConfiguration("EXAMPLE")
settings.Bcrypt.Register(config)
// Ordinarily this would be config.Parse().
err := config.ParseUsing([]string{"--bcrypt-cost", "100"})
if err != nil {
fmt.Println(config.Format(err))
fmt.Println(config.Usage())
}
fmt.Println(settings.Bcrypt)
Output: {100}
Source Files