From 3259c3ca42cdc387d239e941fc1dafd90574be9c Mon Sep 17 00:00:00 2001 From: Tom Cocagne Date: Fri, 25 Mar 2011 11:35:27 -0400 Subject: Updated documentation --- doc/conf.py | 68 +++++++++++++++++++++++++++-------------- doc/index.rst | 22 ++++++++++++++ doc/srp.rst | 98 ++++++++++++++++++++++++++++++++--------------------------- 3 files changed, 121 insertions(+), 67 deletions(-) create mode 100644 doc/index.rst diff --git a/doc/conf.py b/doc/conf.py index 7d22afa..ba75a8c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # -# srp documentation build configuration file, created by -# sphinx-quickstart on Mon Aug 30 23:18:19 2010. +# Secure Remote Password documentation build configuration file, created by +# sphinx-quickstart on Fri Mar 25 10:20:52 2011. # # This file is execfile()d with the current directory set to its containing dir. # @@ -16,10 +16,13 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.append(os.path.abspath('.')) +#sys.path.insert(0, os.path.abspath('.')) # -- General configuration ----------------------------------------------------- +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [] @@ -31,23 +34,23 @@ templates_path = ['_templates'] source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8' +#source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'srp' +master_doc = 'index' # General information about the project. -project = u'srp' -copyright = u'2010, Tom Cocagne' +project = u'Secure Remote Password' +copyright = u'2011, Tom Cocagne' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.9' +version = '1.0' # The full version, including alpha/beta/rc tags. -release = '0.9' +release = '1.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -59,12 +62,9 @@ release = '0.9' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' -# List of documents that shouldn't be included in the build. -#unused_docs = [] - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = ['_build'] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -89,8 +89,8 @@ pygments_style = 'sphinx' # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme @@ -138,7 +138,7 @@ html_static_path = ['_static'] #html_additional_pages = {} # If false, no module index is generated. -#html_use_modindex = True +#html_domain_indices = True # If false, no index is generated. #html_use_index = True @@ -149,16 +149,22 @@ html_static_path = ['_static'] # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'srpdoc' +htmlhelp_basename = 'SecureRemotePassworddoc' # -- Options for LaTeX output -------------------------------------------------- @@ -172,7 +178,7 @@ htmlhelp_basename = 'srpdoc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('srp', 'srp.tex', u'srp Documentation', + ('index', 'SecureRemotePassword.tex', u'Secure Remote Password Documentation', u'Tom Cocagne', 'manual'), ] @@ -184,6 +190,12 @@ latex_documents = [ # not chapters. #latex_use_parts = False +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + # Additional stuff for the LaTeX preamble. #latex_preamble = '' @@ -191,4 +203,14 @@ latex_documents = [ #latex_appendices = [] # If false, no module index is generated. -#latex_use_modindex = True +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'secureremotepassword', u'Secure Remote Password Documentation', + [u'Tom Cocagne'], 1) +] diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..0c13606 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,22 @@ +.. Secure Remote Password documentation master file, created by + sphinx-quickstart on Fri Mar 25 10:20:52 2011. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Secure Remote Password's documentation! +================================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + srp.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/srp.rst b/doc/srp.rst index 805793a..df0c1e9 100644 --- a/doc/srp.rst +++ b/doc/srp.rst @@ -9,42 +9,42 @@ .. sectionauthor:: Tom Cocagne -The Secure Remote Password Protocol (SRP) is a simple and secure -protocol for password-based, mutual authentication over an insecure -network connection. Successful SRP authentication can occur only if -both sides of the connection have knowledge of the user's -password. The client side of the connection must have the raw user's -password and the server side must have a verification key that is -derived from the user's password. An advantageous side-effect of -successful SRP authentication is that it results in a -cryptographically strong shared key that can be used to protect -network traffic via symmetric key encryption. - -An advantage of SRP over other authentication protocols such as Kerberos and -SSL is that SRP does not require a trusted third party. Instead, SRP server -applications store small, salted verification keys that are derived from each -user's password. These keys are then used during the authentication process to -verify the correctness of the remote user's password. - -A favorable aspect of the SRP protocol is that even if the -verification keys are compromized, they are of little value to a -potential attacker. Possesion of a verification key does not allow an -attacker to impersonate the user and cannot be used to obtain the -users password except by way of a computationally infeasible -dictionary attack. A compromized key would, however, allow an attacker -to impersonate the server side of an SRP authenticated -connection. Consequently, care should be taken to prevent unauthorized -access to verification keys for applications in which the client side -relies on the server being genuine. +The Secure Remote Password Protocol (SRP) is a cryptographically +strong authentication protocol for password-based, mutual +authentication over an insecure network connection. Successful SRP +authentication requires both sides of the connection to have knowledge +of the user's password. In addition to password verification, the SRP +protocol also performs a secure key exchange during the authentication +process. This key may be used to protect network traffic via symmetric +key encryption. + +SRP offers security and deployment advantages over other +challenge-response protocols in that it does not require trusted key +servers or certificate infrastructures (as do Kerberos and +SSL). Instead, small verification keys derived from each user's +password are stored and used by each SRP server +application. Consequently, SRP provides a near-ideal solution for many +applications requiring simple and secure password authentication +that does not rely on a properly configured, external infrastructure. + +Another favorable aspect of the SRP protocol is that compromized +verification keys are of little value to an attacker. Possesion of a +verification key does not allow a user to be impersonated +and it cannot be used to obtain the users password except by way of a +computationally infeasible dictionary attack. A compromized key would, +however, allow an attacker to impersonate the server side of an SRP +authenticated connection. Consequently, care should be taken to +prevent unauthorized access to verification keys for applications in +which the client side relies on the server being genuine. Usage ----- -Use of SRP begins by using the *create_salted_verification_key()* function to -create a salted verification key from the user's password. The resulting salt -and key are then stored on the server and will be used during the +SRP usage begins with *create_salted_verification_key()*. This function +creates a salted verification key from the user's password. The resulting salt +and key are stored by the server application and will be used during the authentication process. The authentication process occurs as an exchange of messages between the clent @@ -52,14 +52,19 @@ 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* constructors, as well as the *create_salted_verification_key()* -function, accept optional arguments to specify which hashing algorithm and -prime number arguments should be used during the authentication process. These -options may be used to tune the security/performance tradeoff for an application. -Generally speaking, specifying arguments with a higher number of bits will result -in a greater level of security. However, it will come at the cost of increased -computation time. The parameters passed to the *User* and *Verifier* constructors -must exactly match those passed to *create_salted_verification_key()* +The *User* & *Verifier* constructors, as well as the +*create_salted_verification_key()* function, accept optional arguments +to specify which hashing algorithm and prime number arguments should +be used during the authentication process. These options may be used +to tune the security/performance tradeoff for an application. +Generally speaking, specifying arguments with a higher number of bits +will result in a greater level of security. However, it will come at +the cost of increased computation time. The default values of SHA1 +hashes and 2048 bit prime numbers strike a good balance between +performance and security. These values should be sufficient for most +applications. Regardless of which values are used, the parameters +passed to the *User* and *Verifier* constructors must exactly match +those passed to *create_salted_verification_key()* .. _constants: @@ -213,9 +218,10 @@ the user's password. .. method:: User.verify_session( bytes_H_AMK ) - Complete the :class:`User` side of the authentication - process. If the authentication succeded :meth:`authenticated` will - return True + Complete the :class:`User` side of the authentication process. By + verifying the *bytes_H_AMK* value returned by + :meth:`Verifier.verify_session`. If the authentication succeded + :meth:`authenticated` will return True .. _example: @@ -288,9 +294,13 @@ substantial performance increase. SRP 6a Protocol Description --------------------------- -For the original, authoritative definition of SRP-6a please refer to -http://srp.stanford.edu. RFC 5054 also contains SRP related information and is -the source of the predefined N and g constants used in this implementation. +The original SRP protocol, known as SRP-3, is defined in +RFC 2945. This implementation, however, uses SRP-6a which is a slight +improvement over SRP-3. The authoritative definition for the SRP-6a +protocol is available at http://srp.stanford.edu. An additional +resource is RFC 5054 which covers the integration of SRP into +TLS. This RFC is the source of hashing strategy and the predefined N +and g constants used in this implementation. The following is a complete description of the SRP-6a protocol as implemented by this library. Note that the ^ symbol indicates exponentiaion and the | symbol -- cgit v1.2.3