argon2id

README

argon2id
========

argon2id is a library for generating and verifying hashes using the Argon2 key
derivation function. It is a thin wrapper around the argon2[1] package that
is maintained in /x/crypto.

The API is inspired by the bcrypt[2] package - also found in /x/crypto.

[1]: https://pkg.go.dev/golang.org/x/crypto/argon2
[2]: https://pkg.go.dev/golang.org/x/crypto/bcrypt

Documentation

Overview

Package argon2id provides utility functions for generating and verifying hashes using the Argon2 key derivation function.

Index

• Constants
• Variables
• func CompareHashAndPassword(hashedPassword, password []byte) error
• func GenerateFromPassword(password []byte, parameters Parameters) ([]byte, error)
• type Parameters
  • func OWASPMinimumParameters() Parameters
  • func UseParameters(iterations uint32, memory uint32, parallelism uint8, keyLength uint32, ...) Parameters

Constants

const (
	KiB = 1
	MiB = 1024 * KiB
	GiB = 1024 * MiB
)

Reasonable memory magnitudes. GiB is the largest defined magnitude as the largest amount of memory that Argon2id can use is 3999 GiB.

const Version = argon2.Version

The Argon2 version that this library uses.

Variables

var ErrBadVersion = errors.New("argon2id: hashedPassword was generated with another version of argon2")

The error returned from CompareHashAndPassword when a hashed password was generated with a different version of the argon2 key derivation function.

var ErrInvalidHash = errors.New("argon2id: hashedPassword is not a valid argon2id hash")

The error returned from CompareHashAndPassword when a hashed password is not a valid argon2id hash. This could be for a multitude of reasons, such as one or more of the parameters being invalid (out of range), the key or salt not being correctly encoded base64 values, or the hash being unparsable.

var ErrMismatchedHashAndPassword = errors.New("argon2id: hashedPassword is not the hash of the given password")

The error returned from CompareHashAndPassword when a password and hash do not match.

Functions

func CompareHashAndPassword

func CompareHashAndPassword(hashedPassword, password []byte) error

CompareHashAndPassword compares an Argon2id hashed password with it's possible plaintext equivalent. Returns nil on success, or an error on failure.

func GenerateFromPassword

func GenerateFromPassword(password []byte, parameters Parameters) ([]byte, error)

GenerateFromPassword returns the Argon2id hash of the password based on the given configuration.

Types

type Parameters

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

Parameters defines the input parameters required by the Argon2id key derivation function.

func OWASPMinimumParameters

func OWASPMinimumParameters() Parameters

OWASPMinimumParameters will return a new Parameters instance that adheres to the OWASP suggestions1 for the minimum parameters as of 2024/09/13. Because OWASP doesn't provide values for the salt and key length, these have been set at 128 and 256 bits respectively.

func UseParameters

func UseParameters(
	iterations uint32,
	memory uint32,
	parallelism uint8,
	keyLength uint32,
	saltLength uint32,
) Parameters

UseParameters will return a new Parameters instance that can be used when deriving keys from a password. It will panic if the iterations, parallelism or key length are 0.