Documentation for Password Pepper Feature¶ ↑

The password pepper feature appends a specified secret string to passwords before they are hashed. This way, if the password hashes get compromised, an attacker cannot use them to crack the passwords without also knowing the pepper.

In the configuration block set the password_pepper with your secret string. It’s recommended for the password pepper to be at last 32 characters long and randomly generated.

password_pepper "<long secret key>"

If your database already contains password hashes that were created without a password pepper, these will get automatically updated with a password pepper next time the user successfully enters their password.

If you’re using bcrypt (default), you should set password_maximum_bytes so that password + pepper don’t exceed 72 bytes. This is because bcrypt truncates passwords longer than 72 bytes, enabling an attacker to crack the pepper if the password bytesize is unlimited. If you’re using argon2, you should probably set argon2_secret instead of using this feature.

Pepper Rotation¶ ↑

You can rotate the password pepper as well, just make sure to add the previous pepper to the previous_password_peppers array. Password hashes using the old pepper will get automatically updated on the next successful password match.

password_pepper "new pepper"
previous_password_peppers ["old pepper", ""]

The empty string above ensures password hashes without pepper are handled as well.

Note that each entry in previous_password_peppers will multiply the amount of possible password checks during login, at least for incorrect passwords.

Additionally, when using this feature with the disallow_password_reuse feature, the number of passwords checked when changing or resetting a password will be

(previous_password_peppers.length + 1) * previous_passwords_to_check

So if you have 2 entries in previous_password_peppers, using the default value of 6 for previous_passwords_to_check, every time a password is changed, there will be 18 password checks done, which will be quite slow.

Auth Value Methods¶ ↑

password_pepper	The secret string appended to passwords before they are hashed.
previous_password_peppers	An array of password peppers that will be tried on an unsuccessful password match. Defaults to [""], which allows introducing this feature with existing passwords.
password_pepper_update?	Whether to update password hashes that use a pepper from previous_password_peppers with a new pepper. Defaults to true.