Documentation
¶
Index ¶
Constants ¶
const ( // ErrInvalidHash in returned by ComparePasswordAndHash if the provided // hash isn't in the expected format. ErrInvalidHash = utils.Error("argon2id: hash is not in the correct format") // ErrIncompatibleVersion is returned by ComparePasswordAndHash if the // provided hash was created using a different version of Argon2. ErrIncompatibleVersion = utils.Error("argon2id: incompatible version of argon2") )
Variables ¶
This section is empty.
Functions ¶
func Argon2IdCreateHash ¶
func Argon2IdCreateHash(c *Argon2Config, password string) (string, error)
Argon2IdCreateHash generates an Argon2id hash from the given password using the provided configuration. The hash is returned in the standard format: $argon2id$v=19$m=65536,t=4,p=8$salt$hash
The function generates a cryptographically secure random salt and includes all parameters in the hash for self-contained verification.
func Argon2IdNeedsRehash ¶
func Argon2IdNeedsRehash(c *Argon2Config) bool
Argon2IdNeedsRehash checks if a hash was created with different parameters than the current default configuration. This is useful for upgrading hashes when security parameters are updated.
Returns true if any parameter differs from the current defaults.
Types ¶
type Argon2Config ¶
type Argon2Config struct {
// Memory is the amount of memory to use in KiB (e.g., 64*1024 = 64MB).
// Higher values increase security but also computational cost.
Memory uint32 `json:"memory"`
// Iterations is the number of passes over the memory.
// Also known as time cost. Higher values increase security.
Iterations uint32 `json:"iterations"`
// Parallelism is the number of threads to use.
// Typically set to the number of available CPU cores.
Parallelism uint8 `json:"parallelism"`
// SaltLength is the length of the random salt in bytes.
// Recommended minimum is 16 bytes.
SaltLength uint32 `json:"saltLength"`
// KeyLength is the length of the generated hash in bytes.
// Recommended minimum is 32 bytes.
KeyLength uint32 `json:"keyLength"`
}
Argon2Config holds the parameters for Argon2id password hashing. These parameters control the computational cost and security level.
func Argon2IdComparePassword ¶
func Argon2IdComparePassword(password, hash string) (bool, *Argon2Config, error)
Argon2IdComparePassword verifies that a password matches the given Argon2id hash. It uses constant-time comparison to prevent timing attacks.
Returns:
- bool: true if the password matches the hash
- *Argon2Config: the configuration used to create the hash (useful for rehashing)
- error: any error during hash parsing or comparison
The configuration is returned even on failed matches to allow checking if rehashing is needed after a successful authentication.
Example:
valid, cfg, err := Argon2IdComparePassword(password, hash)
if err != nil {
return err
}
if valid && Argon2IdNeedsRehash(cfg) {
// Generate new hash with updated parameters
}
func Argon2IdDecodeHash ¶
func Argon2IdDecodeHash(hash string) (*Argon2Config, []byte, []byte, error)
Argon2IdDecodeHash parses an Argon2id hash string and extracts the configuration parameters, salt, and hash key.
The expected format is: $argon2id$v=19$m=65536,t=4,p=8$salt$hash
Returns:
- *Argon2Config: The parameters used to create the hash
- []byte: The salt
- []byte: The hash key
- error: ErrInvalidHash if format is incorrect, ErrIncompatibleVersion if version mismatch
func NewArgon2IdConfig ¶
func NewArgon2IdConfig() *Argon2Config
NewArgon2IdConfig returns the default Argon2id configuration with:
- Memory: 64MB (64*1024 KiB)
- Iterations: 4
- Parallelism: Number of CPU cores
- Salt length: 16 bytes
- Key length: 32 bytes
type PasswordHasher ¶ added in v0.6.1
type PasswordHasher interface {
// Generate creates a secure hash from the given password.
// The implementation should generate a random salt and include
// all parameters needed for verification in the returned hash string.
Generate(password string) (string, error)
// Verify checks if the given password matches the hash.
// Returns:
// - bool: true if the password matches the hash
// - RehashFn: non-nil if the hash needs updating with new parameters
// - error: any error that occurred during verification
//
// If the password is valid but the hash was created with outdated
// parameters, the RehashFn should be called to generate a new hash.
Verify(password, hash string) (bool, RehashFn, error)
}
PasswordHasher defines the interface for password hashing implementations. Implementations should use secure, modern hashing algorithms like Argon2, bcrypt, or scrypt.
func NewArgon2Hasher ¶ added in v0.6.1
func NewArgon2Hasher(cfg *Argon2Config) (PasswordHasher, error)
NewArgon2Hasher creates a new PasswordHasher using the Argon2id algorithm. If cfg is nil, it uses the default configuration from NewArgon2IdConfig() with 64MB memory, 4 iterations, and parallelism based on CPU cores.
Source Files