78 lines
3.2 KiB
ReStructuredText
78 lines
3.2 KiB
ReStructuredText
|
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).
|