Geralt
Search…
Password hashing

Purpose

Argon2id is a memory-hard password hashing and password-based key derivation function (KDF). It takes the following parameters:
  • A password.
  • A 128-bit random salt.
  • An iteration count.
  • A memory size in bytes.
  1. 1.
    Set the iteration count to 3.
  2. 2.
    Set the memory size as high as possible (minimum of 64 MiB) for a reasonable delay (e.g. 0.1 seconds to 1 second) on the type of device your application will run on.
  3. 3.
    If the delay is lower than you would like, increase the iterations.
See the Notes for some example parameters.

Usage

DeriveKey

Fills a span with output keying material computed from a password, a random salt, an iteration count, and a memory size in bytes.
Argon2id.DeriveKey(Span<byte> outputKeyingMaterial, ReadOnlySpan<byte> password, ReadOnlySpan<byte> salt, int iterations, int memorySize)

Exceptions

outputKeyingMaterial has a length less than MinKeySize.
salt has a length not equal to SaltSize.
iterations is less than MinIterations.
memorySize is less than MinMemorySize.
Insufficient memory to perform key derivation.

ComputeHash

Fills a span with a password hash computed from a password, an iteration count, and a memory size in bytes.
Argon2id.ComputeHash(Span<byte> hash, ReadOnlySpan<byte> password, int iterations, int memorySize)

Exceptions

hash has a length not equal to MaxHashSize.
iterations is less than MinIterations.
memorySize is less than MinMemorySize.
Insufficient memory to perform password hashing.

VerifyHash

Verifies that a password hash is correct for a given password. It returns true if the hash is valid and false otherwise.
Argon2id.VerifyHash(ReadOnlySpan<byte> hash, ReadOnlySpan<byte> password)

Exceptions

hash has a length less than MinHashSize or greater than MaxHashSize.

NeedsRehash

Determines if a password hash matches the expected iteration count and memory size. It returns true if the hash does not match and false if the hash matches.
Argon2id.NeedsRehash(ReadOnlySpan<byte> hash, int iterations, int memorySize)

Exceptions

hash has a length less than MinHashSize or greater than MaxHashSize.
iterations is less than MinIterations.
memorySize is less than MinMemorySize.
The password hash is invalid.

Notes

The best defence against password cracking will always be to use strong passwords. For example, diceware with 6+ words.
  • Interactive scenario (e.g. online login): 50-100 ms.
  • Semi-interactive scenario (e.g. file encryption): 250-1,000 ms.
  • Non-interactive (e.g. disk encryption): 1,500-5,000 ms.
Here are some example parameters for different scenarios:
Source
Iterations
Memory (bytes)
*Delay (ms)
libsodium's interactive
2
67108864​
51
RFC second recommended option
3
67108864​
72
libsodium's moderate
3
268435456
314
libsodium's sensitive
4
1073741824
1,745
*These delays are for my desktop (a gaming PC). You should perform benchmarks on a typical device for your application using BenchmarkDotNet.
More memory is better than more iterations. However, you will need to increase the iterations in most cases because there should be a limit on how much memory your application uses.
Too high of an iteration count/memory size on a server could lead to denial of service (DoS) attacks. You can do client-side password hashing as well as server-side password hashing to help, sometimes called server relief.
The parallelism is always 1 for deriving keys/hashes in libsodium. However, hashes with a parallelism greater than 1 can be verified.
Libsodium also supports Argon2i, which is more side-channel resistant but less GPU resistant. However, Geralt only supports Argon2id because it is the mandatory and recommended variant in the RFC.
Copy link
On this page
Purpose
Usage
DeriveKey
ComputeHash
VerifyHash
NeedsRehash
Notes