diff options
Diffstat (limited to 'srp-1.0/srp/doc')
| -rw-r--r-- | srp-1.0/srp/doc/conf.py | 216 | ||||
| -rw-r--r-- | srp-1.0/srp/doc/index.rst | 22 | ||||
| -rw-r--r-- | srp-1.0/srp/doc/srp.rst | 377 |
3 files changed, 0 insertions, 615 deletions
diff --git a/srp-1.0/srp/doc/conf.py b/srp-1.0/srp/doc/conf.py deleted file mode 100644 index ba75a8c..0000000 --- a/srp-1.0/srp/doc/conf.py +++ /dev/null @@ -1,216 +0,0 @@ -# -*- coding: utf-8 -*- -# -# 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. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -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.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 = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -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 = '1.0' -# The full version, including alpha/beta/rc tags. -release = '1.0' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# 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 - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# 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 -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# 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 <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# 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 = 'SecureRemotePassworddoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'SecureRemotePassword.tex', u'Secure Remote Password Documentation', - u'Tom Cocagne', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# 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 = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#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/srp-1.0/srp/doc/index.rst b/srp-1.0/srp/doc/index.rst deleted file mode 100644 index 0c13606..0000000 --- a/srp-1.0/srp/doc/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. 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/srp-1.0/srp/doc/srp.rst b/srp-1.0/srp/doc/srp.rst deleted file mode 100644 index 9cdd967..0000000 --- a/srp-1.0/srp/doc/srp.rst +++ /dev/null @@ -1,377 +0,0 @@ -: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> - - -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, such as Kerberos and SSL, in that it -does not require trusted key servers or certificate infrastructures. -Instead, small verification keys derived from each user's password are -stored and used by each SRP server application. SRP provides a -near-ideal solution for many applications requiring simple and secure -password authentication that does not rely on an 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 ------ - -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 -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 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: - -Constants ---------- - -.. table:: Hashing Algorithm Constants - - ============== ============== - Hash Algorithm Number of Bits - ============== ============== - SHA1 160 - SHA224 224 - SHA256 256 - SHA384 384 - SHA512 512 - ============== ============== - -.. note:: - - Larger hashing algorithms will result in larger session keys. - -.. table:: Prime Number Constants - - ================= ============== - Prime Number Size Number of Bits - ================= ============== - NG_1024 1024 - NG_2048 2048 - NG_4096 4096 - NG_8192 8192 - NG_CUSTOM User Supplied - ================= ============== - -.. note:: - - If NG_CUSTOM is used, the 'n_hex' and 'g_hex' parameters are required. - These parameters must be ASCII text containing hexidecimal notation of the - prime number 'n_hex' and the corresponding generator number 'g_hex'. Appendix - A of RFC 5054 contains several large prime number, generator pairs that may - be used with NG_CUSTOM. - -Functions ---------- - -.. function:: create_salted_verification_key ( username, password[, hash_alg=SHA1, ng_type=NG_2048, n_hex=None, g_hex=None] ) - - *username* Name of the user - - *password* Plaintext user password - - *hash_alg*, *ng_type*, *n_hex*, *g_hex* Refer to the :ref:`constants` section. - - Generate a salted verification key for the given username and password and return the tuple: - (salt_bytes, verification_key_bytes) - - -:class:`Verifier` Objects -------------------------- - -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[, hash_alg=SHA1, ng_type=NG_2048, n_hex=None, g_hex=None] ) - - *username* Name of the remote user being authenticated. - - *bytes_s* Salt generated by :func:`create_salted_verification_key`. - - *bytes_v* Verification Key generated by :func:`create_salted_verification_key`. - - *bytes_A* Challenge from the remote user. Generated by - :meth:`User.start_authentication` - - *hash_alg*, *ng_type*, *n_hex*, *g_hex* Refer to the :ref:`constants` section. - - .. method:: Verifier.authenticated() - - Return True if the authentication succeeded. False - otherwise. - - .. method:: Verifier.get_username() - - Return the name of the user this :class:`Verifier` object is for. - - .. method:: Verifier.get_session_key() - - Return the session key for an authenticated user or None if the - authentication failed or has not yet completed. - - .. method:: Verifier.get_challenge() - - Return (bytes_s, bytes_B) on success or (None, None) if - authentication has failed. - - .. method:: Verifier.verify_session( user_M ) - - Complete 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 prove a user's identity to a remote :class:`Verifier` and -verifiy that the remote :class:`Verifier` knows the verification key associated with -the user's password. - -.. class:: User( username, password[, hash_alg=SHA1, ng_type=NG_2048, n_hex=None, g_hex=None] ) - - *username* Name of the user being authenticated. - - *password* Password for the user. - - *hash_alg*, *ng_type*, *n_hex*, *g_hex* Refer to the :ref:`constants` section. - - .. method:: User.authenticated() - - Return True if authentication succeeded. False - otherwise. - - .. method:: User.get_username() - - Return the username passed to the constructor. - - .. method:: User.get_session_key() - - Return the session key if authentication succeeded or None if the - authentication failed or has not yet completed. - - .. method:: User.start_authentication() - - Return (username, bytes_A). These should be passed to the - constructor of the remote :class:`Verifer` - - .. method:: User.process_challenge( bytes_s, bytes_B ) - - Processe 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:: User.verify_session( bytes_H_AMK ) - - 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: - -Example -------- - -Simple Usage Example:: - - import srp - - # The salt and verifier returned from srp.create_salted_verification_key() should be - # stored on the server. - salt, vkey = srp.create_salted_verification_key( 'testuser', 'testpassword' ) - - class AuthenticationFailed (Exception): - pass - - # ~~~ 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, vkey, A ) - s,B = svr.get_challenge() - - if s is None or B is None: - raise AuthenticationFailed() - - # Server => Client: s, B - M = usr.process_challenge( s, B ) - - if M is None: - raise AuthenticationFailed() - - # Client => Server: M - HAMK = svr.verify_session( M ) - - if HAMK is None: - raise AuthenticationFailed() - - # Server => Client: HAMK - usr.verify_session( HAMK ) - - # At this point the authentication process is complete. - - assert usr.authenticated() - assert svr.authenticated() - - - -Implementation Notes --------------------- - -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. - - -.. _protocol-description: - -SRP 6a Protocol Description ---------------------------- - -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 -indicates concatenation. - -.. rubric:: Primary Variables used in SRP 6a - -========= ================================================================= -Variables Description -========= ================================================================= -N A large, safe prime (N = 2q+1, where q is a Sophie Germain prime) - All arithmetic is performed in the field of integers modulo N -g A generator modulo N -s Small salt for the verification key -I Username -p Cleartext password -H() One-way hash function -a,b Secret, random values -K Session key -========= ================================================================= - - -.. rubric:: Derived Values used in SRP 6a - -====================================== ==================================== -Derived Values Description -====================================== ==================================== -k = H(N,g) Multiplier Parameter -A = g^a Public ephemeral value -B = kv + g^b Public ephemeral value -x = H(s, H( I | ':' | p )) Private key (as defined by RFC 5054) -v = g^x Password verifier -u = H(A,B) Random scrambling parameter -M = H(H(N) xor H(g), H(I), s, A, B, K) Session key verifier -====================================== ==================================== - - -.. rubric:: Protocol Description - -The server stores the password verifier *v*. Authentication begins with a -message from the client:: - - client -> server: I, A = g^a - -The server replies with the verifier salt and challenge:: - - server -> client: s, B = kv + g^b - -At this point, both the client and server calculate the shared session key:: - - client & server: u = H(A,B) - -:: - - server: K = H( (Av^u) ^ b ) - -:: - - client: x = H( s, H( I + ':' + p ) ) - client: K = H( (B - kg^x) ^ (a + ux) ) - -Now both parties have a shared, strong session key *K*. To complete -authentication they need to prove to each other that their keys match:: - - client -> server: M = H(H(N) xor H(g), H(I), s, A, B, K) - server -> client: H(A, M, K) - -SRP 6a requires the two parties to use the following safeguards: - -1. The client will abort if it recieves B == 0 (mod N) or u == 0 -2. The server will abort if it detects A == 0 (mod N) -3. The client must show its proof of K first. If the server detects that this - proof is incorrect it must abort without showing its own proof of K - |