argon2id

README

argon2id

Generate and verify password hashes using the argon2id algorithm.

Documentation

Overview

Package argon2id is used to generate and verify password hashes using the argon2id algorithm. It lightly wraps crypto/argon2 to make it a little easier to work with.

Based on https://datatracker.ietf.org/doc/rfc9106 and https://github.com/P-H-C/phc-winner-argon2

Index

• Variables
• func Hash(password string, p Params) (string, error)
• func Verify(hash, password string) error
• type Params

Examples

• Hash
• Verify

Variables

var ErrVerifyMismatch = errors.New("argon2id: password does not match the supplied hash")

ErrVerifyMismatch is returned by Verify if the hash and password don't match.

var FirstRecommended = Params{
	Passes:      1,
	Parallelism: 4,
	Memory:      2 * 1024 * 1024,
	SaltLength:  16,
	TagLength:   32,
	Rand:        rand.Reader,
}

FirstRecommended are the first recommended parameters for argon2id, based on RFC 9106. Uses 2GiB of RAM.

var SecondRecommended = Params{
	Passes:      3,
	Parallelism: 4,
	Memory:      64 * 1024,
	SaltLength:  16,
	TagLength:   32,
	Rand:        rand.Reader,
}

SecondRecommended are the second recommended parameters for argon2id if much less memory is available, based on RFC 9106. Uses 64 MiB of RAM.

Functions

func Hash

func Hash(password string, p Params) (string, error)

Hash returns an encoded argon2id hash of the given password.

Example

h, err := Hash("password", FirstRecommended)
if err != nil {
	// Couldn't hash password.
	return
}

fmt.Println(h)
// $argon2id$v=19$m=2097152,t=1,p=4$kjuwT5ohKLpyRYjRHpJrqA$fempypzcUqh3C2XnuvlAviTy6FE0SQiF3fpFVmh5Dcg

func Verify

func Verify(hash, password string) error

Verify checks an encoded hash against a password. Returns nil if the hash and password match. If they don't match, then ErrVerifyMismatch is returned.

Example

hash := "$argon2id$v=19$m=2097152,t=1,p=4$kjuwT5ohKLpyRYjRHpJrqA$fempypzcUqh3C2XnuvlAviTy6FE0SQiF3fpFVmh5Dcg"

if err := Verify(hash, "password"); errors.Is(err, ErrVerifyMismatch) {
	// Hash was decoded successfully, but hash and password don't match.
	return
} else if err != nil {
	// Some other error
	return
}

Types

type Params

type Params struct {
	// SaltLength for password hashing applications. It must have a length not
	// greater than 2^(32)-1 bytes. 16 bytes is recommended for password
	// hashing. Minimum length is 8.
	SaltLength uint32

	// Parallelism determines how many independent computational chains can be
	// run. Minimum length is 1.
	Parallelism uint8

	// Tag length must be a number of bytes from 4 to 2^(32)-1. This is the
	// length of the output bytes.
	TagLength uint32

	// Memory must be a number of kibibytes from 8*parallelism to 2^(32)-1.
	Memory uint32

	// Passes is the number of passes, which must be from 1 to 2^(32)-1.
	Passes uint32

	// Rand is the source of randomness. If this is nil, crypto/rand Reader
	// will be used.
	Rand io.Reader
}

Params are the input parameters to argon2id.