srp.rst - mozsearch

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).