Options

By default, argon2.hash will generate secure hashes according to the security recommendations by the team that develops Argon2. For password hashing, there is no need to modify them.

However, if you need, you can configure a lot of options by passing those as the second parameter of the hash function. For example, if you wish to use the Argon2d variant, with 2 ** 16 KB (64 MB) of memory and resulting in a 50 character hash, you would use:

const hash = await argon2.hash(password, {
    type: argon2.argon2d,
    memoryCost: 2 ** 16,
    hashLength: 50,
});

Here are the options you can supply and their meaning:

hashLength

The hash length is the length of the hash function output in bytes. Note that the resulting hash is encoded with Base 64, so the digest will be ~1/3 longer.

The default value is 32, which produces raw hashes of 32 bytes or digests of 43 characters.

> await argon2.hash('password')
'$argon2i$v=19$m=4096,t=3,p=1$SX5sc9gOkbvc4wum7EDYRg$3ZlnlCa8+Si4tqbHAnRqMFvWu3QfH4zysPGX7buE0mI'

> await argon2.hash('password', {hashLength: 40})
'$argon2i$v=19$m=4096,t=3,p=1$71SW0DoQwt6oBJza41+J5A$7mf4z59jvSsL3vl31B/ejqHTTNh6Xg9dW7waXzwV/DV05e6JTiuTlg'

Mind how the second hash is longer.

timeCost

The time cost is the amount of passes (iterations) used by the hash function. It increases hash strength at the cost of time required to compute.

The default value is 3.

memoryCost

The amount of memory to be used by the hash function, in KiB. Each thread (see parallelism) will have a memory pool of this size. Note that large values for highly concurrent usage will cause starvation and thrashing if your system memory gets full.

The default value is 65536, meaning a pool of 64 MiB per thread.

parallelism

The amount of threads to compute the hash on. Each thread has a memory pool with memoryCost size. Note that changing it also changes the resulting hash.

The default value is 4, meaning 4 threads are used.

type

The variant of the hash function. Argon2 has several variants with different aims:

• argon2d is faster and highly resistant against GPU attacks, which is useful for cryptocurrency
• argon2i is slower and resistant against tradeoff attacks, which is preferred for password hashing and key derivation
• argon2id is a hybrid combination of the above, being resistant against GPU and tradeoff attacks

The default is argon2id, and the types are available as attributes of the module.

> await argon2.hash('password', {type: argon2.argon2id})
'$argon2id$v=19$m=4096,t=3,p=1$dSzY4kzLGcr/+/I0YvF5mQ$jzKftP3Px0+4X1oYvSLQv8OKkM728OZjPNdgRbIUr2s'

secret

Also known as "pepper" in password hashing, additional data used in the hashing process that does not get included in the hash like the salt. It should be sufficiently random and unpredictable, and securely stored to prevent compromise. The secret must be an instance of a Buffer:

> await argon2.hash('password', {secret: Buffer.from('mysecret')})
'$argon2id$v=19$m=65536,t=3,p=4$HqToZhtkAjxwqpiY4H1eDQ$GhyTvrSAB2bxQ8RkD8w9DLrHzyEa3pf0bu+Hm158fhY'

The default is unset.

associatedData

An extra and optional non-secret binary value. The value will be included as B64 encoded in the parameters portion of the digest.

The default value is unset.

> await argon2.hash('password', {associatedData: Buffer.from('associated data')})
'$argon2i$v=19$m=4096,t=3,p=1,data=YXNzb2NpYXRlZCBkYXRh$3bxuEoDAcj2SCRtaYbfRlg$lXodFk65Jmld5unb/2SPlNXSA4Xo4YqrWRJWJIgtVX4'

Here be dragons!

The options below are reserved for highly specific uses. You should never use them for password hashing, deviating from the defaults will reduce your security!

raw

Controls whether the output is the digest (full hash with parameters) or the raw hash, prior to Base 64 encoding. If you set this option to true, you can not use verify to check the password.

The default value is false.

> await argon2.hash('password', {raw: true})
<Buffer ef f2 8b 54 79 0e f3 c1 03 35 c9 53 a7 82 27 34 02 6c 4b a7 24 e1 a0 84 db 5f 54 7c b3 43 e7 70>

version

The Argon2 version to use. Currently available are versions 1.0 (0x10) and 1.3 (0x13). You shouldn't change this, as the latest version is stronger.

The default value is 0x13 (19), for Argon2 1.3.

salt

Do NOT supply a custom salt unless you really know how it works and what it means.

The salt to protect the data against rainbow tables. You shouldn't set your own salt. (It's already stored in the hash.)

The default value is unset, which generates a cryptographically safe random salt.

saltLength

The length (in bytes) of the cryptographically secure random salt to generate.

The default value is 16, as recommended for password hashing in the argon2 specs.