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.
For a detailed specification of Argon2 see [1].
If you aren't sure which function you need, use Argon2id (IDKey) and the parameter recommendations for your scenario.
Argon2i ¶
Argon2i (implemented by Key) 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 (taken from [2]) for non-interactive operations are time=3 and to use the maximum available memory.
Argon2id ¶
Argon2id (implemented by IDKey) 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 (taken from [2]) are time=1 and to use the maximum available memory.
[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
Index ¶
- Constants
- Variables
- func ComparePasswordAndHash(password, secret, hash string) (match bool, err error)
- func CreateHash(password, secret string, params *Params) (hash string, err error)
- func IDCreateHash(password, secret string, params *Params) (hash string, err error)
- func IDKey(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte
- func IDKeyWithSecret(password, salt, secret []byte, time, memory uint32, threads uint8, ...) []byte
- func Key(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte
- func KeyWithSecret(password, salt, secret []byte, time, memory uint32, threads uint8, ...) []byte
- type Params
Constants ¶
const Version = 0x13
The Argon2 version implemented by this package.
Variables ¶
var ( // ErrInvalidHash is returned by ComparePasswordAndHash if the provided // hash isn't in the expected format. ErrInvalidHash = errors.New("argon2: hash is not in the correct format") // ErrIncompatibleVariant is returned by ComparePasswordAndHash if the // provided hash was created using a unsupported variant of Argon2. // Currently only argon2id is supported by this package. ErrIncompatibleVariant = errors.New("argon2: incompatible variant of argon2") // ErrIncompatibleVersion is returned by ComparePasswordAndHash if the // provided hash was created using a different version of Argon2. ErrIncompatibleVersion = errors.New("argon2: incompatible version of argon2") )
var DefaultParams = &Params{
Memory: 64 * 1024,
Iterations: 1,
Parallelism: 2,
SaltLength: 16,
KeyLength: 32,
}
DefaultParams provides some sane default parameters for hashing passwords.
Follows recommendations given by the Argon2 RFC: "The Argon2id variant with t=1 and maximum available memory is RECOMMENDED as a default setting for all environments. This setting is secure against side-channel attacks and maximizes adversarial costs on dedicated brute-force hardware."
The default parameters should generally be used for development/testing purposes only. Custom parameters should be set for production applications depending on available memory/CPU resources and business requirements.
Functions ¶
func ComparePasswordAndHash ¶
ComparePasswordAndHash performs a constant-time comparison between a plain-text password and Argon2 hash, using the parameters, secret and salt contained in the hash. It returns true if they match, otherwise it returns false.
func CreateHash ¶
CreateHash generates an Argon2i password hash using the provided password, secret, and parameters. It returns the generated hash as a string and any error encountered.
The function takes the user's password, a secret for additional security, and a Params struct containing the parameters for key derivation. It generates a random salt and derives a key using the Argon2i key derivation function.
Parameters:
- password: The user's password.
- secret: An additional secret used for key derivation.
- params: A Params struct containing key derivation parameters.
Returns:
- hash: The generated Argon2i password hash.
- err: Any error encountered during hash generation.
The returned hash follows the format used by the Argon2 reference C implementation and contains the base64-encoded Argon2i derived key prefixed by the salt and parameters. It looks like this:
$argon2i$v=19$m=65536,t=1,p=2$Ell6DALdx5M3PMaNxPsFyA$VTeuPaGQW621unpzV0zHKT8S4xRir8djGSY63vsYb7U
func IDCreateHash ¶
IDCreateHash generates an Argon2id password hash using the provided password, secret, and parameters. It returns the generated hash as a string and any error encountered.
The function takes the user's password, a secret for additional security, and a Params struct containing the parameters for key derivation. It generates a random salt and derives a key using the Argon2id key derivation function.
Parameters:
- password: The user's password.
- secret: An additional secret used for key derivation.
- params: A Params struct containing key derivation parameters.
Returns:
- hash: The generated Argon2id password hash.
- err: Any error encountered during hash generation.
The returned hash follows the format used by the Argon2 reference C implementation and contains the base64-encoded Argon2id derived key prefixed by the salt and parameters. It looks like this:
$argon2id$v=19$m=65536,t=1,p=2$FmIYUI9SfLj+xHJJsM3JXw$DI8bBB2wHgOFwWVXXUSjmwRMeh/1pVVu5PDbsjoFtYE
func IDKey ¶
IDKey derives a key from the password, salt, and cost parameters using Argon2id 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.IDKey([]byte("some password"), salt, 1, 64*1024, 4, 32)
The draft RFC recommends[2] 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 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.
func IDKeyWithSecret ¶
func IDKeyWithSecret(password, salt, secret []byte, time, memory uint32, threads uint8, keyLen uint32) []byte
IDKeyWithSecret adds an extra layer of security on top of the existing IDKey function by including an additional secret.
func Key ¶
Key derives a key from the password, salt, and cost parameters using Argon2i 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.Key([]byte("some password"), salt, 3, 32*1024, 4, 32)
The draft RFC recommends[2] time=3, and memory=32*1024 is a sensible number. If using that amount of memory (32 MB) is not possible in some contexts then the time parameter can be increased to compensate.
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=32*1024 sets the memory cost to ~32 MB. The number of threads can be adjusted to the number of available CPUs. The cost parameters should be increased as memory latency and CPU parallelism increases. Remember to get a good random salt.
Types ¶
type Params ¶
type Params struct { // The amount of memory used by the algorithm (in kibibytes). Memory uint32 // The number of iterations over the memory. Iterations uint32 // The number of threads (or lanes) used by the algorithm. // Recommended value is between 1 and runtime.NumCPU(). Parallelism uint8 // Length of the random salt. 16 bytes is recommended for password hashing. SaltLength uint32 // Length of the generated key. 16 bytes or more is recommended. KeyLength uint32 }
Params describes the input parameters used by the Argon2id algorithm. The Memory and Iterations parameters control the computational cost of hashing the password. The higher these figures are, the greater the cost of generating the hash and the longer the runtime. It also follows that the greater the cost will be for any attacker trying to guess the password. If the code is running on a machine with multiple cores, then you can decrease the runtime without reducing the cost by increasing the Parallelism parameter. This controls the number of threads that the work is spread across. Important note: Changing the value of the Parallelism parameter changes the hash output.
For guidance and an outline process for choosing appropriate parameters see https://tools.ietf.org/html/draft-irtf-cfrg-argon2-04#section-4