renamed gen_sv to create_salted_verification_key

6 files changed, 47 insertions, 43 deletions

diff --git a/_ctsrp.py b/_ctsrp.py
index 83eccb7..42dbfdd 100644
--- a/_ctsrp.py
+++ b/_ctsrp.py
@@ -280,7 +280,7 @@ def get_ngk( hash_class, ng_type, n_hex, g_hex ):
 

     

   

-def gen_sv( username, password, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None ):

+def create_salted_verification_key( username, password, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None ):

     if ng_type == NG_CUSTOM and (n_hex is None or g_hex is None):

         raise ValueError("Both n_hex and g_hex are required when ng_type = NG_CUSTOM")

     s    = BN_new()

diff --git a/_pysrp.py b/_pysrp.py
index 2f21bba..edd1ee3 100644
--- a/_pysrp.py
+++ b/_pysrp.py
@@ -147,7 +147,7 @@ def gen_x( hash_class, salt, username, password ):
     
     
     
-def gen_sv( username, password, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None ):
+def create_salted_verification_key( username, password, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None ):
     if ng_type == NG_CUSTOM and (n_hex is None or g_hex is None):
         raise ValueError("Both n_hex and g_hex are required when ng_type = NG_CUSTOM")
     hash_class = _hash_map[ hash_alg ]
diff --git a/_srp.c b/_srp.c
index 46b1de2..e78c74c 100644
--- a/_srp.c
+++ b/_srp.c
@@ -63,11 +63,11 @@ void srp_random_seed( const unsigned char * random_data, int data_length );
  * The n_hex and g_hex parameters should be 0 unless SRP_NG_CUSTOM is used for ng_type.
  * If provided, they must contain ASCII text of the hexidecimal notation.
  */
-void srp_gen_sv( SRP_HashAlgorithm alg, SRP_NGType ng_type, const char * username,
-                 const unsigned char * password, int len_password,
-                 const unsigned char ** bytes_s, int * len_s, 
-                 const unsigned char ** bytes_v, int * len_v,
-                 const char * n_hex, const char * g_hex );
+void srp_create_salted_verification_key( SRP_HashAlgorithm alg, SRP_NGType ng_type, const char * username,
+                                         const unsigned char * password, int len_password,
+                                         const unsigned char ** bytes_s, int * len_s, 
+                                         const unsigned char ** bytes_v, int * len_v,
+                                         const char * n_hex, const char * g_hex );
 
 
 /* Out: bytes_B, len_B.
@@ -471,11 +471,11 @@ void srp_random_seed( const unsigned char * random_data, int data_length )
 }
 
 
-void srp_gen_sv( SRP_HashAlgorithm alg, SRP_NGType ng_type, const char * username,
-                 const unsigned char * password, int len_password,
-                 const unsigned char ** bytes_s, int * len_s, 
-                 const unsigned char ** bytes_v, int * len_v,
-                 const char * n_hex, const char * g_hex )
+void srp_create_salted_verification_key( SRP_HashAlgorithm alg, SRP_NGType ng_type, const char * username,
+                                         const unsigned char * password, int len_password,
+                                         const unsigned char ** bytes_s, int * len_s, 
+                                         const unsigned char ** bytes_v, int * len_v,
+                                         const char * n_hex, const char * g_hex )
 {
     BIGNUM     * s   = BN_new();
     BIGNUM     * v   = BN_new();
@@ -1240,7 +1240,7 @@ static PyObject * usr_verify_session( PyUser * self, PyObject * args )
 }
 
 
-static PyObject * py_gen_sv( PyObject *self, PyObject *args, PyObject *kwds )
+static PyObject * py_create_salted_verification_key( PyObject *self, PyObject *args, PyObject *kwds )
 {
     PyObject            *ret;
     const char          *username;
@@ -1282,12 +1282,12 @@ static PyObject * py_gen_sv( PyObject *self, PyObject *args, PyObject *kwds )
         return NULL;
     }
 
-    srp_gen_sv( (SRP_HashAlgorithm) hash_alg, 
-                (SRP_NGType) ng_type,
-                username, bytes_password, len_password, &bytes_s, &len_s, 
-                &bytes_v, &len_v,
-                n_hex,
-                g_hex );
+    srp_create_salted_verification_key( (SRP_HashAlgorithm) hash_alg, 
+                                        (SRP_NGType) ng_type,
+                                        username, bytes_password, len_password, &bytes_s, &len_s, 
+                                        &bytes_v, &len_v,
+                                        n_hex,
+                                        g_hex );
     
     ret = Py_BuildValue("s#s#", bytes_s, len_s, bytes_v, len_v);
     
@@ -1354,8 +1354,8 @@ static PyMethodDef PyUser_methods[] = {
 
 
 static PyMethodDef srp_module_methods[] = {
-    {"gen_sv", (PyCFunction) py_gen_sv, METH_VARARGS | METH_KEYWORDS,
-            PyDoc_STR("Returns (s,v): Generates a salt + verifier for the "
+    {"create_salted_verification_key", (PyCFunction) py_create_salted_verification_key, METH_VARARGS | METH_KEYWORDS,
+            PyDoc_STR("Returns (s,v): Generates a salt & verifier for the "
                       "given username and password")
     },
     {NULL} /* Sentinel */
