Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

Argon2 Hashing

important

When using this, please make sure to run the calibration CLI command to find the right settings for your hardware.

Algorithm settings#

password_hashing_alg#

This setting chooses which password hashing algorithm to use. For using Argon2, set this to ARGON2.

argon2_iterations (Default is 1)#

This controls how much CPU processing power is used during hashing. The higher the value, the more processing power, and hence the more time each hash takes.

argon2_memory_kb (Default is 87795 or 85 mb)#

The amount of memory (RAM) that each hash takes. The higher this is, the harder it will be to crack hashes offline, and the longer the algorithm will take.

argon2_parallelism (Default is 2)#

This is the number of threads the algorithm uses during hashing. The higher this is, the harder it would be to crack passwords offline using multile cores.

The value of this should be equal to the number of virtual cores (or twice the number of physical cores) available in the system.

argon2_hashing_pool_size (Default is 1)#

This is the maximum number of concurrent hashes that will be done by the core. A value of 1 means that the core will do only one hash at one point in time, other requests for hashing will be queued up and wait for their turn.

example

If each hash takes 300 milliseconds, a value of 1 here would entail ~ a max of 3 hashes per second (1000 ms / 300 ms). A value of 2 here would entail a max of 6 hashes per second (1000 ms / 300 ms)*2.

Password hashing is carried out during sign in, sign up and password reset flows, therefore, you can set this value according to the target time per hash and how many sign ups / in you would expect per second.

Changing settings#

docker run \
    -p 3567:3567 \
    -e PASSWORD_HASHING_ALG=ARGON2 \
    -e ARGON2_ITERATIONS=1 \
    -e ARGON2_MEMORY_KB=87795 \
    -e ARGON2_PARALLELISM=2 \
    -e ARGON2_HASHING_POOL_SIZE=1 \
    -d registry.supertokens.io/supertokens/supertokens-<db_name>
note

Changing settings will not affect older passwords. Older passwords will continue to be verified using the same settings as the ones when they were created.

Calibration to your hardware#

note
  • This is only applicable for self hosted users. For managed service users, we have already calibrated the params based on our hardware.
  • It can take several minutes for this algorithm to run.

To find the optimal setting for your hardware, you can run the hashingCalibrate command via our CLI. This command takes a few params:

  • --with_alg:
    • The value of this should be argon2
    • Compulsory param
  • --with_time_per_hash_ms:
    • This is the target time per hash (in milliseconds) that we want to achieve.
    • The default value is 300.
  • --with_argon2_hashing_pool_size:
    • This is the number of concurrent hashes to run. This will affect how much memory is to be consumed per hash.
    • The default value is 1
  • --with_argon2_max_memory_mb:
    • This is the maximum amount of memory (RAM) that should be consumed by the core for password hashing. The amount of memory per password hash will be with_argon2_max_memory_mb / with_argon2_hashing_pool_size.
    • The default value is 1024.
  • --with_argon2_parallelism:
    • This is the number of threads that should be used by argon2. The higher this is, the harder it will be to crack passwords offline.
    • The default value is 2*number of cores
docker run registry.supertokens.io/supertokens/supertokens-<db_name> supertokens hashingCalibrate --with_alg=argon2

The above will produce an output like:

====Input Settings====

-> Target time per hash (--with_time_per_hash_ms): 300 MS
-> Number of max concurrent hashes (--with_argon2_hashing_pool_size): 1
-> Max amount of memory to consume across 1 concurrent hashes (--with_argon2_max_memory_mb): 1024 MB
-> Argon2 parallelism (--with_argon2_parallelism): 4


====Running algorithm====

Current argon2 settings
-> memory: 1024 MB
-> iterations: 1
Calculating average hashing time....
..................................................Took 574 MS per hash


Adjusting memory to reach target time.

Current argon2 settings
-> memory: 972 MB
-> iterations: 1
Calculating average hashing time....
..................................................Took 529 MS per hash


Adjusting memory to reach target time.

Current argon2 settings
-> memory: 924 MB
-> iterations: 1
Calculating average hashing time....
..................................................Took 494 MS per hash



<....Truncated....>



Adjusting memory to reach target time.

Current argon2 settings
-> memory: 367 MB
-> iterations: 2
Calculating average hashing time....
..................................................Took 319 MS per hash


Adjusting memory to reach target time.

Current argon2 settings
-> memory: 348 MB
-> iterations: 2
Calculating average hashing time....
..................................................Took 303 MS per hash


====Final values====
Average time per hash is: 303 MS

argon2_memory_kb: 357104 (348 MB)
argon2_iterations: 2
argon2_parallelism: 4
argon2_hashing_pool_size: 1

====================
You should use these as docker env variables or put them in the config.yaml file in the SuperTokens installation directory.

The contents of the ====Final values==== gives you the values of the parameters to provide to the core.

The algorithm starts with the highest amount of memory per hash (= with_argon2_max_memory_mb/with_argon2_hashing_pool_size) and 1 iteration. It calculates the current average hashing time by simulating several hashes concurrently (based on the value of with_argon2_hashing_pool_size). If the hashing time is greater than the target time, it reduces the memory by 5%. If it's lesser than the target time, it increases the number of iterations. The algorithm stops if the current time is within 10 MS (higher or lower) of the target time.

debug

If you see an output like:

/usr/bin/supertokens: line 9: 15 Killed "${ST_INSTALL_LOC}"jre/bin/java -classpath "${ST_INSTALL_LOC}cli/*" io.supertokens.cli.Main false "${ST_INSTALL_LOC}" $@

it means that the system doesn't have enough memory. Try to run the algorithm again with a lower memory value by passing --with_argon2_max_memory_mb

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI