KDF Algorithms

Bitwarden first uses Key Derivation Functions (KDFs) on account creation to derive a master key for the account from the input master password, which acts as input for a master password hash for the account (learn more). Whenever a user is authenticated, for example when unlocking a vault or satisfying master password re-prompt, the process is repeated so that the newly-derived hash can be compared to the originally-derived hash. If they match, the user is authenticated.

KDFs are used in this capacity to frustrate brute-force or dictionary attacks against a master password. KDFs force an attacker's machines to compute a non-trivial number of hashes for each password guess, at increasing cost to the attacker.

Two KDF algorithms are currently available for use in Bitwarden; PBKDF2 and Argon2. Each algorithm has a selection of options available which can be used to increase the time and expense, or "work factor", imposed on the attacker.

Password-Based Key Derivation Function 2 (PBKDF2) is recommended by NIST and, as implemented by Bitwarden, satisfies FIPS-140 requirements so long as default values are not changed.

PBKDF2, as implemented by Bitwarden, works by salting your master password with your username and running the resultant value through a one-way hash algorithm (HMAC-SHA-256) to create a fixed-length hash. This value is again salted with your username and hashed a configurable number of times (KDF iterations). The resultant value after all iterations is your master key, which acts as input for the master password hash used to authenticate that user whenever they log in (learn more).

By default, Bitwarden is set to iterate 600,000 times, as recommended by OWASP for HMAC-SHA-256 implementations. So long as the user does not set this value lower, the implementation is FIPS-140 compliant, but here are some tips should you choose to change your settings:

• More KDF iterations will increase both the time it will take an attacker to crack a password and the time it will take a legitimate user to log in.

• We recommend that you increase the value in increments of 50,000 and test all of your devices.

Argon2 is the winner of the 2015 Password Hashing Competition. There are three versions of the algorithm, and Bitwarden has implemented Argon2id as recommended by OWASP. Argon2id is a hybrid of other versions, using a combination of data-depending and data-independent memory accesses, which gives it some of Argon2i's resistance to side-channel cache timing attacks and much of Argon2d's resistance to GPU cracking attacks (source).

Argon2, as implemented by Bitwarden, works by salting your master password with your username and running the resultant value through a one-way hash algorithm (BLAKE2b) to create a fixed-length hash.

Argon2 then allocates a portion of memory (KDF memory) and fills it with the computed hash until full. This is repeated, starting in the subsequent portion of memory where it left off in the first, a number of times iteratively (KDF iterations) across a number of threads (KDF parallelism). The resultant value after all iterations, is your master key, which acts as input for the master password hash used to authenticate that user whenever they log in (learn more).

By default, Bitwarden is set to allocate 64 MiB of memory, iterate over it 3 times, and do so across 4 threads. These defaults are above current OWASP recommendations, but here are some tips should you choose to change your settings:

• Increasing KDF iterations will increase running time linearly.

• The amount of KDF parallelism you can use depends on your machine's CPU. Generally, Max. Parallelism = Num. of Cores x 2.

• iOS limits app memory for autofill. Increasing iterations from the default 64 MB may result in errors while unlocking the vault with autofill.

To change your KDF algorithm, navigate to the Account Settings → Security → Keys page of the web vault. Changing the algorithm will re-encrypt the protected symmetric key and update the authentication hash, much like a normal master password change, but will not rotate the symmetric encryption key so vault data will not be re-encrypted. See here for information on re-encrypting your data.

When you change algorithm, you'll be logged out of all clients. Though the risk involved in rotating your encryption key does not exist when changing algorithm, we still recommend exporting your vault beforehand.