This instance was upgraded to Heptapod 0.20.1 today

Commit d34d48b9 authored by Eli Collins's avatar Eli Collins

documentation updates

=====================
* CryptContext docs finished
* README / LICENSE updated
* license text changed to correct BSD wording
* embarassingly, the history.rst is kinda off about release versions.
  tried to make it give readers better outline.
* misc doc updates
* some handler names (eg: 'context', 'all') now forbidden by register_crypt_handler()
* bumped setup.cfg to b1
parent 91ff7a40b5a0
License for PassLib
===================
Copyright (c) 2008-2011 by Assurance Technologies, LLC.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Licenses for incorporated software
==================================
PassLib contains some code derived from the following sources:
jBcrypt
-------
Copyright (c) 2006 Damien Miller <djm@mindrot.org>
Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
MD5-Crypt
---------
"THE BEER-WARE LICENSE" (Revision 42):
<phk@login.dknet.dk> wrote this file. As long as you retain this notice you
can do whatever you want with this stuff. If we meet some day, and you think
this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
UnixCrypt.java
--------------
UnixCrypt.java 0.9 96/11/25
Copyright (c) 1996 Aki Yoshida. All rights reserved.
Permission to use, copy, modify and distribute this software
for non-commercial or commercial purposes and without fee is
hereby granted provided that this copyright notice appears in
all copies.
modified April 2001
by Iris Van den Broeke, Daniel Deville
modified Aug 2005
by Greg Wilkins (gregw)
.. -*- restructuredtext -*-
==========================
The PassLib Python Library
==========================
PassLib is a password hash library, which provides cross-platform
implementations of over 20 password hashing algorithms; as well as a framework for managing
and migrating existing password hashes. It's designed to be useful
for any task from quickly verifying a hash found in /etc/shadow,
to providing full-strength password hashing for multi-user application.
The latest documentation can be found online `XXX`.
Requirements
-----------
* Python 2.5 - 2.7
* PyBCrypt (optional; if bcrypt support is needed)
* M2Crypto (optional)
Installation
------------
* For detailed installation instructions, see "docs/install.rst"
To install from source using ``setup.py``::
python setup.py build
sudo python setup.py install
Copyright & License
-------------------
* (c) 2008-2011 - Assurance Technologies LLC
* released under BSD license
* For more license & copyright information, see "docs/copyright.rst"
For more detailed installation & testing instructions, see "docs/install.rst",
......@@ -9,7 +9,6 @@ Table Of Contents
overview
lib/passlib.context
lib/passlib.context-interface
lib/passlib.context-options
lib/passlib.apps
lib/passlib.apache
......
......@@ -2,48 +2,45 @@
Copyrights & Licenses
=====================
Copyright
=========
The PassLib library is (c) 2008-2011 `Assurance Technologies, LLC <http://www.assurancetechnologies.com>`_,
excepting any code noted below as taken from :ref:`third party sources <third-party-software>`.
Such portions are copyright their respective owners.
License
=======
This library is released under the BSD license; we hope you find it useful.
::
The PassLib Python Library
Copyright (c) 2008-2011 Assurance Technologies, LLC
Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.. _third-party-software:
Third Party Software
====================
PassLib contains some code taken from various third-party sources, which have their
own licenses (all of which, it should be noted, are BSD-compatible).
The following is a list of these sources, their owners, licenses, and the parts
of PassLib derived from them.
License for PassLib
===================
PassLib is available under the BSD license, and is (c) `Assurance Technologies <http://www.assurancetechnologies.com>`_::
Copyright (c) 2008-2011 by Assurance Technologies, LLC.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Licenses for incorporated software
==================================
PassLib contains some code derived from the following sources:
jBcrypt
-------
`jBCrypt <http://www.mindrot.org/projects/jBCrypt/>`_ is a pure-java
implementation of OpenBSD's BCrypt algorithm, written by Damien Miller,
and released under a BSD license.
and released under a BSD-like license.
:mod:`passlib.utils._slow_bcrypt` is a python translation of this code,
which is used as a fallback backend for :class:`passlib.hash.bcrypt`
......@@ -68,10 +65,9 @@ This is the license and copyright for jBCrypt::
MD5-Crypt
---------
The fallback pure-python implementation contained in :class:`passlib.hash.md5_crypt`
was derived from the
`FreeBSD md5-crypt <http://www.freebsd.org/cgi/cvsweb.cgi/~checkout~/src/lib/libcrypt/crypt.c?rev=1.2>`_,
implementation which was released under the following license::
The pure-python fallback used by :class:`passlib.hash.md5_crypt` was derived from the original
`FreeBSD md5-crypt implementation <http://www.freebsd.org/cgi/cvsweb.cgi/~checkout~/src/lib/libcrypt/crypt.c?rev=1.2>`_,
which is available under the following license::
"THE BEER-WARE LICENSE" (Revision 42):
<phk@login.dknet.dk> wrote this file. As long as you retain this notice you
......@@ -80,16 +76,11 @@ implementation which was released under the following license::
UnixCrypt.java
--------------
`UnixCrypt.java <http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt>`_
is a pure-java implementation of the historic unix-crypt password hash algorithm.
The DES utility functions in :mod:`passlib.utils.des` are derived
from `UnixCrypt.java <http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt>`_,
a pure-java implementation of the historic unix-crypt password hash algorithm.
Originally written by Aki Yoshida, and modified by others,
it was released under a BSD-like license.
The DES utility functions in :mod:`passlib.utils.des` are a descendant of
this code, after being translated into python. (These are used for des-crypt,
ext-des-crypt, and nthash support).
This is the license and copyright for UnixCrypt.java::
it is available under a BSD-like license::
UnixCrypt.java 0.9 96/11/25
Copyright (c) 1996 Aki Yoshida. All rights reserved.
......
......@@ -2,25 +2,36 @@
Release History
===============
2011-01-10 -- version 1.0
**1.3** (To Be Released)
* first public release
* bugfixes
* more documentation
* documentation completed
* 99% unittest coverage
* some refactoring and lots of bugfixes
* added support for a number of addtional password schemes:
bigcrypt, crypt16, sun md5 crypt, nthash, lmhash, oracle10 & 11,
phpass, sha1, generic hex digests, ldap digests.
**1.2** (2011-01-06)
* many bugfixes
* global registry added
* transitional release for applications using BPS library.
* first truly functional release since splitting from BPS library (see below).
2011-01-05 -- version 0.8
* various code cleanups preparing for public release
* bsdi-crypt, apr-md5-crypt, and other lesser known schemes added.
* documentation added
.. note::
2009-03-10 -- version 0.7
* postgres and mysql hash schemes added.
For all previous versions, PassLib did not exist independantly,
but as a subpackage of *BPS*, an private & unreleased toolkit library.
**1.0** (2009-12-11)
2008-10-02 -- version 0.6
* CryptContext & CryptHandler framework
* added support for: des-crypt, bcrypt (via pybcrypt), postgres, mysql
* added unit tests
* added Unix-Crypt support and pure-python fallback
2008-05-10 -- version 0.5
**0.5** (2008-05-10)
* initial production version
* consolidated from code scattered across multiple applications
* MD5-Crypt, SHA-256-Crypt, SHA-512-Crypt support
* MD5-Crypt, SHA256-Crypt, SHA512-Crypt support
......@@ -5,7 +5,7 @@ PassLib |release| documentation
Introduction
============
PassLib is a library for encrypting, verifying, and managing password hashes.
It supports over 20 current and historical password hash schemes.
It supports over 20 different password hash schemes.
It can be used for a variety of purposes:
* cross-platform replacement for stdlib's :func:`!crypt`.
......@@ -21,8 +21,25 @@ It can be used for a variety of purposes:
Quick Links
===========
* See the :doc:`Library Overview <overview>` for more details about passlib.
.. raw:: html
* See the :doc:`Installation Instructions <install>` to get PassLib installed on your system.
<table class="contentstable" align="center">
<tr>
<td width="50%" valign="top">
<p class="biglink">
<a class="biglink" href="overview.html">Library Overview</a><br>
<span class="linkdescr">describes how PassLib is laid out</span>
</p>
* See the :mod:`passlib.hash <passlib.hash>` module for a complete list of supported hash algorithms.
<p class="biglink">
<a class="biglink" href="install.html">Installation</a><br>
<span class="linkdescr">requirements and installation instructions</span>
</p>
<p class="biglink">
<a class="biglink" href="lib/passlib.hash.html"><i>passlib.hash</i> module</a><br>
<span class="linkdescr">complete list of supported password hash algorithms</span>
</p>
</td>
</tr>
</table>
......@@ -4,56 +4,58 @@ Installation
Requirements
============
PassLib currently has no external depedancies besides Python itself:
* Python 2.5 - 2.7 is required.
* Python 2.5 or better is required.
.. note::
* PassLib has not been tested with Python 2.4 or earlier,
and no guarantees are made about whether PassLib will work with them.
PassLib has not been tested with Python 2.4 or earlier,
and no guarantees are made about whether PassLib will work with those versions.
* Python 3.x is **not** yet supported, work is ongoing.
.. note::
The following libraries are not required, but will be used if found:
Python 3.x is **not** yet supported, work is ongoing.
stdlib's :mod:`!crypt` module
* `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_ (optional)
:func:`!crypt()` will be used if present, and if the host
OS supports the specific scheme in question. OS support is autodetected
for the following schemes: des-crypt, md5-crypt, bcrypt, sha256-crypt,
and sha512-crypt.
If installed, pybcrypt will be used to support the BCrypt hash algorithm.
This is required if you want to handle BCrypt hashes,
and stdlib :mod:`!crypt` does not support BCrypt
(which is pretty much all non-BSD systems).
`py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_
* `M2Crypto <http://chandlerproject.org/bin/view/Projects/MeTooCrypto>`_ (optional)
If installed, pybcrypt will be used to support the BCrypt hash algorithm.
This is required if you want to handle BCrypt hashes,
and stdlib :mod:`!crypt` does not support BCrypt
(which is pretty much all non-BSD systems).
If installed, M2Crypto will be used to accelerate some
internal support functions, but it is not required.
`M2Crypto <http://chandlerproject.org/bin/view/Projects/MeTooCrypto>`_
If installed, M2Crypto will be used to accelerate some
internal support functions, but it is not required.
PassLib should be useable on all operating systems.
PassLib is pure-python, and should be useable on all platforms.
Installing
==========
PassLib can be installed with easy_install / pip, linked/copied into sys.path directly
from it's source directory, or installed using :samp:`{$SOURCE}/setup.py install`,
where :samp:`{$SOURCE}` is the path to the PassLib source directory.
PassLib is pure python, there is nothing to compile or configure.
To install from source directory using ``setup.py`` (requires Setuptools or Distribute)::
python setup.py build
sudo python setup.py install
To install using easy_install::
easy_install passlib
To install using pip::
pip install passlib
Testing
=======
PassLib contains a comprehensive set of unittests providing nearly complete coverage.
All unit tests are contained within the :mod:`passlib.tests` package,
and are designed to be run using the `Nose <http://somethingaboutorange.com/mrl/projects/nose>`_ unit testing library.
Once PassLib and Nose have been installed::
# to run the basic tests from the source directory...
Once PassLib and Nose have been installed, the tests may be run from the source directory::
# to run the platform-relevant tests...
nosetests -v passlib/tests
# to run ALL tests from the source directory...
# to run all tests...
PASSLIB_TESTS="all" nosetests -v passlib/tests
Documentation
......@@ -68,7 +70,7 @@ you will need to:
* install `astdoc <http://www.assurancetechnologies.com/software/astdoc>`_ (a bundle of custom sphinx themes & extensions
used by Assurance Technologies).
* download the PassLib source
* run :samp:`python {$SOURCE}/docs/make.py clean html` (where :samp:`{$SOURCE}` is the path to the PassLib source directory).
* run :samp:`python docs/make.py clean html`.
Once Sphinx completes it's run, point a web browser to the file at :samp:`{$SOURCE}/docs/_build/html/index.html`
Once Sphinx completes it's run, point a web browser to the file at :samp:`docs/_build/html/index.html`
to access the PassLib documentation in html format.
===============================================
:mod:`passlib.context` - CryptContext interface
===============================================
.. currentmodule:: passlib.context
.. autoclass:: CryptContext(schemes=None, policy=<default policy>, \*\*kwds)
.. autoclass:: CryptPolicy(\*\*kwds)
.. _cryptcontext-options:
=============================================
:mod:`passlib.context` - CryptContext options
=============================================
.. currentmodule:: passlib.context
Context Configuration Policy
============================
.. warning::
The :class:`CryptContext` accepts a number of keyword options.
These are divides into the "context options", which affect
the context instance directly, and the "hash options",
which affect the context treats a particular type of hash:
This section's writing and design are still very much in flux.
Context Options
===============
The following keyword options are accepted by both the :class:`CryptContext`
and :class:`CryptPolicy` constructors, and directly affect the behavior
of the :class:`!CryptContext` instance itself:
Each CryptContext instance is extremely configuration through a wide range
of options. All of these options can be specified via the CryptContext
constructor, or by loading the configuration of a section of an ini file
(allowing an application's password policy to be specified externally).
``schemes``
List of handler names and/or instances which the CryptContext should recognize.
This is usually required.
All configuration options are stored in a CryptPolicy object,
which can be created in the following ways:
For use in INI files, this may also be specified as a single comma-separated string
of handler names.
* passing in options as keywords to it's constructor
* loading options from a section of a :mod:`ConfigParser` ini file.
* compositing together existing CryptPolicy objects (this allows for default policies, application policies, and run-time policies)
Any names specified must be registered globally with PassLib.
Hash Configuration Options
==========================
Options for configuring a specific hash take the form of the name of
``{name}.{option}`` (eg ``sha512_crypt.default_rounds``); where ``{name}`` is usually the name of a password hash,
and ``{option}`` is one of the options specified below.
There are a few reserved hash names:
Any options of the form ``all.{option}`` will be inherited by all hashes
if they do not have a ``{hash}.{option}`` value overriding the default.
Any options of the form ``context.{option}`` will be treated as options for the context object itself,
and not for a specified hash. Any options of the form ``{option}`` are taken to implicitly
belong to the context, and are treated as if they started with the prefix ``context.``.
The remaining options -
Example: ``schemes=["sha256_crypt", "md5_crypt", "des_crypt"]``.
``context.schemes``
comma separated list of the schemes this context should recognize, specified by name.
when a context is identifying hashes, it will check each scheme in this list
in order. if this value is being specified programmatically,
it may also be a python list containing a mixture of names
and password hash handler objects.
``deprecated``
``context.deprecated``
comma separated list of the schemes which this context should recognize,
generated hashes only if explicitly requested, and for which ``context.hash_needs_update()`` should return ``False``.
if not specified, none are considered deprecated.
this must be a subset of the names listed in context.schemes
List of handler names which should be considered deprecated by the CryptContext.
This should be a subset of the names of the handlers listed in schemes.
This is optional, if not specified, no handlers will be considered deprecated.
``context.default``
the default scheme context should use for generating new hashes.
if not specified, the first entry in ``context.schemes`` is used.
For use in INI files, this may also be specified as a single comma-separated string
of handler names.
``context.min_verify_time``
if specified, all ``context.verify()`` calls will take at least this many seconds.
if set to an amount larger than the time used by the strongest hash in the system,
this prevents an attacker from guessing the strength of particular hashes remotely.
(specified in fractional seconds).
This is primarily used by :meth:`CryptContext.hash_needs_update` and :meth:`CryptPolicy.handler_is_deprecated`.
If the application does not use these methods, this option can be ignored.
``{hash}.min_rounds``, ``{hash}.max_rounds``
Example: ``deprecated=["des_crypt"]``.
place limits on the number of rounds allowed for a specific hash.
``default``
* these are configurable per-context limits, hard limits set by algorithm are always applied
* if min > max, max will be increased to equal min.
* ``context.genconfig()`` or ``config.encrypt()`` - requests outside of these bounds will be clipped.
* ``context.hash_needs_update()`` - existing hashes w/ rounds outside of range are not compliant
* for hashes which do not have a rounds parameter, these values are ignored.
Specifies the name of the default handler to use when encrypting a new password.
If no default is specified, the first handler listed in ``schemes`` will be used.
``{hash}.default_rounds``
Example: ``default="sha256_crypt"``.
sets the default number of rounds to use when generating new hashes.
``min_verify_time``
* if this value is out side of per-policy min/max, it will be clipped just like user provided value.
* ``context.genconfig()`` or ``config.encrypt()`` - if rounds are not provided explicitly, this value will be used.
* for hashes which do not have a rounds parameter, this value is ignored.
* if not specified, max_rounds is used if available, then min_rounds, then the algorithm default.
If specified, all :meth:`CryptContext.verify` calls will take at least this many seconds.
If set to an amount larger than the time used by the strongest hash in the system,
this prevents an attacker from guessing the strength of particular hashes through timing measurements.
``{hash}.vary_rounds``
Specified in integer or fractional seconds.
[only applies if ``{hash}.default_rounds`` is specified and > 0]
Example: ``min_verify_time=0.1``.
if specified, every time a new hash is created using {hash}/default_rounds for it's rounds value,
the actual value used is generated at random, using default_rounds as a hint.
.. note::
* integer value - a value will be chosen using the formula ``randint(default_rounds-vary_rounds, default_rounds+vary_rounds)``.
* integer value between 0 and 100 with ``%`` suffix - same as above, with integer value equal to ``vary_rounds*default_rounds/100``.
* note that if algorithms indicate they use a logarthmic rounds parameter, the percent syntax equation uses ``log(vary_rounds*(2**default_rounds)/100,2)``,
to permit a default value to be applicable to all schemes. XXX: this might be a bad / overly complex idea.
For symmetry with the format of the hash option keywords (below),
all of the above context option keywords may also be specified
using the format :samp:`context__{option}` (note double underscores),
or :samp:`context.{option}` within INI files.
``{hash}.{setting}``
any keys which match the name of a configuration parameter accepted by the hash
will be used directly as default values.
.. note::
* for security purposes, ``salt`` is *forbidden* from being used in this way.
* if ``rounds`` is specified directly, it will override the entire min/max/default_rounds framework.
To override context options for a particular :ref:`user category <user-categories>`,
use the format :samp:`{category}__context__{option}`,
or :samp:`{category}.context.{option}` within an INI file.
``{hash}.{other}``
any keys which do not fall under the above categories will be ignored
Hash Options
============
The following keyword options are accepted by both the :class:`CryptContext`
and :class:`CryptPolicy` constructors, and affect how a :class:`!CryptContext` instance
treats hashes belonging to a particular hash scheme, as identified by the hash's handler name.
User Categories
===============
One frequent need is for certain categories of users (eg the root account)
to have more strigent password requirements than default users.
PassLib allows this by recognizing options of the format ``{category}.{name}.{option}``,
and allowing many of it's entry methods to accept an optional ``category`` parameter.
All hash option keywords should be specified using the format :samp:`{hash}__{option}`
(note double underscores); where :samp:`{hash}` is the name of the hash's handler,
and :samp:`{option}` is the name of the specific options being set.
Within INI files, this may be specified using the alternate format :samp:`{hash}.{option}`.
:samp:`{hash}__default_rounds`
Sets the default number of rounds to use when generating new hashes (via :meth:`CryptContext.encrypt`).
If not set, this will use max rounds hash option (see below),
or fall back to the algorithm-specified default.
For hashes which do not support a rounds parameter, this option is ignored.
:samp:`{hash}__vary_rounds`
if specified along with :samp:`{hash}__default_rounds`,
this will cause each new hash created by :meth:`CryptContext.encrypt`
to have a rounds value random chosen from the range :samp:`{default_rounds} +/- {vary_rounds}`.
this may be specified as an integer value, or as a string containing an integer
with a percent suffix (eg: ``"10%"``). if specified as a percent,
the amount varied will be calculated as a percentage of the :samp:`{default_rounds}` value.
The default passlib policy sets this to ``"10%"``.
.. note::
If this is specified as a percentage, and the hash algorithm
uses a logarithmic rounds parameter, the amount varied
will be calculated based on the effective number of linear rounds,
not the actual rounds value.
This allows ``vary_rounds`` to be given a default value for all hashes
within a context, and behave sanely for both linear and logarithmic rounds parameters.
:samp:`{hash}__min_rounds`, :samp:`{hash}__max_rounds`
Place limits on the number of rounds allowed for a specific hash.
``min_rounds`` defaults to 0, ``max_rounds`` defaults to unlimited.
When encrypting new passwords with the specified hash (via :meth:`CryptContext.encrypt`),
the number of rounds will be clipped to these boundaries.
When checking for out-of-date hashes (via :meth:`CryptContext.hash_needs_update`),
it will flag any whose rounds are outside the range specified as needing to be re-encrypted.
For hashes which do not support a rounds parameter, these options are ignored.
When one is specified, any ``{category}.{name}.{option}`` keywords in the configuration
will override any ``{name}.{option}`` keywords.
.. note::
In order to simplify behavior and implementation, categories cannot override the ``context/schemes`` keyword,
though they may override the other context keys.
These are configurable per-context limits,
they will be clipped by any hard limits set in the hash algorithm itself.
Default Policies
================
PassLib defines a library-default policy, updated perodically, providing (hopefully) sensible defaults for the various contexts.
:samp:`{hash}__{setting}`
Any other option values, which match the name of a parameter listed
in the hash algorithm's ``handler.setting_kwds`` attribute,
will be passed directly to that hash whenever :meth:`CryptContext.encrypt` is called.