added documentation

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()
+