Documentation ¶
Overview ¶
Package argon2 provides a convenience wrapper around Go's argon2 package. Currently supported only Argon2id. Argon2 was the winner of the Password Hashing Competition that makes it easier to securely derive strong keys from weak inputs (i.e. user passwords). The package provides password generation, constant-time comparison and parameter upgrading for argon2 derived keys.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultParams = &Params{
Memory: 64 * 1024,
Iterations: 3,
Parallelism: 2,
SaltLength: 16,
KeyLength: 32,
}
DefaultParams provides sensible default inputs into the argon2 function for interactive use. The default key length is 256 bits.
var ErrIncompatibleVersion = errors.New("argon2: incompatible version of argon2")
ErrIncompatibleVersion is returned when version of provided argon2 hash s incompatible with current argon2 algorithm
var ErrInvalidHash = errors.New("argon2: the encoded hash is not in the correct format")
ErrInvalidHash is returned when function failed to parse provided argon2 hash and/or given parameters.
var ErrInvalidParams = errors.New("argon2: the parameters provided are invalid")
ErrInvalidParams is returned when the cost parameters (N, r, p), salt length or derived key length are invalid.
var ErrMismatchedHashAndPassword = errors.New("argon2: the hashed password does not match the hash of the given password")
ErrMismatchedHashAndPassword is returned when a password (hashed) and given hash do not match.
Functions ¶
func CompareHashAndPassword ¶
CompareHashAndPassword compares a derived key with the possible cleartext equivalent. The parameters used in the provided derived key are used. The comparison performed by this function is constant-time. It returns nil on success, and an error if the derived keys do not match.
Example ¶
// e.g. r.PostFormValue("password") passwordFromForm := "qwerty123" // e.g. hash from database hash := "qwerty123" // Check password with a hash. Return an error if they don't match err := CompareHashAndPassword([]byte(hash), []byte(passwordFromForm)) if err != nil { log.Fatal(err) } // Do something next
Output:
func GenerateFromPassword ¶
GenerateFromPassword returns the derived key of the password using the parameters provided. The parameters are prepended to the derived key and separated by the "$" character
Example ¶
// e.g. r.PostFormValue("password") passwordFromForm := "qwerty123" // Generates a derived key with default params hash, err := GenerateFromPassword([]byte(passwordFromForm), DefaultParams) if err != nil { log.Fatal(err) } // Print the derived key - "argon2id$19$65536$3$2$R8kBdA675bqNJbhWntdlAA$X28Igb1N0MBO3IWOIPoS+JxLmhAx0KBUYe65BSEsMs8" fmt.Printf("%s\n", hash)
Output:
func GenerateRandomBytes ¶
GenerateRandomBytes returns securely generated random bytes. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller should not continue.
Types ¶
type Params ¶
type Params struct { Memory uint32 // The amount of memory used by the algorithm (kibibytes) Iterations uint32 // The number of iterations (passes) over the memory Parallelism uint8 // The number of threads (lanes) used by the algorithm SaltLength uint32 // Length of the random salt. 16 bytes is recommended for password hashing KeyLength uint32 // Length of the generated key (password hash). 16 bytes or more is recommended }
Params describes the input parameters to the argon2 key derivation function. The iterations parameter specifies the number of passes over the memory and the memory parameter specifies the size of the memory in KiB. For example memory=64*1024 sets the memory cost to ~64 MB. The number of parallelism can be adjusted to the number of available CPUs. The cost parameters should be increased as memory latency and CPU parallelism increases. Remember to get a good random salt.