diff options
Diffstat (limited to 'doc/srp.rst')
| -rw-r--r-- | doc/srp.rst | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/doc/srp.rst b/doc/srp.rst new file mode 100644 index 0000000..8cfd780 --- /dev/null +++ b/doc/srp.rst @@ -0,0 +1,127 @@ +:mod:`srp` --- Secure Remote Password +===================================== + +.. module:: srp + :synopsis: Secure Remote Password + +.. moduleauthor:: Tom Cocagne <tom.cocagne@gmail.com> + +.. sectionauthor:: Tom Cocagne <tom.cocagne@gmail.com> + + +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. + +The SRP authentication requires that the server store a salt and 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. + +See http://srp.stanford.edu/ for a full description of the SRP protocol. + +Functions +--------- + +.. function:: gen_sv ( username, password ) + + Generates a salt and verifier for the given username and password. + Returns (salt_bytes, verifier_bytes) + + +:class:`Verifier` Objects +------------------------- + +A :class:`Verifier` object is used to verify the identity of a remote +user. + +.. class:: Verifier( username, bytes_s, bytes_v, bytes_A ) + + *username* Name of the remote user being authenticated. + + *bytes_s* Salt generated by :func:`gen_sv`. + + *bytes_v* Verifier generated by :func:`gen_sv`. + + *bytes_A* Challenge from the remote user. Generated by + :meth:`User.start_authentication` + + .. method:: authenticated() + + Returns True if the authentication succeeded. False + otherwise. + + .. method:: get_username() + + Returns the name of the user this :class:`Verifier` object is for. + + .. method:: 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() + + Returns (bytes_s, bytes_B) on success or (None, None) if + authentication has failed. + + .. method:: verify_session( user_M ) + + Completes the :class:`Verifier` side of the authentication + process. If the authentication succeded the return result, + bytes_H_AMK should be returned to the remote user. On failure, + this method returns None. + + +:class:`User` Objects +------------------------- + +A :class:`User` object is used to perform mutual authentication with a +remote :class:`Verifier`. Successful authentication requires not only +that the :class:`User` be provided with a valid username/password but +also that the remote :class:`Verifier` have a salt & verifier for that +username/password pair. + +.. class:: User( username, password ) + + *username* Name of the user being authenticated. + + *password* Password for the user. + + .. method:: authenticated() + + Returns True if authentication succeeded. False + otherwise. + + .. method:: get_username() + + Returns the username passed to the constructor. + + .. method:: get_session_key() + + Returns the session key if authentication succeeded or None if the + authentication failed or has not yet completed. + + .. method:: 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 ) + + Processes the challenge returned + by :meth:`Verifier.get_challenge` on success this method + returns bytes_M that should be sent + to :meth:`Verifier.verify_session` if authentication failed, + it returns None. + + .. method:: 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 |