From 39fe54427deddfb11dea6209496b5bcdcaaadd05 Mon Sep 17 00:00:00 2001
From: "Tom Cocagne (vubuntu)" <devnull@localhost>
Date: Mon, 30 Aug 2010 23:37:47 -0400
Subject: initial commit

---
 doc/srp.rst | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 doc/srp.rst

(limited to 'doc/srp.rst')

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
-- 
cgit v1.2.3