Documentation ¶
Overview ¶
Package argon2 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.
This package is a fork of golang.org/x/crypto/argon2. Changes introduced only affect package's public API. Full Argon2 functionality is exposed for the sake of completeness.
For a detailed specification of Argon2 see https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf.
If you aren't sure which function you need, use Argon2id and the parameter recommendations for your scenario. All parameter recommendations are taken from https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03#section-9.3
Index ¶
Constants ¶
const ( // Argon2d is the trade-off attack resistant version of Argon2. It uses // data-dependent memory access, which can be used for cryptocurrencies and // backend servers. Argon2d is vulnerable to side-channel attack. The // recommended parameters for non-interactive operations are time=1 and to use // the maximum available memory. Using memory=64*1024 (64MB) is a sensible // default. If using that amount of memory is not possible, then the time // parameter can be increased to compensate. Argon2d = iota // 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. The recommended parameters // for non-interactive operations are time=3 and to use the maximum available // memory. Using memory=32*1024 (32MB) is a sensible default. If using that // amount of memory is not possible, then the time parameter can be increased // to compensate. Argon2i // Argon2id is a hybrid version of Argon2 combining Argon2i and Argon2d. 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. The recommended // parameters for non-interactive operations are time=1 and to use the maximum // available memory. Using memory=64*1024 (64MB) is a sensible default. If // using that amount of memory is not possible, then the time parameter can be // increased to compensate. Argon2id )
const Version = 0x13
The Argon2 version implemented by this package.
Variables ¶
This section is empty.
Functions ¶
func DeriveKey ¶
func DeriveKey(flavor int, password, salt, secret, data []byte, time, memory uint32, threads uint8, keyLen uint32) []byte
DeriveKey derives a key from the password, salt, secret, data and cost parameters using selected argon2 flavor returning 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)
The draft RFC recommends time=1, and memory=64*1024 is a sensible number. If using that amount of memory (64 MB) is not possible in some contexts then the time parameter can be increased to compensate.
The flavor parameter specifies the flavor that will be used to derive the key. secret is optional and can be used as a constant extra parameter used for hashing that won't be stored in the database. data is also optional, it represents arbitrary extra data. The time parameter specifies the number of passes over the memory and the memory parameter specifies the size of the memory in KiB. See recommendations in documentation for each flavor if you're not sure what to use. The number of threads can be adjusted to the numbers of available CPUs. Remember to get a good random salt.
Types ¶
This section is empty.