Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 190 insertions, 0 deletions

diff --git a/comm/third_party/botan/doc/api_ref/pbkdf.rst b/comm/third_party/botan/doc/api_ref/pbkdf.rst
new file mode 100644
index 0000000000..92f59f2780
--- /dev/null
+++ b/comm/third_party/botan/doc/api_ref/pbkdf.rst
@@ -0,0 +1,190 @@
+
+.. _pbkdf:
+
+Password Based Key Derivation
+========================================
+
+Often one needs to convert a human readable password into a cryptographic
+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).
+
+.. cpp:class:: PasswordHash
+
+   .. cpp:function:: void derive_key(uint8_t out[], size_t out_len, \
+                     const char* password, const size_t password_len, \
+                     const uint8_t salt[], size_t salt_len) const
+
+      Derive a key, placing it into output
+
+   .. cpp:function:: std::string to_string() const
+
+      Return a descriptive string including the parameters (iteration count, etc)
+
+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.
+
+   .. cpp:function:: std::unique_ptr<PasswordHash> default_params() const
+
+      Create a default instance of the password hashing algorithm. Be warned the
+      value returned here may change from release to release.
+
+   .. cpp:function:: std::unique_ptr<PasswordHash> tune(size_t output_len, std::chrono::milliseconds msec) const
+
+      Return a password hash instance tuned to run for approximately ``msec``
+      milliseconds when producing an output of length ``output_len``. (Accuracy
+      may vary, use the command line utility ``botan pbkdf_tune`` to check.)
+
+   .. cpp:function:: std::unique_ptr<PasswordHash> from_params( \
+         size_t i1, size_t i2 = 0, size_t i3 = 0) const
+         
+      Create a password hash using some scheme specific format.
+      Eg PBKDF2 and PGP-S2K set iterations in i1
+      Scrypt uses N,r,p in i{1-3}
+      Bcrypt-PBKDF just has iterations
+      Argon2{i,d,id} would use iterations, memory, parallelism for i{1-3}, and Argon2 type is part of the family.
+      
+      Values not needed should be set to 0.
+
+Available Schemes
+----------------------
+
+PBKDF2
+^^^^^^^^^^^^
+
+PBKDF2 is the "standard" password derivation scheme, widely implemented in many
+different libraries. It uses HMAC internally.
+
+Scrypt
+^^^^^^^^^^
+
+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)
+
+   Computes the Scrypt using the password and salt, and produces an output
+   of arbitrary length.
+
+   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.
+
+   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
+
+Argon2
+^^^^^^^^^^
+
+.. versionadded:: 2.11.0
+
+Argon2 is the winner of the PHC (Password Hashing Competition) and
+provides a tunable memory hard PBKDF.
+
+OpenPGP S2K
+^^^^^^^^^^^^
+
+.. warning::
+
+   The OpenPGP algorithm is weak and strange, and should be avoided unless
+   implementing OpenPGP.
+
+There are some oddities about OpenPGP's S2K algorithms that are documented
+here. For one thing, it uses the iteration count in a strange manner; instead of
+specifying how many times to iterate the hash, it tells how many *bytes* should
+be hashed in total (including the salt). So the exact iteration count will
+depend on the size of the salt (which is fixed at 8 bytes by the OpenPGP
+standard, though the implementation will allow any salt size) and the size of
+the passphrase.
+
+To get what OpenPGP calls "Simple S2K", set iterations to 0, and do not specify
+a salt. To get "Salted S2K", again leave the iteration count at 0, but give an
+8-byte salt. "Salted and Iterated S2K" requires an 8-byte salt and some
+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.
+
+PBKDF1
+^^^^^^^^^^^^
+
+PBKDF1 is an old scheme that can only produce an output length at most
+as long as the hash function. It is deprecated and will be removed in
+a future release. It is not supported through :cpp:class:`PasswordHash`.