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.
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.
The secret string appended to passwords before they are hashed.
An array of password peppers that will be tried on an unsuccessful password match. Defaults to
Whether to update password hashes that use a pepper from