diff options
| author | Eli Collins <elic@assurancetechnologies.com> | 2016-11-28 12:08:37 -0500 |
|---|---|---|
| committer | Eli Collins <elic@assurancetechnologies.com> | 2016-11-28 12:08:37 -0500 |
| commit | 692a18ce4cddeaeaaec1cfb8bd8bbec263027a8f (patch) | |
| tree | 44f298775aa78c4c1e06a538efb39db373f2d3d6 /docs | |
| parent | 131bb9c477ce273222f8946130fba638407296b5 (diff) | |
| parent | 210537f1210e13f17efa734ea080f1d70d605603 (diff) | |
| download | passlib-692a18ce4cddeaeaaec1cfb8bd8bbec263027a8f.tar.gz | |
Merge with stable
Diffstat (limited to 'docs')
44 files changed, 191 insertions, 135 deletions
diff --git a/docs/conf.py b/docs/conf.py index b45d17a..7adac8b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -109,6 +109,8 @@ from passlib import __version__ as release version = csp.get_version(release) if ".dev" in release: tags.add("devcopy") +if 'for-pypi' in options: + tags.add("pypi") # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/history/1.5.rst b/docs/history/1.5.rst index 575e81b..9d4135c 100644 --- a/docs/history/1.5.rst +++ b/docs/history/1.5.rst @@ -1,6 +1,6 @@ -========== -1.5 Series -========== +=========== +Passlib 1.5 +=========== .. _bcrypt-padding-issue: diff --git a/docs/history/1.6.rst b/docs/history/1.6.rst index 6b88c4b..1406b5f 100644 --- a/docs/history/1.6.rst +++ b/docs/history/1.6.rst @@ -1,6 +1,6 @@ -========== -1.6 Series -========== +=========== +Passlib 1.6 +=========== **1.6.5** (2015-08-04) ====================== diff --git a/docs/history/1.7.rst b/docs/history/1.7.rst index ba9b926..9f8f735 100644 --- a/docs/history/1.7.rst +++ b/docs/history/1.7.rst @@ -1,13 +1,17 @@ -.. _whats-new: +=========== +Passlib 1.7 +=========== + +**1.7.1** (NOT YET RELEASED) +============================ -========== -1.7 Series -========== +.. py:currentmodule:: passlib.ifc -.. seealso:: +* bugfix: :meth:`PasswordHash.hash` will now warn if passed any settings + keywords. This usage was deprecated in 1.7.0, but warning wasn't properly enabled. + See :ref:`hash-configuring` for the preferred way to pass settings. - The `Roadmap <https://bitbucket.org/ecollins/passlib/wiki/Roadmap>`_ - for a list of future changes that may impact applications. +.. _whats-new: .. rst-class:: emphasize-children toc-always-open diff --git a/docs/history/ancient.rst b/docs/history/ancient.rst index 797f584..f8a34ed 100644 --- a/docs/history/ancient.rst +++ b/docs/history/ancient.rst @@ -1,6 +1,6 @@ -============= -1.4 & Earlier -============= +===================== +Passlib 1.4 & Earlier +===================== **1.4** (2011-05-04) ==================== diff --git a/docs/history/index.rst b/docs/history/index.rst index c4a6689..219b713 100644 --- a/docs/history/index.rst +++ b/docs/history/index.rst @@ -4,19 +4,36 @@ Release History =============== -.. centered:: This is the documentation for the :ref:`1.7.0 Release <whats-new>` of Passlib. - -.. rst-class:: float-right +.. rst-class:: float-center without-title .. seealso:: - The `Roadmap <https://bitbucket.org/ecollins/passlib/wiki/Roadmap>`_ - for a list of future changes that may impact applications. + **For the latest release:** see :ref:`What's New <whats-new>` in Passlib 1.7 + +.. toctree:: + :maxdepth: 2 + + 1.7 Series <1.7> + +.. toctree:: + :maxdepth: 2 + + 1.6 Series <1.6> .. toctree:: :maxdepth: 2 - 1.7 - 1.6 - 1.5 - ancient + 1.5 Series <1.5> + +.. toctree:: + :maxdepth: 2 + + 1.4 & Earlier <ancient> + +.. rst-class:: float-center without-title + +.. seealso:: + + See the `Project Roadmap <https://bitbucket.org/ecollins/passlib/wiki/Roadmap>`_ + for a list of future changes that may impact applications. + diff --git a/docs/index.rst b/docs/index.rst index d21f9ee..8409ef9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,8 @@ :align: center :class: show-for-small -.. rst-class:: float-right without-title + +.. rst-class:: float-right .. seealso:: :ref:`What's new in Passlib 1.7 <whats-new>` @@ -18,6 +19,14 @@ Passlib |release| documentation For documentation of the latest stable version, see `<https://passlib.readthedocs.io>`_. +.. only:: pypi + + .. warning:: + + The official Passlib documentation have moved to `<https://passlib.readthedocs.io>`_. + Documentation at this location is still being maintained, + but will be updated much less frequently. + Welcome ======= Passlib is a password hashing library for Python 2 & 3, which provides diff --git a/docs/install.rst b/docs/install.rst index 6ee3d7f..2212383 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -104,21 +104,30 @@ Testing Passlib contains a comprehensive set of unittests (about 38% of the total code), which provide nearly complete coverage, and verification of the hash algorithms using multiple external sources (if detected at runtime). + All unit tests are contained within the :mod:`passlib.tests` subpackage, and are designed to be run using the `Nose <http://somethingaboutorange.com/mrl/projects/nose>`_ unit testing library (as well as the ``unittest2`` library under Python 2.6). -Once Passlib and Nose have been installed, the main suite of tests may be run from the source directory:: +Once Passlib and Nose have been installed, the main suite of tests may be run using:: + + nosetests --tests passlib.tests + +By default, this runs the main battery of tests, but omits some additional ones +(such as internal cross-checks, and mock-testing of features not provided natively by the host OS). +To run these tests as well, set the following environmental variable:: - nosetests --tests passlib/tests + PASSLIB_TEST_MODE="full" nosetests --tests passlib.tests -To run the full test suite, which includes internal cross-checks and mock-testing -of features not provided natively by the host OS:: +To run a quick check to confirm just basic functionality, with a pared-down set of tests:: - PASSLIB_TEST_MODE="full" nosetests --tests passlib/tests + PASSLIB_TEST_MODE="quick" nosetests --tests passlib.tests Tests may also be run via ``setup.py test`` or the included ``tox.ini`` file. +The ``tox.ini`` file is used to test passlib before each release, +and contains a number different environment setups. +These tests require `tox <https://pypi.python.org/pypi/tox>`_ 2.5 or later. .. rst-class:: html-toggle @@ -129,7 +138,7 @@ online at `<https://passlib.readthedocs.io>`_. If you wish to generate your own copy of the documentation, you will need to: -1. Install `Sphinx <http://sphinx.pocoo.org/>`_ (1.3 or newer) +1. Install `Sphinx <http://sphinx.pocoo.org/>`_ (1.4 or newer) 2. Install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_ (1.8 or newer). 3. Download the Passlib source 4. From the Passlib source directory, run :samp:`python setup.py build_sphinx`. diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst index e89b804..7e5559f 100644 --- a/docs/lib/passlib.apps.rst +++ b/docs/lib/passlib.apps.rst @@ -3,7 +3,7 @@ ================================================================== .. module:: passlib.apps - :synopsis: encrypting & verifying passwords used in sql servers and other applications + :synopsis: hashing & verifying passwords used in sql servers and other applications .. _predefined-context-example: @@ -23,7 +23,7 @@ Each of the objects in this module can be imported directly:: >>> # a helper to let new applications *quickly* add password hashing. >>> from passlib.apps import custom_app_context -Encrypting a password is simple (and salt generation is handled automatically):: +Hashing a password is simple (and salt generation is handled automatically):: >>> hash = custom_app_context.hash("toomanysecrets") >>> hash @@ -185,11 +185,11 @@ PostgreSQL This object should recognize password hashes stores in PostgreSQL's ``pg_shadow`` table; which are all assumed to follow the :class:`~passlib.hash.postgres_md5` format. - Note that the username must be provided whenever encrypting or verifying a postgres hash:: + Note that the username must be provided whenever hashing or verifying a postgres hash:: >>> from passlib.apps import postgres_context - >>> # encrypting a password... + >>> # hashing a password... >>> postgres_context.hash("somepass", user="dbadmin") 'md578ed0f0ab2be0386645c1b74282917e7' diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst index 2c95a74..b2f7248 100644 --- a/docs/lib/passlib.context.rst +++ b/docs/lib/passlib.context.rst @@ -23,7 +23,7 @@ The CryptContext Class ====================== .. class:: CryptContext(schemes=None, \*\*kwds) - Helper for encrypting passwords using different algorithms. + Helper for hashing passwords using different algorithms. At its base, this is a proxy object that makes it easy to use multiple :class:`~passlib.ifc.PasswordHash` objects at the same time. @@ -104,7 +104,7 @@ Options which directly affect the behavior of the CryptContext instance: Specifies the name of the default scheme. This option controls which of the configured - schemes will be used as the default when encrypting + schemes will be used as the default when creating new hashes. This parameter is optional; if omitted, the first non-deprecated algorithm in ``schemes`` will be used. You can use the :meth:`~CryptContext.default_scheme` method @@ -400,7 +400,7 @@ For example, a CryptContext could be set up as follows:: ... sha256_crypt__default_rounds=77000, ... staff__sha256_crypt__default_rounds=88000) - >>> # In this case, calling encrypt with ``category=None`` would result + >>> # In this case, calling hash() with ``category=None`` would result >>> # in a hash that used 77000 sha256-crypt rounds: >>> myctx.hash("password", category=None) '$5$rounds=77000$sj3XI0AbKlEydAKt$BhFvyh4.IoxaUeNlW6rvQ.O0w8BtgLQMYorkCOMzf84' @@ -442,7 +442,7 @@ style methods provided by all the :class:`~passlib.ifc.PasswordHash` objects: Hash Migration -------------- -Applications which want to detect and re-encrypt deprecated +Applications which want to detect and regenerate deprecated hashes will want to use one of the following methods: .. automethod:: CryptContext.verify_and_update diff --git a/docs/lib/passlib.hash.argon2.rst b/docs/lib/passlib.hash.argon2.rst index 0eb1ad6..fcc9508 100644 --- a/docs/lib/passlib.hash.argon2.rst +++ b/docs/lib/passlib.hash.argon2.rst @@ -17,7 +17,7 @@ for new applications. This class can be used directly as follows:: >>> from passlib.hash import argon2 - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> h = argon2.hash("password") >>> h '$argon2i$v=19$m=512,t=2,p=2$aI2R0hpDyLm3ltLa+1/rvQ$LqPKjd6n8yniKtAithoR7A' diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst index 946c5ff..4683690 100644 --- a/docs/lib/passlib.hash.bcrypt.rst +++ b/docs/lib/passlib.hash.bcrypt.rst @@ -13,7 +13,7 @@ for new applications. This class can be used directly as follows:: >>> from passlib.hash import bcrypt - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> h = bcrypt.hash("password") >>> h '$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy' diff --git a/docs/lib/passlib.hash.bcrypt_sha256.rst b/docs/lib/passlib.hash.bcrypt_sha256.rst index a7470c0..c9d2870 100644 --- a/docs/lib/passlib.hash.bcrypt_sha256.rst +++ b/docs/lib/passlib.hash.bcrypt_sha256.rst @@ -15,7 +15,7 @@ This class can be used directly as follows:: >>> from passlib.hash import bcrypt_sha256 - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> h = bcrypt_sha256.hash("password") >>> h '$bcrypt-sha256$2a,12$LrmaIX5x4TRtAwEfwJZa1.$2ehnw6LvuIUTM0iz4iz9hTxv21B6KFO' diff --git a/docs/lib/passlib.hash.bsdi_crypt.rst b/docs/lib/passlib.hash.bsdi_crypt.rst index cb82797..dde7dee 100644 --- a/docs/lib/passlib.hash.bsdi_crypt.rst +++ b/docs/lib/passlib.hash.bsdi_crypt.rst @@ -14,7 +14,7 @@ It class can be used directly as follows:: >>> from passlib.hash import bsdi_crypt - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> hash = bsdi_crypt.hash("password") >>> hash '_7C/.Bf/4gZk10RYRs4Y' diff --git a/docs/lib/passlib.hash.cisco_pix.rst b/docs/lib/passlib.hash.cisco_pix.rst index d879748..5b00b83 100644 --- a/docs/lib/passlib.hash.cisco_pix.rst +++ b/docs/lib/passlib.hash.cisco_pix.rst @@ -30,7 +30,7 @@ newer systems. They can be used directly as follows:: >>> from passlib.hash import cisco_pix as pix - >>> # encrypt password using specified username + >>> # hash password using specified username >>> hash = pix.hash("password", user="user") >>> hash 'A5XOy94YKDPXCo7U' @@ -45,7 +45,7 @@ newer systems. They can be used directly as follows:: >>> pm.verify("letmein", hash, user="user") False - >>> # encrypt password without associate user account + >>> # hash password without associated user account >>> hash2 = pix.hash("password") >>> hash2 'NuLKvvWGg.x9HEKO' diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst index 7aa6528..c282d5e 100644 --- a/docs/lib/passlib.hash.des_crypt.rst +++ b/docs/lib/passlib.hash.des_crypt.rst @@ -13,7 +13,7 @@ It can used directly as follows:: >>> from passlib.hash import des_crypt - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> hash = des_crypt.hash("password") 'JQMuyS6H.AGMo' diff --git a/docs/lib/passlib.hash.django_std.rst b/docs/lib/passlib.hash.django_std.rst index 02116c6..5135f4f 100644 --- a/docs/lib/passlib.hash.django_std.rst +++ b/docs/lib/passlib.hash.django_std.rst @@ -96,7 +96,7 @@ These classes can be used directly as follows:: >>> from passlib.hash import django_pbkdf2_sha256 as handler - >>> # encrypt password + >>> # hash password >>> h = handler.hash("password") >>> h 'pbkdf2_sha256$10000$s1w0UXDd00XB$+4ORmyvVWAQvoAEWlDgN34vlaJx1ZTZpa1pCSRey2Yk=' @@ -176,7 +176,7 @@ These classes can be used directly as follows:: >>> from passlib.hash import django_salted_sha1 as handler - >>> # encrypt password + >>> # hash password >>> h = handler.hash("password") >>> h 'sha1$c6218$161d1ac8ab38979c5a31cbaba4a67378e7e60845' diff --git a/docs/lib/passlib.hash.fshp.rst b/docs/lib/passlib.hash.fshp.rst index 6ffefd0..ef959d3 100644 --- a/docs/lib/passlib.hash.fshp.rst +++ b/docs/lib/passlib.hash.fshp.rst @@ -23,7 +23,7 @@ It can be used directly as follows:: >>> from passlib.hash import fshp - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> hash = fshp.hash("password") >>> hash '{FSHP1|16|16384}PtoqcGUetmVEy/uR8715TNqKa8+teMF9qZO1lA9lJNUm1EQBLPZ+qPRLeEPHqy6C' diff --git a/docs/lib/passlib.hash.hex_digests.rst b/docs/lib/passlib.hash.hex_digests.rst index 8e66b87..ce30faf 100644 --- a/docs/lib/passlib.hash.hex_digests.rst +++ b/docs/lib/passlib.hash.hex_digests.rst @@ -22,7 +22,7 @@ and can be used directly as follows:: >>> from passlib.hash import hex_sha1 as hex_sha1 - >>> # encrypt password + >>> # hash password >>> h = hex_sha1.hash("password") >>> h '5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8' diff --git a/docs/lib/passlib.hash.ldap_crypt.rst b/docs/lib/passlib.hash.ldap_crypt.rst index ede7c5f..7cd2df8 100644 --- a/docs/lib/passlib.hash.ldap_crypt.rst +++ b/docs/lib/passlib.hash.ldap_crypt.rst @@ -20,7 +20,7 @@ elsewhere in Passlib, and can be used directly as follows:: >>> from passlib.hash import ldap_md5_crypt - >>> # encrypt password + >>> # hash password >>> hash = ldap_md5_crypt.hash("password") >>> hash '{CRYPT}$1$gwvn5BO0$3dyk8j.UTcsNUPrLMsU6/0' diff --git a/docs/lib/passlib.hash.ldap_std.rst b/docs/lib/passlib.hash.ldap_std.rst index 12c2abd..d3788c1 100644 --- a/docs/lib/passlib.hash.ldap_std.rst +++ b/docs/lib/passlib.hash.ldap_std.rst @@ -14,7 +14,7 @@ and are can be used directly as follows:: >>> from passlib.hash import ldap_salted_md5 as lsm - >>> # encrypt password + >>> # hash password >>> hash = lsm.hash("password") >>> hash '{SMD5}OqsUXNHIhHbznxrqHoIM+ZT8DmE=' diff --git a/docs/lib/passlib.hash.lmhash.rst b/docs/lib/passlib.hash.lmhash.rst index 26a4164..65acdf8 100644 --- a/docs/lib/passlib.hash.lmhash.rst +++ b/docs/lib/passlib.hash.lmhash.rst @@ -20,7 +20,7 @@ This class can be used directly as follows:: >>> from passlib.hash import lmhash - >>> # encrypt password + >>> # hash password >>> h = lmhash.hash("password") >>> h 'e52cac67419a9a224a3b108f3fa6cb6d' diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst index 844b6b6..f3c9279 100644 --- a/docs/lib/passlib.hash.md5_crypt.rst +++ b/docs/lib/passlib.hash.md5_crypt.rst @@ -25,7 +25,7 @@ The :class:`!md5_crypt` class can be can be used directly as follows:: >>> from passlib.hash import md5_crypt - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> h = md5_crypt.hash("password") >>> h '$1$3azHgidD$SrJPt7B.9rekpmwJwtON31' @@ -36,7 +36,7 @@ The :class:`!md5_crypt` class can be can be used directly as follows:: >>> md5_crypt.verify("secret", h) False - >>> # encrypt password using cisco-compatible 4-char salt + >>> # hash password using cisco-compatible 4-char salt >>> md5_crypt.using(salt_size=4).hash("password") '$1$wu98$9UuD3hvrwehnqyF1D548N0' diff --git a/docs/lib/passlib.hash.msdcc.rst b/docs/lib/passlib.hash.msdcc.rst index acfd87f..5b39caa 100644 --- a/docs/lib/passlib.hash.msdcc.rst +++ b/docs/lib/passlib.hash.msdcc.rst @@ -24,7 +24,7 @@ This class can be used directly as follows:: >>> from passlib.hash import msdcc - >>> # encrypt password using specified username + >>> # hash password using specified username >>> hash = msdcc.hash("password", user="Administrator") >>> hash '25fd08fa89795ed54207e6e8442a6ca0' diff --git a/docs/lib/passlib.hash.msdcc2.rst b/docs/lib/passlib.hash.msdcc2.rst index 203d957..4510c10 100644 --- a/docs/lib/passlib.hash.msdcc2.rst +++ b/docs/lib/passlib.hash.msdcc2.rst @@ -21,7 +21,7 @@ This class can be used directly as follows:: >>> from passlib.hash import msdcc2 - >>> # encrypt password using specified username + >>> # hash password using specified username >>> hash = msdcc2.hash("password", user="Administrator") >>> hash '4c253e4b65c007a8cd683ea57bc43c76' diff --git a/docs/lib/passlib.hash.mssql2000.rst b/docs/lib/passlib.hash.mssql2000.rst index 481008c..6da9c8f 100644 --- a/docs/lib/passlib.hash.mssql2000.rst +++ b/docs/lib/passlib.hash.mssql2000.rst @@ -16,7 +16,7 @@ This class can be used directly as follows:: >>> from passlib.hash import mssql2000 as m20 - >>> # encrypt password + >>> # hash password >>> h = m20.hash("password") >>> h '0x0100200420C4988140FD3920894C3EDC188E94F428D57DAD5905F6CC1CBAF950CAD4C63F272B2C91E4DEEB5E6444' diff --git a/docs/lib/passlib.hash.mssql2005.rst b/docs/lib/passlib.hash.mssql2005.rst index bb6b0ec..5d7a7a7 100644 --- a/docs/lib/passlib.hash.mssql2005.rst +++ b/docs/lib/passlib.hash.mssql2005.rst @@ -15,7 +15,7 @@ This class can be used directly as follows:: >>> from passlib.hash import mssql2005 as m25 - >>> # encrypt password + >>> # hash password >>> h = m25.hash("password") >>> h '0x01006ACDF9FF5D2E211B392EEF1175EFFE13B3A368CE2F94038B' diff --git a/docs/lib/passlib.hash.mysql323.rst b/docs/lib/passlib.hash.mysql323.rst index eab3e3e..a8e8bfd 100644 --- a/docs/lib/passlib.hash.mysql323.rst +++ b/docs/lib/passlib.hash.mysql323.rst @@ -19,7 +19,7 @@ That aside, this class can be used as follows:: >>> from passlib.hash import mysql323 - >>> # encrypt password + >>> # hash password >>> mysql323.hash("password") '5d2e19393cc5ef67' diff --git a/docs/lib/passlib.hash.nthash.rst b/docs/lib/passlib.hash.nthash.rst index 92c934e..237372a 100644 --- a/docs/lib/passlib.hash.nthash.rst +++ b/docs/lib/passlib.hash.nthash.rst @@ -17,7 +17,7 @@ This class can be used directly as follows:: >>> from passlib.hash import nthash - >>> # encrypt password + >>> # hash password >>> h = nthash.hash("password") >>> h '8846f7eaee8fb117ad06bdd830b7586c' diff --git a/docs/lib/passlib.hash.oracle10.rst b/docs/lib/passlib.hash.oracle10.rst index 3d697c2..de874d4 100644 --- a/docs/lib/passlib.hash.oracle10.rst +++ b/docs/lib/passlib.hash.oracle10.rst @@ -13,7 +13,7 @@ a username for all encrypt/verify operations):: >>> from passlib.hash import oracle10 as oracle10 - >>> # encrypt password using specified username + >>> # hash password using specified username >>> hash = oracle10.hash("password", user="username") >>> hash '872805F3F4C83365' diff --git a/docs/lib/passlib.hash.oracle11.rst b/docs/lib/passlib.hash.oracle11.rst index 0953ead..bf2ad1d 100644 --- a/docs/lib/passlib.hash.oracle11.rst +++ b/docs/lib/passlib.hash.oracle11.rst @@ -10,7 +10,7 @@ This class can be can be used directly as follows:: >>> from passlib.hash import oracle11 as oracle11 - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> hash = oracle11.hash("password") >>> hash 'S:4143053633E59B4992A8EA17D2FF542C9EDEB335C886EED9C80450C1B4E6' diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst index 10e68ba..a918167 100644 --- a/docs/lib/passlib.hash.pbkdf2_digest.rst +++ b/docs/lib/passlib.hash.pbkdf2_digest.rst @@ -26,7 +26,7 @@ All of these classes can be used directly as follows:: >>> from passlib.hash import pbkdf2_sha256 - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> hash = pbkdf2_sha256.hash("password") >>> hash '$pbkdf2-sha256$6400$0ZrzXitFSGltTQnBWOsdAw$Y11AchqV4b0sUisdZd0Xr97KWoymNE0LNNrnEgY4H9M' diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst index 4627eb7..7a88bb8 100644 --- a/docs/lib/passlib.hash.postgres_md5.rst +++ b/docs/lib/passlib.hash.postgres_md5.rst @@ -17,7 +17,7 @@ That aside, this class can be used directly as follows:: >>> from passlib.hash import postgres_md5 - >>> # encrypt password using specified username + >>> # hash password using specified username >>> hash = postgres_md5.hash("password", user="username") >>> hash 'md55a231fcdb710d73268c4f44283487ba2' diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst index f5a728c..3211066 100644 --- a/docs/lib/passlib.hash.rst +++ b/docs/lib/passlib.hash.rst @@ -20,11 +20,9 @@ including its format, underlying algorithm, and known security issues. **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 </narr/quickstart>` instead of picking - one from this list. + support legacy data and systems. + If you want to choose a secure algorithm for a new application, + see the :doc:`Quickstart Guide </narr/quickstart>`. .. rst-class:: float-center @@ -49,7 +47,7 @@ by other applications and password hash schemes. Active Unix Hashes ------------------ -All these schemes are actively in use by various Unix flavors to store user passwords. +All the following schemes are actively in use by various Unix flavors to store user passwords They all follow the modular crypt format. .. toctree:: @@ -73,8 +71,8 @@ found in many Linux & BSD password files: 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: +using the modular crypt format, but are no longer considered secure, +and have been deprecated in favor of the `Active Unix Hashes`_ (above). * :class:`passlib.hash.bsd_nthash` - FreeBSD's MCF-compatible encoding of :doc:`nthash <passlib.hash.nthash>` digests diff --git a/docs/lib/passlib.hash.scram.rst b/docs/lib/passlib.hash.scram.rst index a1f63b6..48e2ed0 100644 --- a/docs/lib/passlib.hash.scram.rst +++ b/docs/lib/passlib.hash.scram.rst @@ -36,7 +36,7 @@ This class can be used like any other Passlib hash, as follows:: >>> from passlib.hash import scram - >>> # generate new salt, encrypt password against default list of algorithms + >>> # generate new salt, hash password against default list of algorithms >>> hash = scram.hash("password") >>> hash '$scram$6400$.Z/znnNOKWUsBaCU$sha-1=cRseQyJpnuPGn3e6d6u6JdJWk.0,sha-256=5G diff --git a/docs/lib/passlib.hash.scrypt.rst b/docs/lib/passlib.hash.scrypt.rst index 6c2c061..19751ca 100644 --- a/docs/lib/passlib.hash.scrypt.rst +++ b/docs/lib/passlib.hash.scrypt.rst @@ -23,7 +23,7 @@ This class can be used directly as follows:: >>> from passlib.hash import scrypt - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> h = scrypt.hash("password") >>> h '$scrypt$ln=16,r=8,p=1$aM15713r3Xsvxbi31lqr1Q$nFNh2CVHVjNldFVKDHDlm4CbdRSCdEBsjjJxD+iCs5E' diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst index b1e23e8..907ce7a 100644 --- a/docs/lib/passlib.hash.sha256_crypt.rst +++ b/docs/lib/passlib.hash.sha256_crypt.rst @@ -17,7 +17,7 @@ This class can be used directly as follows:: >>> from passlib.hash import sha256_crypt - >>> # generate new salt, encrypt password + >>> # generate new salt, hash password >>> hash = sha256_crypt.hash("password") >>> hash '$5$rounds=80000$wnsT7Yr92oJoP28r$cKhJImk5mfuSKV9b3mumNzlbstFUplKtQXXMo4G6Ep5' diff --git a/docs/lib/passlib.hash.unix_disabled.rst b/docs/lib/passlib.hash.unix_disabled.rst index 1159787..8bdf9c3 100644 --- a/docs/lib/passlib.hash.unix_disabled.rst +++ b/docs/lib/passlib.hash.unix_disabled.rst @@ -13,7 +13,7 @@ It can be used directly as follows:: >>> from passlib.hash import unix_disabled - >>> # 'encrypting' a password always results in "!" or "*" + >>> # 'hashing' a password always results in "!" or "*" >>> unix_disabled.hash("password") '!' diff --git a/docs/lib/passlib.hosts.rst b/docs/lib/passlib.hosts.rst index d72fef0..811993d 100644 --- a/docs/lib/passlib.hosts.rst +++ b/docs/lib/passlib.hosts.rst @@ -3,10 +3,10 @@ ============================================ .. module:: passlib.hosts - :synopsis: encrypting & verifying operating system passwords + :synopsis: hashing & verifying operating system passwords This module provides some preconfigured :ref:`CryptContext <context-reference>` -instances for encrypting & verifying password hashes tied to user accounts of various operating systems. +instances for hashing & verifying password hashes tied to user accounts of various operating systems. While (most) of the objects are available cross-platform, their use is oriented primarily towards Linux and BSD variants. @@ -27,7 +27,7 @@ Each of the objects in this module can be imported directly:: >>> # which is configured to recognized most hashes found in Linux /etc/shadow files. >>> from passlib.apps import linux_context -Encrypting a password is simple (and salt generation is handled automatically):: +Hashing a password is simple (and salt generation is handled automatically):: >>> hash = linux_context.hash("toomanysecrets") >>> hash @@ -112,7 +112,7 @@ Current Host OS are available on a given system (via ``host_context.schemes()``). * it defaults to the strongest algorithm available, automatically configured to an appropriate strength - for encrypting new passwords. + for hashing new passwords. * whereas :func:`!crypt` typically defaults to using :mod:`~passlib.hash.des_crypt`; and provides little introspection. diff --git a/docs/lib/passlib.ifc.rst b/docs/lib/passlib.ifc.rst index 8118a4c..77ea440 100644 --- a/docs/lib/passlib.ifc.rst +++ b/docs/lib/passlib.ifc.rst @@ -270,7 +270,7 @@ using the provided configuration string. :type config: unicode or bytes :arg config: - configuration string to use when encrypting secret. + configuration string to use when hashing the secret. this can either be an existing hash that was previously returned by :meth:`PasswordHash.genhash`, or a configuration string that was previously created by :meth:`PasswordHash.genconfig`. diff --git a/docs/narr/context-tutorial.rst b/docs/narr/context-tutorial.rst index 718f031..8e4cb7a 100644 --- a/docs/narr/context-tutorial.rst +++ b/docs/narr/context-tutorial.rst @@ -87,7 +87,7 @@ interface, and hashing and verifying passwords is equally as straightforward:: True If not told otherwise, the context object will use the first algorithm listed -in ``schemes`` when encrypting new hashes. This default can be changed by +in ``schemes`` when creating new hashes. This default can be changed by using the ``default`` keyword:: >>> myctx = CryptContext(schemes=["sha256_crypt", "md5_crypt", "des_crypt"], @@ -112,7 +112,7 @@ which probably provide a better argument for *why* you'd want to use it. Using Default Settings ====================== -While encrypting and verifying hashes is useful enough, it's not much +While creating and verifying hashes is useful enough, it's not much more than could be done by importing the objects into a list. The next feature of the :class:`!CryptContext` class is that it can store various customized settings for the different algorithms, @@ -409,7 +409,7 @@ All of the documented :ref:`context-options` are allowed. pbkdf2_sha256__min_rounds = 10000 pbkdf2_sha256__max_rounds = 50000 - ; set the default rounds to use when encrypting new passwords. + ; set the default rounds to use when hashing new passwords. pbkdf2_sha1__default_rounds = 15000 ; applications can choose to treat certain user accounts differently, diff --git a/docs/narr/hash-tutorial.rst b/docs/narr/hash-tutorial.rst index 2407e63..b19de99 100644 --- a/docs/narr/hash-tutorial.rst +++ b/docs/narr/hash-tutorial.rst @@ -44,21 +44,19 @@ which fall into three general categories: Hashing & Verifying =================== -.. rst-class:: float-right without-title +While all the hashers in :mod:`passlib.hash` offer a range of methods and attributes, +the main activities applications will need to perform is hashing and verifying passwords. +This can be done with the :meth:`PasswordHash.hash` and :meth:`PasswordHash.verify` methods. + +.. rst-class:: float-center without-title .. caution:: **Changed in 1.7:** - This section has changed under Passlib 1.7. Prior releases used - :meth:`PasswordHash.encrypt`, which has now been renamed - to :meth:`PasswordHash.hash`. A legacy alias is present in 1.7, - but will be removed in Passlib 2.0. - -While all the hashers in :mod:`passlib.hash` offer a range of methods and attributes, -the main activities applications will need to perform is hashing and verifying passwords. - -This can be done with the :meth:`PasswordHash.hash` and :meth:`PasswordHash.verify` methods. + Prior releases used :meth:`PasswordHash.encrypt` for hashing, + which has now been renamed to :meth:`PasswordHash.hash`. + A compatibility alias is present in 1.7, but will be removed in Passlib 2.0. Hashing ------- @@ -68,15 +66,15 @@ First, import the desired hash. The following example uses the :class:`~passlib >>> # import the desired hasher >>> from passlib.hash import pbkdf2_sha256 -Use :meth:`PasswordHash.hash` to hash a password. It takes care of unicode encoding, -picking default rounds values:: +Use :meth:`PasswordHash.hash` to hash a password. This call takes care of unicode encoding, +picking default rounds values, and generating a random salt:: >>> hash = pbkdf2_sha256.hash("password") >>> hash '$pbkdf2-sha256$29000$9t7be09prfXee2/NOUeotQ$Y.RDnnq8vsezSZSKy1QNy6xhKPdoBIwc.0XDdRm9sJ8' -Note that each call generates a new salt, and thus the contents of the resulting -hash will differ, despite using the same password:: +Note that since each call generates a new salt, the contents of the resulting +hash will differ between calls (despite using the same password as input):: >>> hash2 = pbkdf2_sha256.hash("password") >>> hash2 @@ -98,45 +96,51 @@ against an existing hash:: Unicode & non-ASCII Characters ------------------------------ -Sidenote regarding unicode passwords & non-ASCII characters: +*Sidenote regarding unicode passwords & non-ASCII characters:* For the majority of hash algorithms and use-cases, passwords should be provided as either :class:`!unicode` (or ``utf-8``-encoded :class:`!bytes`). -One major exception legacy hashes that were generated +One exception is legacy hashes that were generated using a different character encoding. In this case, passwords should be encoded using the correct encoding before they are passed to :meth:`!verify`; otherwise users may not be able to log in successfully. +For proper internationalization, applications should also take care to ensure +unicode inputs are normalized to a single representation before hashing. +The :func:`passlib.utils.saslprep` function can be used for this purpose. + .. _hash-configuring: Customizing the Configuration ============================= -.. rst-class:: float-right without-title -.. caution:: +The using() Method +------------------ +Each hasher contains a number of :ref:`informational attributes <informational-attributes>`. +many of which can be customized to change the properties of the hashes +generated by :meth:`PasswordHash.hash`. When you want to change the defaults, +you don't have to modify the hasher class directly, or pass in the options to each call to :meth:`!PasswordHash.hash`. - **Changed in 1.7:** +Instead, all the hashes offer a :meth:`PasswordHash.using` method. +This is a powerful method which accepts most hash informational attributes, +as well as some other hash-specific configuration keywords; and returns +a subclass of the original hasher (or a object with an identical interface). +The returned object inherits the defaults settings from it's parent, +but integrates any values you choose to override. - This section has changed under Passlib 1.7. Prior releases required you - to pass configuration options to each call of :meth:`PasswordHash.hash` - That pattern is deprecated, and will be removed in Passlib 2.0; - code should be switched to use :meth:`PasswordHash.using`... +.. rst-class:: float-center without-title -Each hasher contains a number of :ref:`informational attributes <informational-attributes>`, -many of which can be customized to change the properties of the hashes -generated by :meth:`PasswordHash.hash`. +.. caution:: -Instead of modifying the hasher class directly, or having to pass in -the options to each call to :meth:`!PasswordHash.hash`, -all the hashes offer a :meth:`PasswordHash.using` method. + **Changed in 1.7:** -This is a powerful method which accepts most hash informational attributes, -as well as some other hash-specific configuration keywords; and returns -a subclass of the original hasher (or an equivalent workalike). This object -inherits the defaults from it's parent, but integrates any values you -choose to override. + Prior releases required you to pass custom settings to each :meth:`PasswordHash.encrypt` call. + That usage pattern is deprecated, and will be removed in Passlib 2.0; + code should be switched to use :meth:`PasswordHash.using`, as shown below. +Usage Example +------------- As an example, if the hasher you select supports a variable number of iterations (such as :class:`~passlib.hash.pbkdf2_sha256`), you can specify a custom value using the ``rounds`` keyword. @@ -162,6 +166,8 @@ But if we call :meth:`PasswordHash.using`, we can override this value:: '$pbkdf2-sha256$123456$QwjBmJPSOsf4HyNE6L239g$8m1pnP69EYeOiKKb5sNSiYw9M8pJMyeW.CSm0KKO.GI' ^^^^^^ +Other Keywords +-------------- While hashes frequently have additional keywords supported by using, the basic set of settings you can customize can be found by inspecting the :attr:`PasswordHash.setting_kwds` attribute:: @@ -169,7 +175,14 @@ the :attr:`PasswordHash.setting_kwds` attribute:: >>> pbkdf2_sha256.settings_kwds ("salt", "salt_size", "rounds") -This method is additionally used internally by the :ref:`CryptContext <context-tutorial>` +For instance, the following generates pbkdf2 hashes with a 32-byte salt +instead of the default 16:: + + >>> pbkdf2_sha256.using(salt_size=8).hash("password") + '$pbkdf2-sha256$29000$tPZ.r5UyZgyhNEaI8Z5z7r1X6p1zTknJ.T/nHINwbq0$RlM49Qf5qRraHx.L7gq3hKIKSMLttrG1zWmWXyfXqc8' + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This method is also used internally by the :ref:`CryptContext <context-tutorial>` class it order to create a custom hasher configured based on the CryptContext policy it was provided. @@ -252,10 +265,14 @@ which determines whether a hash belongs to a given algorithm:: >>> pbkdf2_sha256.identify(other_hash) False -Note that most cases where an application will need to use this to -sort out multiple hash formats, it will be more useful to switch to -a :ref:`CryptContext <context-tutorial>` object, which handles this -(and many similar tasks) automatically. +.. rst-class:: float-center + +.. seealso:: + + In most cases where an application needs to + distinguish between multiple hash formats, it will be more useful to switch to + a :ref:`CryptContext <context-tutorial>` object, which automatically handles this + and many similar tasks. .. todo:: diff --git a/docs/narr/overview.rst b/docs/narr/overview.rst index 6aa73ec..03f1b16 100644 --- a/docs/narr/overview.rst +++ b/docs/narr/overview.rst @@ -16,10 +16,10 @@ as "hasher" classes which can be imported from the :mod:`passlib.hash` module. In turn, all of the hashers have a uniform interface, which is documented in the :ref:`hash-tutorial`. -*A word of warning:* the hashes in this library marked as "insecure" -are provided for historical purposes only. Still others are specialized in ways that are not generally useful. +*A word of warning:* Some the hashes in this library are marked as "insecure", +and are provided for historical purposes only. Still others 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:`quickstart`. +please read the :doc:`quickstart` first. .. rst-class:: float-center @@ -43,8 +43,8 @@ Over time, they have to support a number of tasks: 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. +:class:`!CryptContext`, which attempts to solve all of these problems +(or at least relieve developers of most of the burden). This class handles managing multiple password hash schemes, deprecation & migration of old hashes, and supports a simple configuration diff --git a/docs/narr/quickstart.rst b/docs/narr/quickstart.rst index 8e2570e..cfdd730 100644 --- a/docs/narr/quickstart.rst +++ b/docs/narr/quickstart.rst @@ -3,8 +3,8 @@ New Application Quickstart Guide ================================ Need to quickly get password hash support added into your new application, -and don't have time to wade through pages of documentation, -comparing and contrasting all the different schemes? Read on... +butdon't have time to wade through pages of documentation, +comparing and contrasting all the different schemes? Then read on... .. NOTE: commented this out for now, considering deprecating @@ -24,13 +24,13 @@ comparing and contrasting all the different schemes? Read on... >>> # import the context under an app-specific name (so it can easily be replaced later) >>> from passlib.apps import custom_app_context as pwd_context - >>> # encrypting a password... + >>> # hash a password... >>> hash = pwd_context.hash("somepass") >>> # verifying a password... >>> ok = pwd_context.verify("somepass", hash) - >>> # [optional] encrypting a password for an admin account... + >>> # [optional] hashing a password for an admin account... >>> # the custom_app_context is preconfigured so that >>> # if the category is set to "admin" instead of None, >>> # it uses a stronger setting of 80000 rounds: @@ -266,7 +266,7 @@ To start using your CryptContext, import the context you created wherever it's n >>> # import context from where you defined it... >>> from myapp.model.security import pwd_context - >>> # encrypting a password... + >>> # hashing a password... >>> hash = pwd_context.hash("somepass") >>> hash '$pbkdf2-sha256$29000$BSBkLEXIeS9FKMW4F.I85w$SJMzqVU7fw49NDOJZHt2o9vKIfDUVM4cKlAD4MxIgD0' |