diff options
Diffstat (limited to 'docs/overview.rst')
| -rw-r--r-- | docs/overview.rst | 138 |
1 files changed, 58 insertions, 80 deletions
diff --git a/docs/overview.rst b/docs/overview.rst index c9aad2c..899b7fe 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -8,96 +8,74 @@ as stored in mysql and postgres, and various other places. Passlib's contents can be roughly grouped into three categories: password hashes, password contexts, and utility functions. -.. note:: - - New applications which just need drop-in password hashing support - should see the :doc:`new_app_quickstart`. - Password Hashes =============== All of the hash schemes supported by Passlib are implemented -as classes importable from the :mod:`passlib.hash` module. -All of these classes support a single uniform interface of standard class methods. -These methods are documented in detail by the :ref:`password hash api <password-hash-api>`. - -As a quick example of how a password hash can be used directly:: - - >>> #import the SHA512-Crypt class: - >>> from passlib.hash import sha512_crypt as sc - - >>> #generate new salt, encrypt password: - >>> h = sc.encrypt("password") - >>> h - '$6$rounds=40000$xCsOXRqPPk5AGDFu$o5eyqxEoOSq0dLRFbPxEHp5Jc1vFVj47BNT.h9gmjSHXDS15mjIM.GSUaT5r6Z.Xa1Akrv4FAgKJE3EfbkJxs1' - - >>> #same, but with explict number of rounds: - >>> sc.encrypt("password", rounds=10000) - '$6$rounds=10000$QWT8AlDMYRms7vSx$.1267Pg6Opn9CblFndtBJ2Q0AI0fcI2IX93zX3gi1Qse./j.VlKYX59NIUlbs0A66wCbfu/vra9wMv2uwTZAI.' - - >>> #check if string is recognized as belonging to this hash scheme: - >>> sc.identify(h) - True - >>> #check if some other hash is recognized: - >>> sc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') - False - - >>> #verify correct password: - >>> sc.verify("password", h) - True - >>> #verify incorrect password: - >>> sc.verify("secret", h) - False +as classes which can be imported from the :mod:`passlib.hash` module. +In turn, all of the hash classes implement a single uniform interface, +which is documented in detail and with usage examples in the +:ref:`password-hash-api` document. +However, many of these hashes are severely insecure, provided only for legacy +purposes, or are specialized in ways that are not generally useful. +If you are creating a new application and need to choose a password hash, +see the :doc:`new_app_quickstart`. + +.. seealso:: + + - :mod:`passlib.hash` -- all the hashes supported by Passlib. + - :ref:`password-hash-api` -- documentation of the common PasswordHash interface. + - :doc:`new_app_quickstart` -- choosing a hash for new applications. Password Contexts ================= -Mature applications frequently have to deal with tables of existing password -hashes. Over time, they have to migrate to newer and stronger schemes; as well as raise -the requirements for existing algorithms as more processing power becomes available. -In this case, directly importing and handling the various schemes -generally becomes complicated and tedious. - -The :mod:`passlib.context` module provides the :class:`!CryptContext` class and other -utilties to help with these use-cases. This class handles -managing multiple password hash schemes, deprecation & migration of old hashes, and -many other policy requirements. - -A quick example of how a password context can be used:: - - >>> #importing the 'linux_context', which understands - >>> #all hashes found on standard linux systems: - >>> from passlib.hosts import linux_context as lc - - >>> #try encrypting a password - >>> lc.encrypt("password") - '$6$rounds=30000$suoPoYtkbccdZa3v$DW2KUcV98H4IrvlBB0YZf4DM8zqz5vduygB3OROhPzwHE5PDNVkpSUjJfjswn/dXqidha5t5CSCCIhtm6mIDR1' - - >>> #try encrypting a password using a specified scheme - >>> lc.encrypt("password", scheme="des_crypt") - 'q1Oyx5r9mdGZ2' - - >>> #try verifying a password (scheme is autodetected) - >>> lc.verify('password', 'q1Oyx5r9mdGZ2') - True - -Predefined Password Contexts -============================ -In addition to the :mod:`!passlib.context` module, -PassLib provides a number of pre-configured :class:`!CryptContext` instances +Mature applications frequently have to deal with tables of existing password hashes. +Over time, they have to support a number of tasks: + +* add support for new algorithms, and deprecate old ones, +* raise the time-cost settings for existing algorithms, as computing power increases, +* and do rolling upgrades of existing hashes to comply with these changes. +* hardcode these policies in the source, or spend time implementing + a configuration language for them. + +In these situations, loading and handling multiple hash algorithms becomes +complicated and tedious. The :mod:`passlib.context` module provides a single class, +:class:`!CryptContext`, which attempts to solve all of these problems, +or at least relieve applications developers of (most of) the burden. +This class handles managing multiple password hash schemes, +deprecation & migration of old hashes, and supports a simple configuration +language that can be serialized to an INI file. + +.. seealso:: + + * :ref:`CryptContext Tutorial <context-tutorial>` -- complete walkthrough of the CryptContext class. + * :ref:`CryptContext API Reference <context-reference>` -- full method and attribute documentation. + +Application Helpers +=================== +Passlib also provides a number of pre-configured :class:`!CryptContext` instances in order to get users started quickly: -* The :mod:`passlib.apache` module contains classes - for managing htpasswd and htdigest files. + * :mod:`passlib.apps` -- contains pre-configured + instances for managing hashes used by Postgres, Mysql, and LDAP, and others. + + * :mod:`passlib.hosts` -- contains pre-configured + instances for managing hashes as found in the /etc/shadow files + on Linux and BSD systems. + +Passlib also contains a couple of additional modules which provide +support for certain application-specific tasks: -* The :mod:`passlib.apps` module contains pre-configured - instances for managing hashes used by Postgres, Mysql, and LDAP, and others. + * :mod:`passlib.apache` -- classes for managing htpasswd and htdigest files. -* The :mod:`passlib.hosts` module contains pre-configured - instances for managing hashes as found in the /etc/shadow files - on Linux and BSD systems. + * :mod:`passlib.ext.django` -- Django plugin which monkeypatches support for (almost) any hash in Passlib. Utility Functions ================= -The :mod:`passlib.registry` and :mod:`passlib.utils` modules contain a large number -of support functions, most of which are only needed when -are implementing custom password hash schemes. Most users of passlib -will not need to use these. +Additionally, Passlib contains a number of modules which are used internally +to implement the all of the other features. These may change between major +releases, and won't be needed by most users of Passlib. They are documented +mainly to aid in examining the source. + + * :mod:`passlib.exc` -- all the custom errors & warnings used by Passlib. + * :mod:`passlib.registry` -- functions for registering password hash algorithms. + * :mod:`passlib.utils` -- support functions for implementing password hashes. |