Skip to main content

Password hashing

Learn about the password hashing algorithms used by SuperTokens and how to customize and calibrate them.

Overview

SuperTokens supports two password hashing algorithms: BCrypt and Argon2. Per current best practices, Argon2 is the recommended algorithm. However, SuperTokens uses BCrypt by default since Argon2 requires custom settings that are specific to the hardware in which the core is running on.

Hashing time

The key metric to aim for when hashing passwords is the amount of time each hash would take. By default, SuperTokens has configured these algorithms to take 300 milliseconds per hash on a machine with 1 GB of RAM and 2 virtual CPU cores.

Change the hashing algorithm

You can switch algorithms whenever you want. The change affects only the new users that sign up. Previous passwords undergo decryption using the original algorithm. For example, if you hash a password with BCrypt, it verifies using BCrypt even if the core configuration changes to Argon2.

Instructions:

  1. Go to the SuperTokens SaaS dashboard.
  2. Click "Edit Configuration" on the environment you want to change.
  3. Find the password_hashing_alg property and change it.
  4. Click "Save".

Hashing calibration

This information is relevant only for self hosted core instances. The managed service instances have already calibrated the algorithms based on the hardware.

important

When you change the hashing settings make sure to run the calibration CLI command to find the right balance for your hardware.

Algorithm settings

NameDefaultDescription
password_hashing_alg-This setting chooses which password hashing algorithm to use. For using Argon2, set this to ARGON2.
argon2_iterations1This controls how much CPU processing power the hashing process uses. The higher the value, the more processing power, and hence the more time each hash takes.
argon2_memory_kb87795 (85 MB)The amount of memory (RAM) that each hash takes. The higher this is, the harder it becomes to crack hashes offline, and the longer the algorithm takes.
argon2_parallelism2This is the number of threads the algorithm uses during hashing. The higher this is, the harder it would be to crack passwords offline using multiple cores. Should be equal to the number of virtual cores (or twice the number of physical cores) available in the system.
argon2_hashing_pool_size1This is the maximum number of concurrent hashes that the core performs. A value of 1 means that the core does only one hash at one point in time, other requests for hashing queue 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 occurs 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 expect per second.

Change the settings

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

Calibrate to your hardware

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

  • --with_alg:
    • The value of this should be argon2
    • Compulsory parameter
  • --with_time_per_hash_ms:
    • This requires the target time per hash (in milliseconds).
    • The default value is 300.
  • --with_argon2_hashing_pool_size:
    • This affects how much memory the hashing process uses per hash.
    • The default value is 1
  • --with_argon2_max_memory_mb:
    • This is the maximum amount of memory (RAM) that the core should use for password hashing. The amount of memory per password hash is 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 argon2 should use. The higher this is, the harder it becomes to crack passwords offline.
    • The default value is 2*number of cores

Running the algorithm takes minutes.

docker run registry.supertokens.io/supertokens/supertokens-<db_name> supertokens hashingCalibrate --with_alg=argon2

The above produces 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 environment 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 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 less than the target time, it increases the number of iterations. The algorithm stops if the current time is within 10 milliseconds (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

See also