Documentation
¶
Overview ¶
Package password provides secure password hashing and verification using bcrypt and Argon2id, the two algorithms recommended by OWASP for password storage.
Algorithm selection ¶
Argon2id is the primary recommendation (memory-hard, GPU-resistant). Bcrypt is provided as a widely-compatible alternative. Both produce self-describing hash strings that encode the algorithm, parameters, salt, and digest, so a stored hash carries everything needed to verify it.
Quick start ¶
// Hash a password with Argon2id (recommended).
hashed, err := password.Hash("my-secret-password", nil)
if err != nil { return err }
// Verify.
if password.Verify("my-secret-password", hashed) {
// access granted
}
// Check if a hash needs rehashing (e.g. params are outdated).
if password.NeedsRehash(hashed, nil) {
newHash, _ := password.Hash("my-secret-password", nil)
// persist newHash
}
Migrating from bcrypt to Argon2id ¶
// On next login:
if password.Verify(plain, stored) {
if password.NeedsRehash(stored, nil) {
newHash, _ := password.Hash(plain, nil)
// save newHash
}
}
Index ¶
Constants ¶
const ( // DefaultBcryptCost is the default bcrypt cost factor. // OWASP recommends a minimum of 10; 12 provides ~250ms per hash on // modern hardware. Adjust based on your hardware and latency budget. DefaultBcryptCost = 12 // DefaultArgon2Time is the default Argon2id time cost (iterations). DefaultArgon2Time = 3 // DefaultArgon2Memory is the default Argon2id memory cost in KiB. // 64 * 1024 = 64 MB. OWASP recommends a minimum of 19 MiB; 64 MiB // provides strong resistance. Adjust based on your hardware. DefaultArgon2Memory = 64 * 1024 // DefaultArgon2Threads is the default Argon2id parallelism (threads). DefaultArgon2Threads = 2 // DefaultArgon2KeyLen is the default Argon2id output key length in bytes. DefaultArgon2KeyLen = 32 // DefaultArgon2SaltLen is the default Argon2id salt length in bytes. DefaultArgon2SaltLen = 16 )
Variables ¶
var ( // ErrEmptyPassword is returned when hashing an empty password. ErrEmptyPassword = errors.New("password: password must not be empty") // ErrInvalidHash is returned when a stored hash is malformed or uses an // unknown algorithm. ErrInvalidHash = errors.New("password: invalid hash format") // ErrPasswordTooLong is returned when the password exceeds 72 bytes // (bcrypt limitation). ErrPasswordTooLong = errors.New("password: password exceeds 72 bytes for bcrypt") )
Functions ¶
func Hash ¶
Hash produces a self-describing password hash string.
By default, Argon2id is used. The returned string encodes the algorithm and all parameters so that Verify can reconstruct the computation without external configuration:
"$argon2id$v=19$m=65536,t=3,p=2$<base64-salt>$<base64-key>" "$bcrypt$<bcrypt-hash>"
Pass nil for opts to use secure defaults.
func MustHash ¶
MustHash is like Hash but panics on error. Use only in tests or initialization where a hash failure is unrecoverable.
func NeedsRehash ¶
NeedsRehash reports whether a stored hash should be recomputed with current parameters. This is true when:
- The algorithm differs from the target (default: Argon2id).
- The bcrypt cost is lower than the target.
- The Argon2id time/memory/threads are lower than the target.
Use this on login to transparently upgrade hashes to stronger params. Pass nil for opts to compare against defaults.
Types ¶
type Algorithm ¶
type Algorithm string
Algorithm identifies a password hashing algorithm.
func AlgorithmOf ¶
AlgorithmOf returns the algorithm used by a stored hash, or Algorithm("") if the hash is unrecognized.
type Options ¶
type Options struct {
// Algorithm selects the hashing algorithm. Defaults to AlgorithmArgon2id.
Algorithm Algorithm
// BcryptCost is the bcrypt cost factor (4-31). Defaults to 12.
// Only used when Algorithm == AlgorithmBcrypt.
BcryptCost int
// Argon2Time is the Argon2id time cost (iterations). Defaults to 3.
// Only used when Algorithm == AlgorithmArgon2id.
Argon2Time uint32
// Argon2Memory is the Argon2id memory cost in KiB. Defaults to 65536 (64MB).
// Only used when Algorithm == AlgorithmArgon2id.
Argon2Memory uint32
// Argon2Threads is the Argon2id parallelism. Defaults to 2.
// Only used when Algorithm == AlgorithmArgon2id.
Argon2Threads uint8
// Argon2KeyLen is the output key length in bytes. Defaults to 32.
// Only used when Algorithm == AlgorithmArgon2id.
Argon2KeyLen uint32
// Argon2SaltLen is the salt length in bytes. Defaults to 16.
// Only used when Algorithm == AlgorithmArgon2id.
Argon2SaltLen uint32
}
Options configures password hashing. Zero values use safe defaults.