Struct argon2_kdf::Hasher

pub struct Hasher<'a> { /* private fields */ }

A builder for a hash. Parameters for hashing, such as

Implementations

impl<'a> Hasher<'a>

pub fn new() -> Self

Create a new Hasher with default values.

This provides some reasonable defaults, but it is recommended that you tinker with these parameters to find the best settings for your application. The more resources the hashing requires, the stronger the hash. Increase the memory cost (and perhaps the parallelization factor) as high as your application can afford, then likewise raise the iteration count.

Unless you are absolutely positive you want to use a different algorithm, use the default argon2id algorithm for password hashing and key derivation.

The defaults are as follows:

• Algorithm: Argon2id
• Salt Length: 16 bytes
• Hash Length: 32 bytes
• Iterations: 18
• Memory Cost: 62500 kibibytes (equal to 64 megabytes)
• Parallelization Factor: 1 thread

Hasher allows for a secret, sometimes called a “pepper,” to be mixed with the password before hashing. Hasher can be used securely without a secret, though high-security applications might consider using one.

pub fn algorithm(self, alg: Algorithm) -> Self

Specifies the hashing algorithm to use.

The Argon2 spec consist of 3 different algorithms: one that aims to be resistant to GPU cracking attacks (argon2d), one that aims to be resistant to side-channel attacks (argon2i), and a hybrid algorithm that aims to be resistant to both types of attacks. See https://en.wikipedia.org/wiki/Argon2 for more information.

Argon2id is a good default. The other algorithms should only be used in rare cases, preferably only when a cryptography expert can validate that using one of the other two algorithms is safe.

pub fn custom_salt(self, salt: &'a [u8]) -> Self

When left unspecified, a salt is generated using a cryptographically-secure random number generator. In most cases, this function should not be used. Only use this function if you are trying to generate a hash deterministically with a known salt and a randomly generated salt will not suffice.

pub fn salt_length(self, salt_len: u32) -> Self

The length of the salt for the hash, in bytes. Using salt that is too short can lower the strength of the generated hash. 16 bytes is a reasonable default salt length.

If a salt is specified manually using [custom_salt()], the length of the provided salt will override the length specified here.

pub fn hash_length(self, hash_len: u32) -> Self

The length of the resulting hash, in bytes.

Short hashes can be insecure. The shorter the hash, the greater the chance of collisions. A 32-byte hash should be plenty for any application.

Note that the length of the hash string will be different; the hash string specifies parameters and the salt used to generate the hash. The hash is base64-encoded in the hash string, so even the hash itself is longer in the hash string than the specified number of bytes.

A hash is just an array of bytes, whereas a hash string looks something like this:

$argon2id$v=19$m=62500,t=18,p=2$AQIDBAUGBwg$ypJ3pKxN4aWGkwMv0TOb08OIzwrfK1SZWy64vyTLKo8

pub fn iterations(self, iterations: u32) -> Self

The number of times the hashing algorithm is repeated in order to slow down the hashing and thwart those pesky hackers.

pub fn memory_cost_kib(self, cost: u32) -> Self

The amount of memory required to compute a hash. This is where a lot of the magic of Argon2 happens. By setting a hard memory requirement for generating a hash, brute-forcing a password becomes infeasable even for well-funded adversaries with access to a lot of processing power.

Set this parameter as high as you can afford to. Be cautious setting this lower than 62500 KiB (64 MB). If reasonable, increase this to 125000 KiB (128 MB) or 250000 KiB (256 MB) (or even higher were security is critical).

pub fn threads(self, threads: u32) -> Self

The number of CPU threads required to generate a hash. If this is set higher than the total number of logical CPU cores on a given machine, hashing may fail or take an astronomically long time to generate on said machine.

While increasing the thread count does strengthen the hash, it is impractical to raise this parameter for some applications. Aim to increase the memory cost before increasing the thread count. With a high memory cost, just 1 thread can still provide excellent security.

pub fn secret(self, secret: Secret<'a>) -> Self

A secret that mixes with a password (and a salt) to create a hash. This is sometimes referred to as a “pepper.”

This secret is not necessary to generate strong hashes, though high-security applications might consider using a secret. Many argon2 libraries don’t expose this parameter (because it isn’t necessary), so using a secret can limit interoperability with other languages/libraries.

A 32-byte key is recommended. Do not use an alphanumeric password or passphrase; the entrophy of a 32-character password is much lower than the entrophy of a 32-byte key. This key should be generated with a cryptographically-secure random number generator and stored securely.

pub fn hash(self, password: &str) -> Result<Hash, Argon2Error>

Consumes the Hasher and returns a hash.

This is an expensive operation. For some appliations, it might make sense to move this operation to a separate thread using std::thread or something like the Rayon crate to avoid blocking main threads.

Trait Implementations

impl<'a> Clone for Hasher<'a>

fn clone(&self) -> Hasher<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Hasher<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for Hasher<'a>

fn default() -> Self

Create a new Hasher with default values.

This provides some reasonable defaults, but it is recommended that you tinker with these parameters to find the best settings for your application. The more resources the hashing requires, the stronger the hash. Increase the memory cost (and perhaps the parallelization factor) as high as your application can afford, then likewise raise the iteration count.

Unless you are absolutely positive you want to use a different algorithm, use the default argon2id algorithm for password hashing and key derivation.

The defaults are as follows:

• Algorithm: Argon2id
• Salt Length: 16 bytes
• Hash Length: 32 bytes
• Iterations: 18
• Memory Cost: 62500 kibibytes (equal to 64 megabytes)
• Parallelization Factor: 1 thread

Hasher allows for a secret, sometimes called a “pepper,” to be mixed with the password before hashing. Hasher can be used securely without a secret, though high-security applications might consider using one.