argon2

Documentation

Index

• func Check(password, encodedHash []byte, preferred *Params) (bool, bool, error)
• func EncodedHash(r io.Reader, password []byte, p Params) ([]byte, error)
• type Params
  • func Calibrate(target time.Duration, variant Variant, memory, parallelism int) (Params, time.Duration)
  • func (p *Params) IsValid() error
• type Variant

Functions

func Check

func Check(password, encodedHash []byte, preferred *Params) (bool, bool, error)

Check will check to see whether the given password matches the given encoded hash or not.

If a preferred argument is provided then the rehash return value will be set based on whether any of those parameters are different from the encoded hash's because preferred is treated as the "preferred" parameters.

The rehash return value will only be set to anything other than false on a successful check.

func EncodedHash

func EncodedHash(r io.Reader, password []byte, p Params) ([]byte, error)

EncodedHash will generate and return an encoded variant of an Argon2 hash based on the given parameters.

The encoded hash returned will follow the format: $argon2x$v=19$m=65536,t=1,p=1$salt$key.

The salt and key will be base64 encoded and the salt will be generated using a CSrand.

Types

type Params

type Params struct {
	Variant     Variant
	Time        uint32
	Memory      uint32
	Parallelism uint8
	SaltLength  uint32
	KeyLength   uint32
}

Params holds the parameters that will be used in the Argon2 key derivation functions.

A sensible starting point for Argon2id would be to set Time to 1, and Memory to 64 MiB (64 * 1024 KiB).

For Argon2i a sensible starting point would be to set Time to 3, and Memory to 32 MiB (32 * 1024 KiB).

Argon2 key derivation functions expect the memory parameter to be expressed in terms of kibibytes (KiB). That is, a memory value of 1024 is actually 1024 KiB, not 1024 bytes, as you might expect.

For example, if the memory should be set to 64 MiB then the memory field should be set to 65536. This is because 65536 KiB is the same as 64 MiB (65536 / 1024 = 64).

The parallelism parameter sets the number of threads that will be used to spread the work across. Changing this parameter will also change the final output of the encoded hash.

So even if all other parameters remain the same, just spreading the work across multiple threads will result in completely different output.

For more information see: https://golang.org/x/crypto/argon2

func Calibrate

func Calibrate(target time.Duration, variant Variant, memory, parallelism int) (Params, time.Duration)

Calibrate starts with a set of minimum hashing parameters and increases them until it hits the desired target duration.

The amount of memory should be expressed as a number of kibibytes (KiB). For example, if the memory should be set to 64 MiB then the memory parameter should be set to 65536. This is because 65536 KiB is the same as 64 MiB (65536 / 1024 = 64).

func (*Params) IsValid

func (p *Params) IsValid() error

IsValid will check to see if the current parameters are valid for use or not. If they are not valid then an error will be returned.

It's important to note that just because this function may return true, it does not mean that the given parameters are actually suitable for hashing an actual password.

The limits tested in this method are deliberately low so as to provide maximum flexibility.

type Variant

type Variant string

Variant represents the variants of an Argon2 hash.

const (
	I  Variant = "argon2i"
	ID Variant = "argon2id"
)

These are the available Argon2 variants. If you have the choice then Argon2id is recommended.