diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 25 | ||||
| -rw-r--r-- | docs/contents.rst | 31 | ||||
| -rw-r--r-- | docs/index.rst | 109 | ||||
| -rw-r--r-- | docs/lib/passlib.context-tutorial.rst | 11 | ||||
| -rw-r--r-- | docs/lib/passlib.context.rst | 9 | ||||
| -rw-r--r-- | docs/lib/passlib.exc.rst | 6 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.bcrypt.rst | 9 | ||||
| -rw-r--r-- | docs/lib/passlib.hash.rst | 186 | ||||
| -rw-r--r-- | docs/lib/passlib.pwd.rst | 2 | ||||
| -rw-r--r-- | docs/lib/passlib.totp-tutorial.rst | 36 | ||||
| -rw-r--r-- | docs/lib/passlib.totp.rst | 40 | ||||
| -rw-r--r-- | docs/modular_crypt_format.rst | 30 | ||||
| -rw-r--r-- | docs/new_app_quickstart.rst | 21 | ||||
| -rw-r--r-- | docs/password_hash_api.rst | 2 |
14 files changed, 272 insertions, 245 deletions
diff --git a/docs/conf.py b/docs/conf.py index 7c703e0..4761304 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,9 +66,6 @@ extensions = [ # allow table column alignment styling 'cloud_sptheme.ext.table_styling', - # modify logo per page - 'cloud_sptheme.ext.perpage', - # monkeypatch sphinx to support a few extra things we can't do with extensions. 'cloud_sptheme.ext.autodoc_sections', 'cloud_sptheme.ext.autoattribute_search_bases', @@ -94,7 +91,8 @@ index_doc = 'index' # General information about the project. project = 'Passlib' author = "Assurance Technologies, LLC" -copyright = "2008-%d, %s" % (datetime.date.today().year, author) +updated = datetime.date.today().isoformat() +copyright = "2008-%d, %s. Last Updated %s" % (datetime.date.today().year, author, updated) # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -147,6 +145,9 @@ pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. modindex_common_prefix = ["passlib."] +# appended to all pages +rst_epilog = "\n.. |updated| replace:: %s\n" % updated + #============================================================================= # Options for all output #============================================================================= @@ -172,14 +173,16 @@ if csp.is_cloud_theme(html_theme): # lighter_decor=True, borderless_decor=True, sidebarbgcolor='transparent', + small_sidebar_bg_color='#EBEBEB', bodytrimcolor='transparent', max_width="12.5in", sidebarwidth="3in", large_sidebar_width="3.5in", hyphenation_language="en", headfont='"Bitstream Vera Sans", sans-serif', - bodyfont='arial, helvetica, sans-serif', + # bodyfont='arial, helvetica, sans-serif', relbarbgcolor='#821f4d', + footerbgcolor='#521330', sectionbgcolor='#964361', rubricbgcolor='#B4748B', sidebarlinkcolor='#6A3051', @@ -207,9 +210,6 @@ html_short_title = "%s %s Documentation" % (project, version) # The name of an image file (relative to this directory) to place at the top # of the sidebar. html_logo = os.path.join("_static", "masthead.png") -perpage_html_logo = { - 'index': 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 @@ -230,14 +230,7 @@ html_static_path = ['_static'] html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -# common_sidebars = ['quicklinks.html', 'searchbox.html'] -# html_sidebars = { -# '**': ['localtoc.html', 'relations.html'] + common_sidebars, -# 'py-modindex': common_sidebars, -# 'genindex': common_sidebars, -# 'search': common_sidebars, -# } -html_sidebars = {'**': ['globaltoc.html', 'searchbox.html']} +html_sidebars = {'**': ['searchbox.html', 'globaltoc.html']} # Additional templates that should be rendered to pages, maps page names to # template names. diff --git a/docs/contents.rst b/docs/contents.rst index 309d7cb..0be84f5 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -5,33 +5,10 @@ Table Of Contents .. toctree:: :maxdepth: 4 - Front Page <index> - install - - overview - new_app_quickstart - - lib/passlib.hash - - lib/passlib.context-tutorial - lib/passlib.context - lib/passlib.apps - lib/passlib.hosts - - lib/passlib.apache - lib/passlib.ext.django - lib/passlib.pwd - lib/passlib.totp - - lib/passlib.exc - lib/passlib.registry - lib/passlib.utils - lib/passlib.crypto - - modular_crypt_format - - history - copyright + Introduction <index> + narrative + reference + other * :ref:`General Index <genindex>` * :ref:`Module List <modindex>` diff --git a/docs/index.rst b/docs/index.rst index f22231f..7f9aace 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,10 @@ .. image:: _static/masthead.png :align: center + :class: show-for-small + +.. rst-class:: float-right without-title + +.. seealso:: :ref:`What's new in Passlib 1.7 <whats-new>` ========================================== Passlib |release| documentation @@ -38,88 +43,29 @@ using the :doc:`PBKDF2-SHA256 </lib/passlib.hash.pbkdf2_digest>` algorithm:: >>> pbkdf2_sha256.verify("joshua", hash) False -Content Summary -=============== - -.. rst-class:: float-right inline-title - -.. seealso:: :ref:`What's new in Passlib 1.7 <whats-new>` - -Introductory Materials ----------------------- - - :doc:`install` - requirements & installation instructions - - :doc:`overview` - describes how Passlib is laid out +.. rst-class:: toc-always-open - :doc:`New Application Quickstart <new_app_quickstart>` - choosing a password hash for new applications - ----- - -Password Hashing Algorithms ---------------------------- - :mod:`passlib.hash` - all the password hashes supported by Passlib -- - - :doc:`Overview <lib/passlib.hash>` - - :ref:`mcf-hashes` - - :ref:`ldap-hashes` - - :ref:`database-hashes` - - :ref:`windows-hashes` - - :ref:`other-hashes` - - :doc:`PasswordHash interface <password_hash_api>` - examples & documentation of the common hash interface - used by all the hash algorithms in Passlib. - -CryptContext Objects --------------------- - :mod:`passlib.context` - provides the :class:`!CryptContext` class, a flexible container - for managing and migrating between multiple hash algorithms. - - :mod:`passlib.apps` - predefined CryptContext objects for managing the hashes used by - MySQL, PostgreSQL, OpenLDAP, and others applications. - - :mod:`passlib.hosts` - predefined CryptContext objects for managing the hashes - found in Linux & BSD "shadow" files. - -Application Helpers -------------------- - :mod:`passlib.apache` - classes for manipulating Apache's ``htpasswd`` and ``htdigest`` files. - - :mod:`passlib.ext.django` - Django plugin which monkeypatches support for (almost) any hash in Passlib. +Getting Started +=============== - :mod:`passlib.pwd` - Password generation helpers. +This documentation is organized into two main parts: +a narrative walkthrough of Passlib, and a top-down API reference. - :mod:`passlib.totp` - TOTP / Two Factor Authentication +:doc:`narrative` -.. - Support Modules - --------------- - :mod:`passlib.exc` + New users in particular will want to visit the walkthrough, as it provides + introductory documentation including installation requirements, + an overview of what passlib provides, and a guide for getting started quickly. - custom warnings and exceptions used by Passlib - :mod:`passlib.registry` - :mod:`passlib.utils` +:doc:`reference` ----- + The API reference contains a top-down reference of the :mod:`!passlib` package. -Other Documents ---------------- - :doc:`modular_crypt_format` - reference listing "modular crypt format" support across Unix systems. +:doc:`other` - :doc:`Changelog <history>` - Passlib's release history + This section contains additional things that don't + fit anywhere else, including an :doc:`FAQ <faq>` and a complete + :doc:`changelog <history>`. Online Resources ================ @@ -128,12 +74,9 @@ Online Resources :class: fullwidth :column-alignment: lr - ================ =================================================== - Homepage: `<https://bitbucket.org/ecollins/passlib>`_ - Online Docs: `<http://packages.python.org/passlib>`_ - Discussion: `<http://groups.google.com/group/passlib-users>`_ - ---------------- --------------------------------------------------- - ---------------- --------------------------------------------------- - Downloads: `<https://pypi.python.org/pypi/passlib>`_ - Source: `<https://bitbucket.org/ecollins/passlib/src>`_ - ================ =================================================== + =================== =================================================== + Latest Docs: `<http://packages.python.org/passlib>`_ + Project Home: `<https://bitbucket.org/ecollins/passlib>`_ + News & Discussion: `<http://groups.google.com/group/passlib-users>`_ + Downloads @ PyPI: `<https://pypi.python.org/pypi/passlib>`_ + =================== =================================================== diff --git a/docs/lib/passlib.context-tutorial.rst b/docs/lib/passlib.context-tutorial.rst index 19bdb2b..9d0cdc3 100644 --- a/docs/lib/passlib.context-tutorial.rst +++ b/docs/lib/passlib.context-tutorial.rst @@ -3,12 +3,11 @@ .. _context-overview: .. _context-tutorial: -========================================================= -:mod:`passlib.context` - CryptContext Overview & Tutorial -========================================================= +.. currentmodule:: passlib.context -.. module:: passlib.context - :synopsis: CryptContext class, for managing multiple password hash schemes +============================================== +:mod:`passlib.context` - CryptContext Tutorial +============================================== Overview ======== @@ -26,7 +25,7 @@ password hashes at once: The following sections contain a walkthrough of this class, starting with some simple examples, and working up to a complex "full-integration" example. -.. seealso:: The :ref:`CryptContext Reference <context-reference>` document, +.. seealso:: The :mod:`passlib.context` api reference, which lists all the options and methods supported by this class. .. index:: CryptContext; usage examples diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst index 72524e8..ecb954d 100644 --- a/docs/lib/passlib.context.rst +++ b/docs/lib/passlib.context.rst @@ -1,11 +1,12 @@ .. index:: CryptContext; reference -.. currentmodule:: passlib.context +.. module:: passlib.context + :synopsis: CryptContext class, for managing multiple password hash schemes .. _context-reference: ====================================================== -:mod:`passlib.context` - CryptContext Reference +:mod:`passlib.context` - CryptContext ====================================================== This page provides a complete reference of all the methods and options supported by the :class:`!CryptContext` class @@ -16,7 +17,7 @@ and helper utilities. * :ref:`CryptContext Overview & Tutorial <context-overview>` -- overview of this class and walkthrough of how to use it. -.. rst-class:: emphasize-children +.. rst-class:: emphasize-children toc-always-open The CryptContext Class ====================== @@ -45,7 +46,7 @@ The CryptContext Class .. index:: CryptContext; keyword options -.. rst-class:: html-toggle expanded +.. rst-class:: html-toggle expanded toc-always-open Constructor Keywords -------------------- diff --git a/docs/lib/passlib.exc.rst b/docs/lib/passlib.exc.rst index f90f330..4b36a2b 100644 --- a/docs/lib/passlib.exc.rst +++ b/docs/lib/passlib.exc.rst @@ -1,6 +1,6 @@ -=============================================================== -:mod:`passlib.exc` - exceptions and warnings raised by Passlib -=============================================================== +============================================ +:mod:`passlib.exc` - Exceptions and warnings +============================================ .. module:: passlib.exc :synopsis: exceptions & warnings raised by Passlib diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst index e5a7a56..946c5ff 100644 --- a/docs/lib/passlib.hash.bcrypt.rst +++ b/docs/lib/passlib.hash.bcrypt.rst @@ -82,11 +82,14 @@ you need to upgrade the external package being used as the backend Format & Algorithm ================== -Bcrypt is compatible with the :ref:`modular-crypt-format`, and uses ``$2$`` and ``$2a$`` as the identifying prefix -for all its strings (``$2$`` is seen only for legacy hashes which used an older version of Bcrypt). +Bcrypt is compatible with the :ref:`modular-crypt-format`, and uses a number of identifying +prefixes: ``$2$``, ``$2a$``, ``$2x$``, ``$2y$``, and ``$2b$``. Each prefix indicates +a different revision of the BCrypt algorithm; and all but the ``$2b$`` identifier are +considered deprecated. + An example hash (of ``password``) is: - ``$2a$12$GhvMmNVjRW29ulnudl.LbuAnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m`` + ``$2b$12$GhvMmNVjRW29ulnudl.LbuAnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m`` Bcrypt hashes have the format :samp:`$2a${rounds}${salt}{checksum}`, where: diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst index e17b710..03a28b1 100644 --- a/docs/lib/passlib.hash.rst +++ b/docs/lib/passlib.hash.rst @@ -8,20 +8,30 @@ Overview ======== The :mod:`!passlib.hash` module contains all the password hash algorithms built into Passlib. -While each hash has its own options and output format, they all share a common interface, -documented in detail in the :ref:`password-hash-api`. The following pages -describe the common interface, and then describe each hash in detail -(including its format, underlying algorithm, and known security issues). +While each hash has its own options and output format, +they all inherit from the :mod:`passlib.ifc`.\ :class:`!PasswordHash` API. +The following pages describe each hash in detail, +including its format, underlying algorithm, and known security issues. -.. seealso:: :doc:`Quickstart Guide </new_app_quickstart>` -- advice on - choosing an appropriately secure hash for your new application. +.. warning:: + + **Many of the hash algorithms listed below are *NOT* secure.** + + Passlib supports a wide array of hash algorithms, primarily to + support dealing with legacy data and systems. + + If you're looking to choose a hash algorithm for a new application, + see the :doc:`Quickstart Guide </new_app_quickstart>` instead of picking + one from this list. + +.. rst-class:: html-toggle Usage -===== -All of the hashes in this module can used in two ways: +----- +All of the hashes in this module can be used in two ways: -1. They can be imported and used directly, as in the following example - with the :class:`md5_crypt` hash:: +1. They can be imported from :mod:`!passlib.hash` and used directly, + as in the following example with the :class:`md5_crypt` hash:: >>> # import the desired hash >>> from passlib.hash import md5_crypt @@ -61,87 +71,124 @@ All of the hashes in this module can used in two ways: >>> pwd_context.verify("letmein", hash2) True -For additional details, usage examples, and full documentation of all -methods and attributes provided by the common hash interface: - -.. toctree:: - :maxdepth: 2 +.. seealso:: - /password_hash_api + For additional details and usage examples, see the + :doc:`PasswordHash </password_hash_api>` and :doc:`CryptContext </lib/passlib.context>` + reference. .. _mcf-hashes: -Unix & "Modular Crypt" Hashes -============================= -Aside from the "archaic" schemes below, most modern Unix flavors -use password hashes which follow the :ref:`modular crypt format <modular-crypt-format>`, +Unix Hashes +=========== +Aside from "archaic" schemes such as :class:`!des_crypt`, +most of the password hashes supported by modern Unix flavors +adhere to the :ref:`modular crypt format <modular-crypt-format>`, allowing them to be easily distinguished when used within the same file. -The basic format :samp:`${scheme}${hash}` has also been adopted for use +The basic of format :samp:`${scheme}${hash}` has also been adopted for use by other applications and password hash schemes. -.. _archaic-unix-schemes: +.. _standard-unix-hashes: -Archaic Unix Schemes --------------------- -All of the following hashes are/were used by various Unix flavors -to store user passwords; most are based on the DES block cipher, -and predate the arrival of the modular crypt format. -They should all be considered insecure at best, but may be useful when reading -legacy password entries: +.. rst-class:: toc-always-open + +Active Unix Hashes +------------------ +All these schemes are actively in use by various Unix flavors to store user passwords. +They all follow the modular crypt format. .. toctree:: :maxdepth: 1 - passlib.hash.des_crypt - passlib.hash.bsdi_crypt - passlib.hash.bigcrypt - passlib.hash.crypt16 + passlib.hash.bcrypt + passlib.hash.sha256_crypt + passlib.hash.sha512_crypt -.. _standard-unix-hashes: +Special note should be made of the following fallback helper, +which is not an actual hash scheme, but implements the "disabled account marker" +found in many Linux & BSD password files: -Standard Unix Schemes ---------------------- -All these schemes are currently used by various Unix flavors to store user passwords. -They all follow the modular crypt format. +.. toctree:: + :maxdepth: 1 + + passlib.hash.unix_disabled + +.. rst-class:: toc-always-open + +Deprecated Unix Hashes +---------------------- +The following schemes are supported by various Unix systems +use the modular crypt format, and are noticably stronger than the previous group. +However, they have all since been deprecated in favor of stronger algorithms: + +* :class:`passlib.hash.bsd_nthash` - FreeBSD's MCF-compatible encoding of :doc:`nthash <passlib.hash.nthash>` digests .. toctree:: :maxdepth: 1 passlib.hash.md5_crypt - passlib.hash.bcrypt passlib.hash.sha1_crypt passlib.hash.sun_md5_crypt - passlib.hash.sha256_crypt - passlib.hash.sha512_crypt -Other Modular Crypt Schemes ---------------------------- -While most of these schemes are not (commonly) used by any Unix flavor to store user passwords, -they can be used compatibly along side other modular crypt format hashes. +.. _archaic-unix-schemes: + +.. rst-class:: toc-always-open + +Archaic Unix Hashes +------------------- +The following schemes are supported by certain Unix systems, +but are considered particularly archaic: Not only do they predate +the modular crypt format, but they're based on the outmoded DES block cipher, +and are woefully insecure: .. toctree:: :maxdepth: 1 - passlib.hash.apr_md5_crypt + passlib.hash.des_crypt + passlib.hash.bsdi_crypt + passlib.hash.bigcrypt + passlib.hash.crypt16 + +Other "Modular Crypt" Hashes +============================ +The :ref:`modular crypt format <modular-crypt-format>` is a loose standard +for password hash strings which started life under the Unix operating system, +and is used by many of the Unix hashes (above). However, it's +it's basic :samp:`${scheme}${hash}` format has also been adopted by a number +of application-specific hash algorithms: + +.. rst-class:: toc-always-open + +Active Hashes +------------- +While most of these schemes generally require an application-specific +implementation, natively used by any Unix flavor to store user passwords, +they can be used compatibly along side other modular crypt format hashes: + +.. toctree:: + :maxdepth: 1 + + passlib.hash.argon2 passlib.hash.bcrypt_sha256 passlib.hash.phpass passlib.hash.pbkdf2_digest - passlib.hash.cta_pbkdf2_sha1 - passlib.hash.dlitz_pbkdf2_sha1 passlib.hash.scram passlib.hash.scrypt - passlib.hash.argon2 -* :class:`passlib.hash.bsd_nthash` - FreeBSD's MCF-compatible :doc:`nthash <passlib.hash.nthash>` encoding +.. rst-class:: toc-always-open -Special note should be made of the fallback helper, -which is not an actual hash scheme, but provides "disabled account" -behavior found in many Linux & BSD password files: +Deprecated Hashes +----------------- +The following are some additional application-specific hashes which are still +occasionally seen, use the modular crypt format, but are rarely used or weak +enough that they have been deprecated: .. toctree:: :maxdepth: 1 - passlib.hash.unix_disabled + passlib.hash.apr_md5_crypt + passlib.hash.cta_pbkdf2_sha1 + passlib.hash.dlitz_pbkdf2_sha1 .. _ldap-hashes: @@ -152,9 +199,6 @@ All of the following hashes use a variant of the password hash format used by LDAPv2. Originally specified in :rfc:`2307` and used by OpenLDAP [#openldap]_, the basic format ``{SCHEME}HASH`` has seen widespread adoption in a number of programs. -.. [#openldap] OpenLDAP homepage - `<http://www.openldap.org/>`_. - - .. _standard-ldap-hashes: Standard LDAP Schemes @@ -237,13 +281,11 @@ no identifying markers, identifying them is pretty much context-dependant. passlib.hash.msdcc passlib.hash.msdcc2 -.. _other-hashes: +.. rst-class:: toc-always-toggle -Other Hashes +Cisco Hashes ============ -The following schemes are used in various contexts, -but have formats or uses which cannot be easily placed -in one of the above categories: +The following hashes are used in various places on Cisco IOS and ASA devices: .. toctree:: :maxdepth: 1 @@ -251,13 +293,31 @@ in one of the above categories: passlib.hash.cisco_pix passlib.hash.cisco_asa -* *Cisco "Type 5" hashes* - see :doc:`md5_crypt <passlib.hash.md5_crypt>` +* **Cisco "Type 5" hashes** - these are the same as :doc:`md5_crypt <passlib.hash.md5_crypt>` .. toctree:: :maxdepth: 1 passlib.hash.cisco_type7 + +.. _other-hashes: + +Other Hashes +============ +The following schemes are used in various contexts, +but have formats or uses which cannot be easily placed +in one of the above categories: + +.. toctree:: + :maxdepth: 1 + passlib.hash.django_std passlib.hash.grub_pbkdf2_sha512 passlib.hash.hex_digests passlib.hash.plaintext + +.. rubric:: Footnotes + +.. [#openldap] OpenLDAP homepage - `<http://www.openldap.org/>`_. + + diff --git a/docs/lib/passlib.pwd.rst b/docs/lib/passlib.pwd.rst index 0b4b556..505230c 100644 --- a/docs/lib/passlib.pwd.rst +++ b/docs/lib/passlib.pwd.rst @@ -2,7 +2,7 @@ :synopsis: password generation helpers ================================================= -:mod:`passlib.pwd` -- password generation helpers +:mod:`passlib.pwd` -- Password generation helpers ================================================= .. versionadded:: 1.7 diff --git a/docs/lib/passlib.totp-tutorial.rst b/docs/lib/passlib.totp-tutorial.rst new file mode 100644 index 0000000..0982825 --- /dev/null +++ b/docs/lib/passlib.totp-tutorial.rst @@ -0,0 +1,36 @@ +.. index:: TOTP; overview +.. _totp-tutorial: + +.. currentmodule:: passlib.totp + +=================================== +:mod:`passlib.totp` - TOTP Tutorial +=================================== + +Overview +======== +The :mod:`passlib.totp` module provides a set of classes for adding +two-factor authentication (2FA) support into your application, +using the widely supported TOTP / HOTP specifications. + +This module provides a number of classes, designed to support a variety +of use cases, including: + + * Low-level methods for calculating tokens on the client side. + + * Low-level methods for generating OTP keys & verifying tokens on the server side. + + * High level methods for server-side storage of OTP keys *along with + state and history*, making it easy to add TOTP integration. + +.. seealso:: The :mod:`passlib.totp` api reference, + which lists all details of all the classes and methods mentioned here. + +.. index:: TOTP; usage examples + +.. rst-class:: emphasize-children + +Tutorial / Walkthrough +====================== + +.. todo:: this content needs writing
\ No newline at end of file diff --git a/docs/lib/passlib.totp.rst b/docs/lib/passlib.totp.rst index fdb5fe4..961bf46 100644 --- a/docs/lib/passlib.totp.rst +++ b/docs/lib/passlib.totp.rst @@ -5,14 +5,14 @@ :mod:`passlib.totp` -- TOTP / Two Factor Authentication ======================================================= -.. versionadded:: 1.7 - .. todo:: This module is still a work in progress, it's API may change before release. Things left: + * convert TOTP 'offset' to 'skew' (inverting sense) + * TOTO & helper should track *next* counter, to match HTOP (as well as default reuse=False behavior) * finish unittests (there are a few cases left) * write narrative documentation * get api documentation formatted better (whether by getting nested sections integrated into TOC, @@ -24,34 +24,35 @@ * more verification against other TOTP servers & clients. * consider native pyqrcode integration (e.g. a ``to_qrcode()`` method) -.. rst-class:: emphasize-children +.. versionadded:: 1.7 + +The :mod:`!passlib.totp` module provides a number of classes for implementing +two-factor authentication (2FA) using the TOTP / HOTP specifications. +This page provides a reference to all the classes and methods in this module. -API Reference -============= +.. seealso:: + + * :ref:`TOTP Tutorial <totp-overview>` -- + overview of this module and walkthrough of how to use it. + +.. rst-class:: emphasize-children OTPContext ----------- +========== .. autoclass:: OTPContext .. autofunction:: generate_secret Common Interface ----------------- +================ .. autoclass:: BaseOTP() TOTP (Timed-based tokens) -------------------------- +========================= .. autoclass:: TOTP(key=None, format="base32", \*, new=False, \*\*kwds) -Helper Classes -.............. - -.. autoclass:: TotpToken() - -.. autoclass:: TotpMatch() - HOTP (Counter-based tokens) ---------------------------- +=========================== .. note:: HOTP is used much less frequently, since it's fragile @@ -60,9 +61,10 @@ HOTP (Counter-based tokens) .. autoclass:: HOTP(key=None, format="base32", \*, new=False, \*\*kwds) -Helper Classes -.............. - +Support Classes +=============== +.. autoclass:: TotpToken() +.. autoclass:: TotpMatch() .. autoclass:: HotpMatch() Deviations diff --git a/docs/modular_crypt_format.rst b/docs/modular_crypt_format.rst index 86988a6..43dc846 100644 --- a/docs/modular_crypt_format.rst +++ b/docs/modular_crypt_format.rst @@ -8,7 +8,14 @@ Modular Crypt Format ==================== -.. centered:: *or*, a side note about a standard that isn't +.. rst-class:: subtitle + + A explanation about a standard that isn't + +Overview +======== +A number of the hashes in Passlib are described as adhering to the "Modular Crypt Format". +This page is an attempt to document what that means. In short, the modular crypt format (MCF) is a standard for encoding password hash strings, which requires hashes @@ -18,9 +25,12 @@ identifying a particular scheme, and :samp:`{content}` is the contents of the scheme, using only the characters in the regexp range ``[a-zA-Z0-9./]``. -However, there appears to be no central registry of identifiers, -no specification document, and no actual rules; -so the modular crypt format is more of an ad-hoc idea rather than a true standard. +However, there's no official specification document describing this format. +Nor is there a central registry of identifiers, or actual rules. +The modular crypt format is more of an ad-hoc idea rather than a true standard. + +The rest of this page is an attempt to describe what is known, +at least as far as the hashes supported by Passlib. History ======= @@ -73,11 +83,10 @@ by the modular crypt format hashes found in Passlib: they may use the ``$`` character as an internal field separator. This is the least adhered-to of any modular crypt format convention. - Other characters (such as ``+=,-``) are sometimes - used by various formats, though sparingly. + Other characters (such as ``+=,-``) are used by various formats. The only hard and fast stricture - is that ``:;!*`` and all non-printable characters be avoided, + is that ``:;!*`` and all non-printable or 8-bit characters be avoided, since this would interfere with parsing of the Unix shadow password file, where these hashes are typically stored. @@ -142,7 +151,8 @@ and indicates which operating systems offer native support: :class:`~passlib.hash.bsdi_crypt` ``_`` y y y :class:`~passlib.hash.md5_crypt` ``$1$`` y y y y y :class:`~passlib.hash.bcrypt` ``$2$``, ``$2a$``, - ``$2x$``, ``$2y$`` y y y y + ``$2x$``, ``$2y$`` + ``$2b$`` y y y y :class:`~passlib.hash.bsd_nthash` ``$3$`` y :class:`~passlib.hash.sha256_crypt` ``$5$`` y 8.3+ y :class:`~passlib.hash.sha512_crypt` ``$6$`` y 8.3+ y @@ -165,7 +175,7 @@ by the following operating systems and platforms: **Google App Engine** As of 2011-08-19, Google App Engine's :func:`!crypt` implementation appears to match that of a typical Linux - system. + system (as listed in the previous table). ===================== ============================================================== Application-Defined Hashes @@ -183,6 +193,8 @@ These hashes can be found in various libraries and applications Scheme Prefix Primary Use (if known) =========================================== =================== =========================== :class:`~passlib.hash.apr_md5_crypt` ``$apr1$`` Apache htdigest files + :class:`~passlib.hash.argon2` ``$argon2i$``, + ``$argon2d$`` :class:`~passlib.hash.bcrypt_sha256` ``$bcrypt-sha256$`` Passlib-specific :class:`~passlib.hash.phpass` ``$P$``, ``$H$`` PHPass-based applications :class:`~passlib.hash.pbkdf2_sha1` ``$pbkdf2$`` Passlib-specific diff --git a/docs/new_app_quickstart.rst b/docs/new_app_quickstart.rst index 2dccb30..51a7ae0 100644 --- a/docs/new_app_quickstart.rst +++ b/docs/new_app_quickstart.rst @@ -38,6 +38,7 @@ instance; see below for more... .. index:: Passlib; recommended hash algorithms .. _recommended-hashes: +.. rst-class:: toc-always-open Choosing a Hash ================ @@ -187,20 +188,20 @@ For new applications, this decision comes down to a couple of questions: 1. Does the hash need to be natively supported by your operating system's :func:`!crypt` api, in order to allow inter-operation with third-party applications on the host? - * If so, the right choice is either :class:`~passlib.hash.bcrypt` for BSD variants, + * If yes, the right choice is either :class:`~passlib.hash.bcrypt` for BSD variants, or :class:`~passlib.hash.sha512_crypt` for Linux; since these are natively supported. - * If not, continue... + * If no, continue... -2. Does your hosting prevent you from installing C extensions? +2. Does your hosting provider allow you to install C extensions? - * If yes, you probably want to use :class:`~passlib.hash.pbkdf2_sha256` / :class:`~passlib.hash.pbkdf2_sha512`; - This is currently the option with the fastest pure-python backend. + * If no, you probably want to use :class:`~passlib.hash.pbkdf2_sha256`, + as this currently has the fastest pure-python backend. * If they allow C extensions, continue... -3. Do you want to use the latest, greatest, and don't mind increased memory usage - per hash? +3. Do you want to use the latest & greatest, and don't mind increased memory usage + when hashing? * :class:`~passlib.hash.argon2` is a next-generation hashing algorithm, attempting to become the new standard. It's design has been being slightly tweaked @@ -208,12 +209,12 @@ For new applications, this decision comes down to a couple of questions: You'll need to install the `argon2_cffi <https://pypi.python.org/pypi/argon2_cffi>`_ support library. - * If you want something secure, but battle tested, continue... + * If you want something secure, but more battle tested, continue... -4. The top two choices left are :class:`~passlib.hash.bcrypt` and :class:`~passlib.hash.pbkdf2_sha256`. +4. The top choices left are :class:`~passlib.hash.bcrypt` and :class:`~passlib.hash.pbkdf2_sha256`. Both have advantages, and their respective rough edges; - though currently the balance is in favor of :class:`~passlib.hash.bcrypt` + though currently the balance is in favor of bcrypt (pbkdf2 can be cracked somewhat more efficiently). * If choosing bcrypt, we strongly recommend installing the `bcrypt <https://pypi.python.org/pypi/bcrypt>`_ diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst index bd8168b..a2daf45 100644 --- a/docs/password_hash_api.rst +++ b/docs/password_hash_api.rst @@ -8,7 +8,7 @@ .. _password-hash-api: ============================================= -Password Hash Interface +:mod:`passlib.ifc` -- Password Hash Interface ============================================= Overview |