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, 77 insertions, 0 deletions

diff --git a/comm/third_party/botan/doc/api_ref/srp.rst b/comm/third_party/botan/doc/api_ref/srp.rst
new file mode 100644
index 0000000000..cf0386b539
--- /dev/null
+++ b/comm/third_party/botan/doc/api_ref/srp.rst
@@ -0,0 +1,77 @@
+Secure Remote Password
+========================================
+
+The library contains an implementation of the
+`SRP6-a <http://srp.stanford.edu/design.html>`_ password authenticated
+key exchange protocol in ``srp6.h``.
+
+A SRP client provides what is called a SRP *verifier* to the server.
+This verifier is based on a password, but the password cannot be
+easily derived from the verifier (however brute force attacks are
+possible). Later, the client and server can perform an SRP exchange,
+which results in a shared secret key. This key can be used for mutual
+authentication and/or encryption.
+
+SRP works in a discrete logarithm group. Special parameter sets for
+SRP6 are defined, denoted in the library as "modp/srp/<size>", for
+example "modp/srp/2048".
+
+.. warning::
+
+     While knowledge of the verifier does not easily allow an attacker
+     to get the raw password, they could still use the verifier to
+     impersonate the server to the client, so verifiers should be
+     protected as carefully as a plaintext password would be.
+
+.. cpp:function:: BigInt generate_srp6_verifier( \
+          const std::string& username, \
+          const std::string& password, \
+          const std::vector<uint8_t>& salt, \
+          const std::string& group_id, \
+          const std::string& hash_id)
+
+    Generates a new verifier using the specified password and salt.
+    This is stored by the server. The salt must also be stored. Later,
+    the given username and password are used to by the client during
+    the key agreement step.
+
+.. cpp:function:: std::string srp6_group_identifier( \
+            const BigInt& N, const BigInt& g)
+
+.. cpp:class:: SRP6_Server_Session
+
+   .. cpp:function:: BigInt step1(const BigInt& v, \
+                     const std::string& group_id, \
+                     const std::string& hash_id, \
+                     RandomNumberGenerator& rng)
+
+       Takes a verifier (generated by generate_srp6_verifier) along
+       with the group_id, and output a value `B` which is provided to
+       the client.
+
+   .. cpp:function:: SymmetricKey step2(const BigInt& A)
+
+      Takes the parameter A generated by srp6_client_agree,
+      and return the shared secret key.
+
+      In the event of an impersonation attack (or wrong username/password, etc)
+      no error occurs, but the key returned will be different on the two sides.
+      The two sides must verify each other, for example by using the shared
+      secret to key an HMAC and then exchanging authenticated messages.
+
+.. cpp:function:: std::pair<BigInt,SymmetricKey> srp6_client_agree( \
+               const std::string& username, \
+               const std::string& password, \
+               const std::string& group_id, \
+               const std::string& hash_id, \
+               const std::vector<uint8_t>& salt, \
+               const BigInt& B, \
+               RandomNumberGenerator& rng)
+
+    The client receives these parameters from the server, except for
+    the username and password which are provided by the user. The
+    parameter B is the output of `step1`.
+
+    The client agreement step outputs a shared symmetric key along
+    with the parameter A which is returned to the server (and allows
+    it the compute the shared key).