Update the password hashing docs

2 files changed, 107 insertions, 83 deletions

diff --git a/doc/api_ref/pbkdf.rst b/doc/api_ref/pbkdf.rst
index 2138d02e9..137ad2d3c 100644
--- a/doc/api_ref/pbkdf.rst
+++ b/doc/api_ref/pbkdf.rst
@@ -9,60 +9,16 @@ key. It is useful to slow down the computation of these computations in order to
 reduce the speed of brute force search, thus they are parameterized in some
 way which allows their required computation to be tuned.
 
-PBKDF
----------
-
-:cpp:class:`PBKDF` is the older API for this functionality, presented in header
-``pbkdf.h``. It does not support Scrypt, nor will it be able to support other
-future hashes (such as Argon2) that may be added in the future. In addition,
-this API requires the passphrase be entered as a ``std::string``, which means
-the secret will be stored in memory that will not be zeroed.
-
-.. cpp:class:: PBKDF
-
-   .. cpp:function:: void pbkdf_iterations(uint8_t out[], size_t out_len, \
-                            const std::string& passphrase, \
-                            const uint8_t salt[], size_t salt_len, \
-                            size_t iterations) const
-
-      Run the PBKDF algorithm for the specified number of iterations,
-      with the given salt, and write output to the buffer.
-
-   .. cpp:function:: void pbkdf_timed(uint8_t out[], size_t out_len, \
-                         const std::string& passphrase, \
-                         const uint8_t salt[], size_t salt_len, \
-                         std::chrono::milliseconds msec, \
-                         size_t& iterations) const
-
-      Choose (via short run-time benchmark) how many iterations to perform
-      in order to run for roughly msec milliseconds. Writes the number
-      of iterations used to reference argument.
-
-   .. cpp:function:: OctetString derive_key( \
-               size_t output_len, const std::string& passphrase, \
-               const uint8_t* salt, size_t salt_len, \
-               size_t iterations) const
-
-   Computes a key from *passphrase* and the *salt* (of length
-   *salt_len* bytes) using an algorithm-specific interpretation of
-   *iterations*, producing a key of length *output_len*.
-
-   Use an iteration count of at least 10000. The salt should be
-   randomly chosen by a good random number generator (see
-   :ref:`random_number_generators` for how), or at the very least
-   unique to this usage of the passphrase.
-
-   If you call this function again with the same parameters, you will
-   get the same key.
-
 PasswordHash
 --------------
 
 .. versionadded:: 2.8.0
 
-This API has two classes, one representing the algorithm (such as
-"PBKDF2(SHA-256)", or "Scrypt") and the other representing a specific instance
-of the problem which is fully specified (say "Scrypt" with N=8192,r=64,p=8).
+This API, declared in ``pwdhash.h``, has two classes, ``PasswordHashFamily``
+representing the general algorithm, such as "PBKDF2(SHA-256)", or "Scrypt", and
+``PasswordHash`` representing a specific instance of the problem which is fully
+specified with all parameters (say "Scrypt" with ``N`` = 8192, ``r`` = 64, and
+``p`` = 8) and which can be used to derive keys.
 
 .. cpp:class:: PasswordHash
 
@@ -70,20 +26,41 @@ of the problem which is fully specified (say "Scrypt" with N=8192,r=64,p=8).
                      const char* password, const size_t password_len, \
                      const uint8_t salt[], size_t salt_len) const
 
-      Derive a key, placing it into output
+      Derive a key from the specified password and salt, placing it into output.
 
    .. cpp:function:: std::string to_string() const
 
       Return a descriptive string including the parameters (iteration count, etc)
 
+   .. cpp:function:: size_t iterations() const
+
+      Return the iteration parameter
+
+   .. cpp:function:: size_t memory_param() const
+
+      Return the memory usage parameter, or 0 if the algorithm does not offer
+      a memory usage option.
+
+   .. cpp:function:: size_t parallelism() const
+
+      Returns the parallelism parameter, or 0 if the algorithm does not offer a
+      parallelism option.
+
+   .. cpp:function:: size_t total_memory_usage() const
+
+      Return a guesstimate of the total number of bytes of memory consumed when
+      running this algorithm. If the function is not intended to be memory-hard
+      and uses an effictively fixed amount of memory when running, this function
+      returns 0.
+
 The ``PasswordHashFamily`` creates specific instances of ``PasswordHash``:
 
 .. cpp:class:: PasswordHashFamily
 
    .. cpp:function:: static std::unique_ptr<PasswordHashFamily> create(const std::string& what)
 
