Commit 8195ce41 authored by Eli Collins's avatar Eli Collins

updated front matter and other documentation

parent 3e09b3e2a50a
......@@ -5,6 +5,7 @@ Release History
===============
**1.6** (NOT YET RELEASED)
==========================
Hashes
......@@ -58,7 +59,7 @@ Release History
of :func:`!os_crypt`.
* The :doc:`ldap salted digests </lib/passlib.hash.ldap_std>`
now support salts from 4-16 bytes [issue 30].
now support salts from 4-16 bytes :issue:`30`.
* :class:`bsdi_crypt` now issues a warning if an even number of rounds
is requested by the application, due to a known weakness in DES.
......@@ -231,7 +232,7 @@ Release History
*all* passwords if any of the padding bits are set. Thus Passlib's
BCrypt salt generation needed to be fixed to ensure compatibility,
and a route provided to correct existing hashes already out in the wild
[issue 25].
:issue:`25`.
*Changes in this release:*
......@@ -266,7 +267,7 @@ Release History
* *bugfix:* :class:`django_des_crypt` now accepts all
:data:`hash64 <passlib.utils.h64>` characters in it's salts;
previously it accepted only lower-case hexidecimal characters [issue 22].
previously it accepted only lower-case hexidecimal characters :issue:`22`.
* Additional unittests added for all
standard :doc:`Django hashes </lib/passlib.hash.django_std>`.
......@@ -290,16 +291,16 @@ Release History
Minor bugfix release -- now compatible with Google App Engine.
* *bugfix:* make ``passlib.hash.__loader__`` attribute writable -
needed by Google App Engine (GAE) [issue 19].
needed by Google App Engine (GAE) :issue:`19`.
* *bugfix:* provide fallback for loading ``passlib/default.cfg``
if :mod:`pkg_resources` is not present, such as for GAE [issue 19].
if :mod:`pkg_resources` is not present, such as for GAE :issue:`19`.
* *bugfix:* fixed error thrown by CryptContext.verify
when issuing min_verify_time warning [issue 17].
when issuing min_verify_time warning :issue:`17`.
* removed min_verify_time setting from custom_app_context,
min_verify_time is too host & load dependant to be hardcoded [issue 17].
min_verify_time is too host & load dependant to be hardcoded :issue:`17`.
* under GAE, disable all unittests which require writing to filesystem.
......@@ -474,7 +475,7 @@ Release History
.. note::
For this and all previous versions, PassLib did not exist independantly,
For this and all previous versions, Passlib did not exist independantly,
but as a subpackage of *BPS*, a private & unreleased toolkit library.
* many bugfixes
......
......@@ -42,7 +42,7 @@ and is released under the `BSD license <http://www.opensource.org/licenses/bsd-l
Licenses for incorporated software
==================================
PassLib contains some code derived from the following sources:
Passlib contains some code derived from the following sources:
MD5-Crypt
---------
......
.. -*- restructuredtext -*-
==========================
The PassLib Python Library
The Passlib Python Library
==========================
Welcome
=======
Passlib is a password hashing library for Python 2 & 3,
which provides cross-platform implementations of over 20
password hashing algorithms, as well as a framework for
managing existing password hashes. It's designed to be useful
for a wide range of tasks, from verifying a hash found in /etc/shadow,
to providing full-strength password hashing for multi-user application.
Passlib is a password hashing library for Python 2 & 3, which provides
cross-platform implementations of over 30 password hashing algorithms, as well
as a framework for managing existing password hashes. It's designed to be useful
for a wide range of tasks, from verifying a hash found in /etc/shadow, to
providing full-strength password hashing for multi-user application.
The latest documentation can be found online at `<http://packages.python.org/passlib>`_.
......
# -*- coding: utf-8 -*-
#
# PassLib documentation build configuration file, created by
# Passlib documentation build configuration file, created by
# sphinx-quickstart on Mon Mar 2 14:12:06 2009.
#
# This file is execfile()d with the current directory set to its containing dir.
......@@ -57,6 +57,9 @@ extensions = [
# replace sphinx :samp: role handler with one that allows escaped {} chars
'cloud_sptheme.ext.escaped_samp_literals',
# add "issue" role
'cloud_sptheme.ext.issue_tracker',
]
# Add any paths that contain templates here, relative to this directory.
......@@ -73,7 +76,7 @@ master_doc = 'contents'
index_doc = 'index'
# General information about the project.
project = u'PassLib'
project = u'Passlib'
copyright = u'2008-2011, Assurance Technologies, LLC'
# The version info for the project you're documenting, acts as replacement for
......@@ -99,8 +102,11 @@ version = csp.get_version(release)
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [
#disabling documentation of this until module is more mature.
# disabling documentation of this until module is more mature.
"lib/passlib.utils.compat.rst",
# may remove this in future release
"lib/passlib.utils.md4.rst",
]
# The reST default role (used for this markup: `text`) to use for all documents.
......@@ -126,6 +132,7 @@ modindex_common_prefix = [ "passlib." ]
# -- Options for all output ---------------------------------------------------
todo_include_todos = "hide-todos" not in options
keep_warnings = "hide-warnings" not in options
issue_tracker_url = "gc:passlib"
# -- Options for HTML output ---------------------------------------------------
......@@ -136,7 +143,7 @@ html_theme = 'cloud'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
if html_theme == 'cloud':
if html_theme in ['cloud', 'redcloud']:
html_theme_options = { "roottarget": index_doc, "collapsiblesidebar": True }
if 'for-pypi' in options:
html_theme_options['googleanalytics_id'] = 'UA-22302196-2'
......
......@@ -3,23 +3,22 @@ Table Of Contents
=================
.. toctree::
:maxdepth: 4
Front Page <index>
install
new_app_quickstart
overview
new_app_quickstart
password_hash_api
lib/passlib.hash
lib/passlib.context-tutorial
lib/passlib.context
lib/passlib.apps
lib/passlib.apache
lib/passlib.hosts
lib/passlib.apache
lib/passlib.ext.django
lib/passlib.exc
......
==========================================
PassLib |release| documentation
Passlib |release| documentation
==========================================
Welcome
=======
Passlib is a password hashing library for Python 2 & 3,
which provides cross-platform implementations of over 20 password hashing algorithms,
as well as a framework for managing existing password hashes.
It's designed to be useful for a large range of tasks, including:
* quick-start password hashing for new python applications ~
:doc:`quickstart guide <new_app_quickstart>`
* constructing a configurable hashing policy
to match the needs of any python application ~
:data:`passlib.context`
* reading & writing Apache htpasswd / htdigest files ~
:mod:`passlib.apache`
* creating & verifying hashes used by MySQL, PostgreSQL, OpenLDAP,
and other applications ~
:mod:`passlib.apps`
* creating & verifying hashes found in Unix "shadow" files ~
:data:`passlib.hosts`
See the library overview for more details and usage examples.
Quick Links
===========
.. raw:: html
<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>
<p class="biglink">
<a class="biglink" href="install.html">Installation</a><br>
<span class="linkdescr">requirements and installation instructions</span>
</p>
</td>
<td width="50%" valign="top">
<p class="biglink">
<a class="biglink" href="lib/passlib.hash.html">Supported Hashes</a><br>
<span class="linkdescr">complete list of supported password hash algorithms</span>
</p>
<p class="biglink">
<a class="biglink" href="history.html">Changelog</a><br>
<span class="linkdescr">history of current and past releases</span>
</p>
</td>
</tr>
</table>
Passlib is a password hashing library for Python 2 & 3, which provides
cross-platform implementations of over 30 password hashing algorithms, as well
as a framework for managing existing password hashes. It's designed to be useful
for a wide range of tasks, from verifying a hash found in /etc/shadow, to
providing full-strength password hashing for multi-user application.
As a quick sample, the following code hashes and then verifies a password
using the :doc:`SHA256-Crypt </lib/passlib.hash.sha256_crypt>` algorithm::
>>> # import the hash algorithm
>>> from passlib.hash import sha256_crypt
>>> # generate new salt, and hash a password
>>> hash = sha256_crypt.encrypt("toomanysecrets")
>>> hash
'$5$rounds=80000$zvpXD3gCkrt7tw.1$QqeTSolNHEfgryc5oMgiq1o8qCEAcmye3FoMSuvgToC'
>>> # verifying the password
>>> sha256_crypt.verify("toomanysecrets", hash)
True
>>> sha256_crypt.verify("joshua", hash)
False
Contents
========
Introductory Materials
----------------------
:doc:`install`
requirements & installation instructions
:doc:`overview`
describes how Passlib is laid out
: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.
Support Modules
---------------
:mod:`passlib.exc`
custom warnings and exceptions used by Passlib
..
:mod:`passlib.registry`
:mod:`passlib.utils`
----
Other Documents
---------------
:doc:`modular_crypt_format`
reference listing "modular crypt format" support across Unix systems.
:doc:`Changelog <history>`
Passlib's release history
Online Resources
================
......@@ -66,12 +107,12 @@ Online Resources
.. rst-class:: html-plain-table
================ ===================================================
**Homepage**: `<http://passlib.googlecode.com>`_
**Online Docs**: `<http://packages.python.org/passlib>`_
**Discussion**: `<http://groups.google.com/group/passlib-users>`_
Homepage: `<http://passlib.googlecode.com>`_
Online Docs: `<http://packages.python.org/passlib>`_
Discussion: `<http://groups.google.com/group/passlib-users>`_
---------------- ---------------------------------------------------
---------------- ---------------------------------------------------
**PyPI**: `<http://pypi.python.org/pypi/passlib>`_
**Downloads**: `<http://code.google.com/p/passlib/downloads>`_
**Source**: `<http://code.google.com/p/passlib/source>`_
PyPI: `<http://pypi.python.org/pypi/passlib>`_
Downloads: `<http://code.google.com/p/passlib/downloads>`_
Source: `<http://code.google.com/p/passlib/source>`_
================ ===================================================
......@@ -52,12 +52,12 @@ To install from a source directory using :command:`setup.py`::
Testing
=======
PassLib contains a comprehensive set of unittests providing nearly complete coverage.
Passlib contains a comprehensive set of unittests providing nearly complete coverage.
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.
Once PassLib and Nose have been installed, the tests may be run 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 --tests passlib/tests
......@@ -82,9 +82,9 @@ you will need to:
1. Install `Sphinx <http://sphinx.pocoo.org/>`_ (1.0 or better)
2. Install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_.
3. Download the PassLib source
4. From the PassLib source directory, run :samp:`python setup.py build_sphinx`.
3. Download the Passlib source
4. From the Passlib source directory, run :samp:`python setup.py build_sphinx`.
5. Once Sphinx completes it's run, point a web browser to the file at :samp:`{$SOURCE}/build/sphinx/html/index.html`
to access the PassLib documentation in html format.
to access the Passlib documentation in html format.
6. Alternately, steps 4 & 5 can be replaced by running :samp:`python setup.py docdist`,
which will build a zip file of the documentation in :samp:`{$SOURCE}/dist`.
......@@ -10,10 +10,11 @@ htpasswd and htdigest files; though the use of two helper classes.
.. versionchanged:: 1.6
The api for this module was updated to be more flexible,
and to have (hopefully) less confusing method names.
The old method and keyword names are supported but deprecated, and
and to have less ambiguous method names.
The old method and keyword names are deprecated, and
will be removed in Passlib 1.8.
No more backwards-incompatible changes are currently planned.
No more backwards-incompatible changes are currently planned
for these classes.
.. index:: apache; htpasswd
......
......@@ -5,46 +5,45 @@
.. module:: passlib.apps
:synopsis: encrypting & verifying passwords used in sql servers and other applications
This lists a number of :class:`!CryptContext` instances that are predefined
by PassLib for easily handling the multiple formats used by various applications.
(For details about how to use a :class:`!CryptContext` instance,
see :doc:`passlib.context-usage`).
.. _predefined-context-example:
.. _quickstart-custom-applications:
This module contains a number of preconfigured :ref:`CryptContext <context-overview>` instances
that are provided by Passlib for easily handling the hash formats used by various applications.
Custom Applications
===================
.. data:: custom_app_context
.. rst-class:: html-toggle
This :class:`!CryptContext` object is provided for new python applications
to quickly and easily add password hashing support.
It offers:
Usage Example
=============
The :class:`!CryptContext` class itself has a large number of features,
but to give an example of how to quickly use the instances in this module:
* Support for :class:`~passlib.hash.sha256_crypt` and :class:`~passlib.hash.sha512_crypt`
* Defaults to SHA256-Crypt under 32 bit systems; SHA512-Crypt under 64 bit systems.
* Comes pre-configured with strong rounds settings.
Each of the objects in this module can be imported directly::
For applications which want to quickly add a password hash,
all they need to do is the following::
>>> #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
>>> # as an example, this imports the custom_app_context object,
>>> # a helper to let new applications *quickly* add password hashing.
>>> from passlib.apps import custom_app_context
>>> #encrypting a password...
>>> hash = pwd_context.encrypt("somepass")
Encrypting a password is simple (and salt generation is handled automatically)::
>>> #verifying a password...
>>> ok = pwd_context.verify("somepass", hash)
>>> hash = custom_app_context.encrypt("toomanysecrets")
>>> hash
'$5$rounds=84740$fYChCy.52EzebF51$9bnJrmTf2FESI93hgIBFF4qAfysQcKoB0veiI0ZeYU4'
>>> #[optional] encrypting a password for an admin account - uses stronger settings
>>> hash = pwd_context.encrypt("somepass", category="admin")
Verifying a password against an existing hash is just as quick::
.. seealso::
>>> custom_app_context.verify("toomanysocks", hash)
False
>>> custom_app_context.verify("toomanysecrets", hash)
True
The :doc:`/new_app_quickstart`.
.. seealso:: the :ref:`CryptContext Tutorial <context-tutorial>`
and :ref:`CryptContext Reference <context-reference>`
for more information about the CryptContext class.
.. index:: django; crypt context
.. _django-contexts:
Django
======
The following objects provide pre-configured :class:`!CryptContext` instances
......@@ -182,16 +181,22 @@ PostgreSQL
>>> from passlib.apps import postgres_context
>>> #encrypting a password...
>>> # encrypting a password...
>>> postgres_context.encrypt("somepass", user="dbadmin")
'md578ed0f0ab2be0386645c1b74282917e7'
>>> #verifying a password...
>>> # verifying a password...
>>> postgres_context.verify("somepass", 'md578ed0f0ab2be0386645c1b74282917e7', user="dbadmin")
True
>>> postgres_context.verify("wrongpass", 'md578ed0f0ab2be0386645c1b74282917e7', user="dbadmin")
False
>>> # forgetting the user will result in an error:
>>> postgres_context.encrypt("somepass")
Traceback (most recent call last):
<traceback omitted>
TypeError: user must be unicode or bytes, not None
.. index:: roundup; crypt context
Roundup
......@@ -218,3 +223,25 @@ The following contexts are available for reading Roundup password hash fields:
this is an alias for the latest version-specific roundup context supported
by passlib, currently the :data:`!roundup15_context`.
.. _quickstart-custom-applications:
Custom Applications
===================
.. data:: custom_app_context
This :class:`!CryptContext` object is provided for new python applications
to quickly and easily add password hashing support.
It comes preconfigured with:
* Support for :class:`~passlib.hash.sha256_crypt` and :class:`~passlib.hash.sha512_crypt`
* Defaults to SHA256-Crypt under 32 bit systems, SHA512-Crypt under 64 bit systems.
* Large number of ``rounds``, for increased time-cost to hedge against attacks.
For applications which want to quickly add a password hash,
all they need to do is import and use this object, per the
:ref:`usage example <predefined-context-example>` at the top of this page.
.. seealso::
The :doc:`/new_app_quickstart` for additional details.
......@@ -16,7 +16,13 @@ Exceptions
Warnings
========
.. autoexception:: PasslibWarning
Minor Warnings
--------------
.. autoexception:: PasslibConfigWarning
.. autoexception:: PasslibHashWarning
Critical Warnings
-----------------
.. autoexception:: PasslibRuntimeWarning
.. autoexception:: PasslibSecurityWarning
......@@ -5,25 +5,68 @@
.. module:: passlib.hosts
:synopsis: encrypting & verifying operating system passwords
This module provides :class:`!CryptContext` instances for encrypting &
verifying password hashes tied to user accounts of various operating systems.
This module provides some preconfigured :ref:`CryptContext <context-overview>`
instances for encrypting & 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.
.. seealso::
for Microsoft Windows, see the list of :ref:`windows-hashes`
in :mod:`passlib.hash`.
:mod:`passlib.context` module for details about how to use a :class:`!CryptContext` instance.
.. rst-class:: html-toggle
Usage Example
=============
The :class:`!CryptContext` class itself has a large number of features,
but to give an example of how to quickly use the instances in this module:
Each of the objects in this module can be imported directly::
>>> # as an example, this imports the linux_context object,
>>> # 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)::
>>> hash = linux_context.encrypt("toomanysecrets")
>>> hash
'$5$rounds=84740$fYChCy.52EzebF51$9bnJrmTf2FESI93hgIBFF4qAfysQcKoB0veiI0ZeYU4'
Verifying a password against an existing hash is just as quick::
>>> linux_context.verify("toomanysocks", hash)
False
>>> linux_context.verify("toomanysecrets", hash)
True
You can also identify hashes::
>>> linux_context.identify(hash)
'sha512_crypt'
Or encrypt using a specific algorithm::
>>> linux_context.schemes()
('sha512_crypt', 'sha256_crypt', 'md5_crypt', 'des_crypt', 'unix_disabled')
>>> linux_context.encrypt("password", scheme="des_crypt")
'2fmLLcoHXuQdI'
>>> linux_context.identify('2fmLLcoHXuQdI')
'des_crypt'
.. seealso::
the :ref:`CryptContext Tutorial <context-tutorial>`
and :ref:`CryptContext Reference <context-reference>`
for more information about the CryptContext class.
Unix Password Hashes
====================
PassLib provides a number of pre-configured :class:`!CryptContext` instances
Passlib provides a number of pre-configured :class:`!CryptContext` instances
which can identify and manipulate all the formats used by Linux and BSD.
See the :ref:`modular crypt identifier list <mcf-identifiers>` for a complete
list of which hashes are supported by which operating system.
Predefined Contexts
-------------------
PassLib provides :class:`!CryptContext` instances
Passlib provides :class:`!CryptContext` instances
for the following Unix variants:
.. data:: linux_context
......@@ -54,21 +97,6 @@ for the following Unix variants:
particularly the common strings ``!`` and ``*`` which are used to indicate
that an account has been disabled [#shadow]_.
A quick usage example, using the :data:`!linux_context` instance::
>>> from passlib.hosts import linux_context
>>> hash = linux_context.encrypt("password")
>>> hash
'$6$rounds=31779$X2o.7iqamZ.bAigR$ojbo/zh6sCmUuibhM7lnqR4Vy0aB3xGZXOYVLgtTFgNYiXaTNn/QLUz12lDSTdxJCLXHzsHiWCsaryAlcbAal0'
>>> linux_context.verify("password", hash)
True
>>> linux_context.identify(hash)
'sha512_crypt'
>>> linux_context.encrypt("password", scheme="des_crypt")
'2fmLLcoHXuQdI'
>>> linux_context.identify('2fmLLcoHXuQdI')
'des_crypt'
Current Host OS
---------------
......
......@@ -5,13 +5,23 @@
.. module:: passlib.registry
:synopsis: registry for tracking password hash handlers.
This module contains the code PassLib uses to track all password hash handlers
This module contains the code Passlib uses to track all password hash handlers
that it knows about. While custom handlers can be used directly within an application,
or even handed to a :class:`!CryptContext`; it is frequently useful to register
them globally within a process and then refer to them by name.
This module provides facilities for that, as well as programmatically
querying passlib to detect what algorithms are available.
.. warning::
This module is primarily used as an internal support module.
It's interface has not been finalized yet, and may be changed somewhat
between major releases of Passlib, as the internal code is cleaned up