diff --git a/doc/srp.rst b/doc/srp.rst
index e6708fe..4a593c4 100644
--- a/doc/srp.rst
+++ b/doc/srp.rst
@@ -46,15 +46,17 @@ Briefly stated, the advantages of SRP are:
 Usage
 -----
 
-Use of SRP begins by using the gen_sv() function to create a salted 
-verification key from the user's password. The salt and key are stored
-on the server and will be used during the authentication process. 
+Use of SRP begins by using the create_salted_verification_key() function to 
+create a salted verification key from the user's password. The salt and key 
+are stored on the server and will be used during the authentication process. 
 
-TODO: Lay out the steps of the protocol
+The rest of the authentication process occurs as an exchange of
+messages between the clent and the server. The :ref:`example` below provides 
+a simple demonstration of the protocol. A comprehensive description of the SRP
+protocol is contained in the :ref:`protocol-description` section.
 
-
-The User & Verifier construtors, as well as the gen_sv() function,
-take optional hashing algorithm and prime number arguments. Generally
+The User & Verifier construtors, as well as the create_salted_verification_key()
+function, take optional hashing algorithm and prime number arguments. Generally
 speaking, more bits means more security but comes at the cost of 
 increased computation time. The hashing and prime number parameters passed 
 to the User and Verifier constructors must match those used to create the 
@@ -99,7 +101,7 @@ be used with NG_CUSTOM.
 Functions
 ---------
 
-.. function:: gen_sv ( username, password[, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None] )
+.. function:: create_salted_verification_key ( username, password[, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None] )
 
     Generates a salt and verifier for the given username and password.
     Returns (salt_bytes, verifier_bytes)
@@ -120,9 +122,9 @@ user.
 
   *username* Name of the remote user being authenticated.
   
-  *bytes_s* Salt generated by :func:`gen_sv`.
+  *bytes_s* Salt generated by :func:`create_salted_verification_key`.
   
-  *bytes_v* Verifier generated by :func:`gen_sv`.
+  *bytes_v* Verifier generated by :func:`create_salted_verification_key`.
   
   *bytes_A* Challenge from the remote user. Generated by
   :meth:`User.start_authentication`  
@@ -202,17 +204,18 @@ username/password pair.
     process. If the authentication succeded :meth:`authenticated` will
     return True
     
-    
-Examples
---------
+.. _example:
+
+Example
+-------
 
 Simple Usage Example::
 
     import srp
     
-    # The salt and verifier returned from srp.gen_sv() should be
+    # The salt and verifier returned from srp.create_salted_verification_key() should be
     # stored on the server.
-    salt, verifier = srp.gen_sv( 'testuser', 'testpassword' )
+    salt, verifier = srp.create_salted_verification_key( 'testuser', 'testpassword' )
     
     # ~~~ Begin Authentication ~~~
     
@@ -263,6 +266,7 @@ authentication steps on multi-core systems will yield a substantial
 performance increase.
 
 
+.. _protocol-description:
 
 SRP 6a Protocol Description
 ---------------------------
diff --git a/srp.py b/srp.py
index 6792076..785e721 100644
--- a/srp.py
+++ b/srp.py
@@ -19,9 +19,9 @@ if not _mod:
     _mod = _pysrp

 

     

-User      = _mod.User

-Verifier  = _mod.Verifier

-gen_sv    = _mod.gen_sv

+User                           = _mod.User

+Verifier                       = _mod.Verifier

+create_salted_verification_key = _mod.create_salted_verification_key

 

 SHA1      = _mod.SHA1

 SHA224    = _mod.SHA224

diff --git a/test_srp.py b/test_srp.py
index 59b7435..be28c4c 100644
--- a/test_srp.py
+++ b/test_srp.py
@@ -27,9 +27,9 @@ except:
 
 import srp
 
-User     = u_mod.User
-Verifier = v_mod.Verifier
-gen_sv   = g_mod.gen_sv
+User                           = u_mod.User
+Verifier                       = v_mod.Verifier
+create_salted_verification_key = g_mod.create_salted_verification_key
 
 HASH = srp.SHA256
 NG   = srp.NG_CUSTOM
@@ -54,7 +54,7 @@ FBB694B5C803D89F7AE435DE236D525F54759B65E372FCD68EF20FA7111F9E4AFF73'''
     
 
 
-_s, _v = gen_sv( username, password, hash_alg=HASH, ng_type=NG, n_hex=n_hex, g_hex=g_hex )
+_s, _v = create_salted_verification_key( username, password, hash_alg=HASH, ng_type=NG, n_hex=n_hex, g_hex=g_hex )
     
 def test_one():
     usr      = User( username, password, hash_alg=HASH, ng_type=NG, n_hex=n_hex, g_hex=g_hex )