-      For example "PBKDF2(SHA-256)", "Scrypt", "OpenPGP-S2K(SHA-384)". Returns
-      null if not available.
+      For example "PBKDF2(SHA-256)", "Scrypt", "Argon2id". Returns null if the
+      algorithm is not available.
 
    .. cpp:function:: std::unique_ptr<PasswordHash> default_params() const
 
@@ -100,9 +77,11 @@ The ``PasswordHashFamily`` creates specific instances of ``PasswordHash``:
          size_t i1, size_t i2 = 0, size_t i3 = 0) const
 
       Create a password hash using some scheme specific format. Parameters are as follows:
-      - For PBKDF2, PGP-S2K, and Bcrypt-PBKDF, i1 is iterations
-      - Scrypt uses N, r, p for i{1-3}
-      - Argon2 family uses memory (in KB), iterations, and parallelism for i{1-3}
+
+      * For PBKDF2, PGP-S2K, and Bcrypt-PBKDF, ``i1`` is iterations
+      * Scrypt uses ``i1`` == ``N``, ``i2`` == ``r``, and ``i3`` == ``p``
+      * Argon2 family uses ``i1`` == ``M``, ``i2`` == ``t``, and ``i3`` == ``p``
+
       All unneeded parameters should be set to 0 or left blank.
 
 Available Schemes
@@ -111,8 +90,9 @@ Available Schemes
 General Recommendations
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you need wide interoperability use PBKDF2 with HMAC-SHA256 and at least 10K
-iterations. If you don't, use Scrypt with N=32768, r=8, p=1.
+If you need wide interoperability use PBKDF2 with HMAC-SHA256 and at least 50K
+iterations. If you don't, use Argon2id with p=1, t=3 and M as large as you
+can reasonable set (say 1 gigabyte).
 
 You can test how long a particular PBKDF takes to execute using the cli tool
 ``pbkdf_tune``::
@@ -120,11 +100,10 @@ You can test how long a particular PBKDF takes to execute using the cli tool
   $ ./botan pbkdf_tune --algo=Argon2id 500 --max-mem=192 --check
   For 500 ms selected Argon2id(196608,3,1) using 192 MiB took 413.159 msec to compute
 
-This indicates the parameters chosen by the fast auto-tuning algorithm and
+This returns the parameters chosen by the fast auto-tuning algorithm, and
 because ``--check`` was supplied the hash is also executed with the full set of
 parameters and timed.
 
-
 PBKDF2
 ^^^^^^^^^^^^
 
@@ -132,41 +111,30 @@ PBKDF2 is the "standard" password derivation scheme, widely implemented in many
 different libraries. It uses HMAC internally and requires choosing a hash
 function to use. (If in doubt use SHA-256 or SHA-512). It also requires choosing
 an iteration count, which makes brute force attacks more expensive. Use *at
-least* 10000 and preferably much more.
+least* 50000 and preferably much more. Using 250,000 would not be unreasonable.
 
 Scrypt
 ^^^^^^^^^^
 
+.. versionadded:: 2.7.0
+
 Scrypt is a relatively newer design which is "memory hard" - in
 addition to requiring large amounts of CPU power it uses a large block
 of memory to compute the hash. This makes brute force attacks using
 ASICs substantially more expensive.
 
-Scrypt is not supported through :cpp:class:`PBKDF`, only :cpp:class:`PasswordHash`,
-starting in 2.8.0. In addition, starting in version 2.7.0, scrypt is available
-with this function:
-
-.. cpp:function:: void scrypt(uint8_t output[], size_t output_len, \
-                              const std::string& password, \
-                              const uint8_t salt[], size_t salt_len, \
-                              size_t N, size_t r, size_t p)
+Scrypt has three parameters, usually termed ``N``, ``r``, and ``p``.  ``N`` is
+the primary control of the workfactor, and must be a power of 2. For interactive
+logins use 32768, for protection of secret keys or backups use 1048576.
 
