argon2

README

Argon2 Go

This is a fork of the standard library x/crypto/argon2, exposing additional Argon2 parameters. It implements the key derivation function Argon2. Argon2 was selected as the winner of the Password Hashing Competition and can be used to derive cryptographic keys from passwords.

argon2.DeriveKey(mode, password, salt, secret, data, time, memory, threads, keyLen)

Additional parameters supported in this fork:

• mode: one of Argon2d, Argon2i, or Argon2id
• secret: commonly used to include a secret key or pepper in the hash; the secret is accessed at the application level, not stored in the database alongside the salt; an attacker who only has access to the database cannot crack any hashed passwords
• data: extra data to be fed into the hash

Documentation

Overview

Package argon2 implements the key derivation function Argon2, with extra parameters supported. This is a fork of the standard library x/crypto/argon2. It implements the key derivation function Argon2. Argon2 was selected as the winner of the Password Hashing Competition and can be used to derive cryptographic keys from passwords.

For a detailed specification of Argon2 see [1].

1. https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf
2. https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03#section-9.3
3. https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id
4. https://eprint.iacr.org/2016/759.pdf

Index

• Constants
• func DeriveKey(mode int, password, salt, secret, data []byte, time, memory uint32, ...) []byte

Constants

const Argon2d = 0

Argon2d maximizes resistance to GPU cracking attacks. It accesses the memory array in a password dependent order, which reduces the possibility of time–memory trade-off (TMTO) attacks, but introduces possible side-channel attacks.

const Argon2i = 1

Argon2i is the side-channel resistant version of Argon2. It uses data-independent memory access, which is preferred for password hashing and password-based key derivation. Argon2i requires more passes over memory than Argon2id to protect from trade-off attacks. Based on cryptanalysis from 2016 (see [4]), time > 10 (iterations) are required for 1GB of memory. For interactive password prompts where memory is constrained, this mode will be too slow to use. Argon2id is recommended instead.

const Argon2id = 2

Argon2id is a hybrid version of Argon2 combining Argon2i and Argon2d. It is recommended[3] by OWASP for normal password hashing. It uses data-independent memory access for the first half of the first iteration over the memory and data-dependent memory access for the rest. Argon2id is side-channel resistant and provides better brute- force cost savings due to time-memory tradeoffs than Argon2i

const Version = 0x13

The Argon2 version implemented by this package.

Functions

func DeriveKey

func DeriveKey(mode int, password, salt, secret, data []byte, time, memory uint32, threads uint8, keyLen uint32) []byte

DeriveKey derives a key from password, salt, secret (a.k.a key or pepper), data, and cost parameters. The mode is one of Argon2d, Argon2i, or Argon2id. You may pass nil for any of salt, secret, or data to exclude them from the hash. A byte slice of length keyLen that can be used as cryptographic key. The CPU cost and parallelism degree must be greater than zero.

For example, you can get a derived key for e.g. AES-256 (which needs a 32-byte key) by doing:

key := argon2.DeriveKey(argon2.Argon2id, []byte("some password"), salt, nil, nil, 1, 64*1024, 4, 32)

OWASP publishes recommendations[3] for sensible cost parameters for password hashing. The original draft RFC also contains recommendations, though they may not be up-to-date. For normal password hashing, a salt, secret, and key of length 16 bytes is sufficient.

The time parameter specifies the number of passes over the memory and the memory parameter specifies the size of the memory in KiB. For example memory=64*1024 sets the memory cost to ~64 MB. The number of threads can be adjusted to the numbers of available CPUs. The cost parameters should be increased as memory latency and CPU parallelism increases. Remember to get a good random salt.