diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/srp.rst | 111 |
1 files changed, 86 insertions, 25 deletions
diff --git a/doc/srp.rst b/doc/srp.rst index 8cfd780..c9e65cf 100644 --- a/doc/srp.rst +++ b/doc/srp.rst @@ -10,18 +10,31 @@ This module provides an implementation of the Secure Remote Password -Protocol. It may be used for secure, mutual authentication across an -unsecured network connection. With SRP, the user's password is never -sent across the network and a successful authentication results in a -cryptographically secure shared key that may be used for symmetric key -encryption. +Protocol. It may be used for secure authentication across an unsecured +network connection and verifies that both sides, the user and server, +have knowledge of the user's password. Unlike other commonly used +authentication protocols such as Kerberos and certificate-based SSL, +SRP does not require a trusted third party. With SRP, the user's password +is never sent over the network and a successful authentication results +in a cryptographically secure shared key that may be used for symmetric +key encryption. -The SRP authentication requires that the server store a salt and verification +SRP authentication requires the server to store a salted verification key that is computed from user's password. While care should be taken to protect the verification key from disclosure, the protocol remains -reasonably secure even in the event that an attacker obtains it as a -computationally infeasible brute-force dictionary attack would be required -to derive the users password. +reasonably secure even in the event that an attacker obtains it. The +verification key cannot be used to directly impersonate the user and +it would require a computationally infeasible brute-force dictionary +attack to derive the users password from the verification key. + +This implementation of SRP consists of both a pure-python module and +a C-based implementation that is approximately 10x faster. By default, +the C-implementation will be used if it is available. An additional +benefit of the C implementation is that it can take advantage of +of multiple CPUs. For cases in which the number of connections per +second is an issue, using a small pool of threads to perform the +authentication steps on multi-core systems will yield a substantial +performance increase. See http://srp.stanford.edu/ for a full description of the SRP protocol. @@ -40,6 +53,11 @@ Functions A :class:`Verifier` object is used to verify the identity of a remote user. +.. note:: + + The standard SRP 6 protocol allows only one password attempt per + connection. + .. class:: Verifier( username, bytes_s, bytes_v, bytes_A ) *username* Name of the remote user being authenticated. @@ -49,28 +67,28 @@ user. *bytes_v* Verifier generated by :func:`gen_sv`. *bytes_A* Challenge from the remote user. Generated by - :meth:`User.start_authentication` + :meth:`User.start_authentication` - .. method:: authenticated() + .. method:: Verifier.authenticated() Returns True if the authentication succeeded. False otherwise. - .. method:: get_username() + .. method:: Verifier.get_username() Returns the name of the user this :class:`Verifier` object is for. - .. method:: get_session_key() + .. method:: Verifier.get_session_key() Returns the session key for an authenticated user or None if the authentication failed or has not yet completed. - .. method:: get_challenge() + .. method:: Verifier.get_challenge() Returns (bytes_s, bytes_B) on success or (None, None) if authentication has failed. - .. method:: verify_session( user_M ) + .. method:: Verifier.verify_session( user_M ) Completes the :class:`Verifier` side of the authentication process. If the authentication succeded the return result, @@ -93,26 +111,26 @@ username/password pair. *password* Password for the user. - .. method:: authenticated() + .. method:: User.authenticated() - Returns True if authentication succeeded. False - otherwise. + Returns True if authentication succeeded. False + otherwise. - .. method:: get_username() + .. method:: User.get_username() - Returns the username passed to the constructor. + Returns the username passed to the constructor. - .. method:: get_session_key() + .. method:: User.get_session_key() Returns the session key if authentication succeeded or None if the authentication failed or has not yet completed. - .. method:: start_authentication() + .. method:: User.start_authentication() Returns (username, bytes_A). These should be passed to the constructor of the remote :class:`Verifer` - .. method:: process_challenge( bytes_s, bytes_B ) + .. method:: User.process_challenge( bytes_s, bytes_B ) Processes the challenge returned by :meth:`Verifier.get_challenge` on success this method @@ -120,8 +138,51 @@ username/password pair. to :meth:`Verifier.verify_session` if authentication failed, it returns None. - .. method:: verify_session( bytes_H_AMK ) + .. method:: User.verify_session( bytes_H_AMK ) Completes the :class:`User` side of the authentication process. If the authentication succeded :meth:`authenticated` will - return True
\ No newline at end of file + return True + + +Examples +-------- + +Simple Usage Example:: + + import srp + + # The salt and verifier returned from srp.gen_sv() should be + # stored on the server. + salt, verifier = srp.gen_sv( 'testuser', 'testpassword' ) + + # ~~~ Begin Authentication ~~~ + + usr = srp.User( 'testuser', 'testpassword' ) + uname, A = usr.start_authentication() + + # The authentication process can fail at each step from this + # point on. To comply with the SRP protocol, the authentication + # process should be aborted on the first failure. + + # Client => Server: username, A + svr = srp.Verifier( uname, salt, verifier, A ) + s,B = svr.get_challenge() + + + # Server => Client: s, B + M = usr.process_challenge( s, B ) + + + # Client => Server: M + HAMK = svr.verify_session( M ) + + + # Server => Client: HAMK + usr.verify_session( HAMK ) + + # At this point the authentication process is complete. + + assert usr.authenticated() + assert svr.authenticated() + |