-   Computes the Scrypt using the password and salt, and produces an output
-   of arbitrary length.
+The ``r`` parameter controls how 'wide' the internal hashing operation is. It
+also increases the amount of memory that is used. Values from 1 to 8 are
+reasonable.
 
-   The N, r, p parameters control how much work and memory Scrypt
-   uses.  N is the primary control of the workfactor, and must be a
-   power of 2. For interactive logins use 32768, for protection of
-   secret keys or backups use 1048576.
+Setting ``p`` parameter to greater than 1 splits up the work in a way that up
+to p processors can work in parallel.
 
-   The r parameter controls how 'wide' the internal hashing operation
-   is. It also increases the amount of memory that is used. Values
-   from 1 to 8 are reasonable.
-
-   Setting p parameter to greater than one splits up the work in a way
-   that up to p processors can work in parallel.
-
-   As a general recommendation, use N=32768, r=8, p=1
+As a general recommendation, use ``N`` = 32768, ``r`` = 8, ``p`` = 1
 
 Argon2
 ^^^^^^^^^^
@@ -214,3 +182,59 @@ iteration count (this should be significantly larger than the size of the
 longest passphrase that might reasonably be used; somewhere from 1024 to 65536
 would probably be about right). Using both a reasonably sized salt and a large
 iteration count is highly recommended to prevent password guessing attempts.
+
+PBKDF
+---------
+
+:cpp:class:`PBKDF` is the older API for this functionality, presented in header
+``pbkdf.h``. It only supports PBKDF2 and the PGP S2K algorithm, not
+Scrypt, Argon2, or bcrypt. This interface is deprecated and will be removed
+in a future major release.
+
+In addition, this API requires the passphrase be entered as a
+``std::string``, which means the secret will be stored in memory that
+will not be zeroed.
+
+.. cpp:class:: PBKDF
+
+   .. cpp:function:: static std::unique_ptr<PBKDF> create(const std::string& algo_spec, \
+                                                          const std::string& provider = "")
+
+      Return a newly created PBKDF object. The name should be in the
+      format "PBKDF2(HASHNAME)", "PBKDF2(HMAC(HASHNAME))", or
+      "OpenPGP-S2K".  Returns null if the algorithm is not available.
+
+   .. cpp:function:: void pbkdf_iterations(uint8_t out[], size_t out_len, \
+                            const std::string& passphrase, \
+                            const uint8_t salt[], size_t salt_len, \
+                            size_t iterations) const
+
+      Run the PBKDF algorithm for the specified number of iterations,
+      with the given salt, and write output to the buffer.
+
+   .. cpp:function:: void pbkdf_timed(uint8_t out[], size_t out_len, \
+                         const std::string& passphrase, \
+                         const uint8_t salt[], size_t salt_len, \
+                         std::chrono::milliseconds msec, \
+                         size_t& iterations) const
+
+      Choose (via short run-time benchmark) how many iterations to perform
+      in order to run for roughly msec milliseconds. Writes the number
+      of iterations used to reference argument.
+
+   .. cpp:function:: OctetString derive_key( \
+               size_t output_len, const std::string& passphrase, \
+               const uint8_t* salt, size_t salt_len, \
+               size_t iterations) const
+
+   Computes a key from *passphrase* and the *salt* (of length
+   *salt_len* bytes) using an algorithm-specific interpretation of
+   *iterations*, producing a key of length *output_len*.
+
+   Use an iteration count of at least 10000. The salt should be
+   randomly chosen by a good random number generator (see
+   :ref:`random_number_generators` for how), or at the very least
+   unique to this usage of the passphrase.
+
+   If you call this function again with the same parameters, you will
+   get the same key.
diff --git a/src/lib/pbkdf/pwdhash.h b/src/lib/pbkdf/pwdhash.h
index 4255e1d43..d57775e73 100644
--- a/src/lib/pbkdf/pwdhash.h
+++ b/src/lib/pbkdf/pwdhash.h
@@ -50,7 +50,7 @@ class BOTAN_PUBLIC_API(2,8) PasswordHash
       virtual size_t parallelism() const { return 0; }
 
       /**
-      * Returns an estimate of the total memory usage required to perform this
+      * Returns an estimate of the total number of bytes required to perform this
       * key derivation.
       *
       * If this algorithm uses a small and constant amount of memory, with no