Derive Hash based on Password. This predicate is
similar to
crypto_data_hash/3 in
that it derives a hash from given data. However, it is tailored for the
specific use case of
passwords. One essential distinction is that for this use case,
the derivation of a hash should be as slow as possible to
counteract brute-force attacks over possible passwords.
Another important distinction is that equal passwords must yield,
with very high probability, different hashes. For this reason,
cryptographically strong random numbers are automatically added to the
password before a hash is derived.
Hash is unified with an atom that contains the computed
hash and all parameters that were used, except for the password. Instead
of storing passwords, store these hashes. Later, you can verify the
validity of a password with crypto_password_hash/2,
comparing the then entered password to the stored hash. If you need to
export this atom, you should treat it as opaque ASCII data with up to
255 bytes of length. The maximal length may increase in the future.
Admissible options are:
- algorithm(+Algorithm)
- The algorithm to use. Currently, the only available algorithms are
pbkdf2-sha512
(the default) and bcrypt.
- cost(+C)
- C is an integer, denoting the binary logarithm of the number
of iterations used for the derivation of the hash. This means
that the number of iterations is set to 2
^C.
Currently, the default is 17, and thus more than one hundred thousand
iterations. You should set this option as high as your server and users
can tolerate. The default is subject to change and will likely increase
in the future or adapt to new algorithms.
- salt(+Salt)
- Use the given list of bytes as salt. By default, cryptographically
secure random numbers are generated for this purpose. The default is
intended to be secure, and constitutes the typical use case of this
predicate.
Currently, PBKDF2 with SHA-512 is used as the hash derivation
function, using 128 bits of salt. All default parameters, including the
algorithm, are subject to change, and other algorithms will also become
available in the future. Since computed hashes store all parameters that
were used during their derivation, such changes will not affect the
operation of existing deployments. Note though that new hashes will then
be computed with the new default parameters.
- See also
- crypto_data_hkdf/4 for
generating keys from Hash.
