README (1764B)
1 This module provides an implementation of the argon2 key derivation function as 2 described by RFC 9106. This is the recommended algorithm for password hashing in 3 Hare programs, and for deriving keys for use with other cryptographic 4 algorithms. Some thought must be given to the appropriate configuration for your 5 use case. Some general advice is provided here; if in doubt, consult the RFC. 6 7 The argon2 parameters are configured via the [[conf]] structure. To determine 8 the appropriate configuration parameters for a particular use-case, consult 9 section 4 of the RFC. Otherwise, sane defaults for common scenarios are provided 10 via [[default_conf]] and [[low_mem_conf]]; consult the docs of each 11 configuration for details. 12 13 Once a suitable configuration has been selected, the user must provide a salt. 14 This salt should be stored alongside the hash, should be unique for each 15 password, and should be random: see [[crypto::random::]]. The salt and hash 16 lengths are configurable, the recommended defaults are 16 and 32 bytes 17 respectively. 18 19 Equipped with the necessary parameters, the user may call the appropriate argon2 20 variant via [[argon2d]], [[argon2i]], or [[argon2id]]. If unsure which to use, 21 choose [[argon2id]]. The RFC is the authoratative source on the appropriate 22 argon2 variant and configuration parameters for your use-case. 23 24 This is a low-level module which implements cryptographic primitives. Direct use 25 of cryptographic primitives is not recommended for non-experts, as incorrect use 26 of these primitives can easily lead to the introduction of security 27 vulnerabilities. Non-experts are advised to use the high-level operations 28 available in the top-level [[crypto::]] module. 29 30 Be advised that Hare's cryptography implementations have not been audited.