= 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 <tt>[""]</tt>, 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+.
