diff options
Diffstat (limited to 'comm/third_party/botan/doc/api_ref/srp.rst')
| -rw-r--r-- | comm/third_party/botan/doc/api_ref/srp.rst | 77 |
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). |