argon2.rdoc in rodauth-2.32.0

- old
+ new

@@ -1,13 +1,16 @@
 = Documentation for Argon2 Feature
 
 The argon2 feature adds the ability to replace the bcrypt password hash
 algorithm with argon2 (specifically, argon2id).  Argon2 is an alternative to
-bcrypt that offers the ability to be memory-hard.  However, if you are storing
-password hashes in a table that the database user does not have access to
-(the recommended way to use Rodauth), argon2 does not offer significant
-security advantages over bcrypt.
+bcrypt that offers the ability to be memory-hard.  However, argon2 is weaker
+than bcrypt for interactive login environments (e.g. password check times
+under a second), so for the vast majority of web applications, using the
+argon2 feature will weaken the application's security.  You should not use
+the argon2 feature unless the usage of argon2 is required or you are a
+cryptographer and understand why argon2 would be better than bcrypt for your
+application.
 
 If you are using this feature with Rodauth's database authentication functions,
 you need to make sure that the database authentication functions are configured
 to support argon2 in addition to bcrypt.  You can do this by passing the
 +:argon2+ option when calling the method to define the database functions.
@@ -30,11 +33,11 @@
   # new functions that support argon2 for that:
   Rodauth.create_database_previous_password_check_functions(DB, argon2: true) 
 
 The argon2 feature provides the ability to allow for a gradual migration
 from transitioning from bcrypt to argon2 and vice-versa, if you are using the
-update_password_hash.
+update_password_hash feature.
 
 Argon2 is more configurable than bcrypt in terms of password hash cost
 speficiation.  Instead of specifying the password_hash_cost value as
 an integer, you must specify the password hash cost as a hash, such as
 (<tt>{t_cost: 2, m_cost: 16}</tt>).
@@ -44,7 +47,8 @@
 Rodauth configuration to prevent loading the bcrypt library, which will save
 memory.
 
 == Auth Value Methods
 
+argon2_old_secret :: The previous secret key used as input at hashing time, used for argon2_secret rotation.  In order to rotate the argon2_secret, you must also use the update_password_hash feature, and rotation will not be finished until all users have logged in using the new secret.
 argon2_secret :: A secret key used as input at hashing time, folded into the value of the hash.
 use_argon2? :: Whether to use the argon2 password hash algorithm for new passwords (true by default). The only reason to set this to false is if you have existing passwords using argon2 that you want to support, but want to use bcrypt for new passwords.