Commit 0847ed96 authored by Eli Collins's avatar Eli Collins

doc cleanups

parent aac68dde49ef
......@@ -14,7 +14,18 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
import os, sys
#make sure passlib in sys.path
doc_root = os.path.abspath(os.path.join(__file__,os.path.pardir))
source_root = os.path.abspath(os.path.join(doc_root,os.path.pardir))
sys.path.insert(0, source_root)
#check for Assurance Technologies' BPS library, to conditionally load in some helpers
try:
import bps
except ImportError:
bps = None
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
......@@ -48,7 +59,7 @@ index_doc = 'index'
# General information about the project.
project = u'PassLib'
copyright = u'2004-2009, Assurance Technologies, LLC'
copyright = u'2008-2010, Assurance Technologies, LLC'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
......@@ -111,16 +122,17 @@ keep_warnings = True
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = 'cloud'
##html_theme = 'cloud'
html_theme = "nature"
# 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.
html_theme_options = { "roottarget": index_doc }
##html_theme_options = { "roottarget": index_doc }
# Add any paths that contain custom themes here, relative to this directory.
from bps.unstable.bpsdoc import theme_path
html_theme_path = [theme_path]
##from bps.unstable.bpsdoc import theme_path
##html_theme_path = [theme_path]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
......
......@@ -9,12 +9,11 @@ Table Of Contents
overview
lib/passlib
lib/passlib.rng
lib/passlib.hash
lib/passlib.gen
lib/passlib.util
history
roadmap
copyright
* :ref:`General Index <genindex>`
......
......@@ -4,7 +4,7 @@ Copyrights & Licenses
Copyright
=========
The BPS library is (c) 2004-2009 `Assurance Technologies, LLC <http://www.assurancetechnologies.com>`_,
The PassLib library is (c) 2008-2010 `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.
......@@ -14,9 +14,9 @@ This library is released under the BSD license; we hope you find it useful.
::
The BPS Python Library
The PassLib Python Library
Copyright (c) 2004-2009 Assurance Technologies, LLC
Copyright (c) 2008-2010 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
......@@ -34,17 +34,17 @@ This library is released under the BSD license; we hope you find it useful.
Third Party Software
====================
BPS contains some code taken from various third-party sources, which have their
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 BPS derived from them.
of PassLib derived from them.
GPW
---
The class :class:`bps.security.pwgen.GpwGenerator`
The class :class:`passlib.gen.GpwGenerator`
is a python implementation of Tom Van Vleck's phonetic
password algorithm `GPW <http://www.multicians.org/thvv/gpw.html>`_.
It's released under informally worded BSD-like terms.
password generation algorithm `GPW <http://www.multicians.org/thvv/gpw.html>`_.
It's released under informally worded BSD-compatible terms.
jBcrypt
-------
......@@ -52,10 +52,10 @@ jBcrypt
implementation of OpenBSD's BCrypt algorithm, written by Damien Miller,
and released under a BSD license.
:mod:`bps.security._bcrypt` is a python translation of this code,
which is used as a fallback backend for :class:`bps.security.pwhash.BCrypt`
:mod:`passlib._bcrypt` is a python translation of this code,
which is used as a fallback backend for :class:`passlib.hash.BCrypt`
when the external python library `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_
is not available.
is not installed.
This is the license and copyright for jBCrypt::
......@@ -75,7 +75,7 @@ This is the license and copyright for jBCrypt::
MD5-Crypt
---------
The class :class:`bps.security.pwgen.Md5Crypt` is a pure-python
The class :class:`passlib.hash.Md5Crypt` is a pure-python
implementation of the md5-crypt password hashing algorithm.
It's derived from the FreeBSD md5-crypt implementation `<http://www.freebsd.org/cgi/cvsweb.cgi/~checkout~/src/lib/libcrypt/crypt.c?rev=1.2>`_,
which was released under the following license::
......@@ -85,36 +85,6 @@ which was released under the following license::
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
PEP 3101
--------
:pep:`3101` defines a new string templating system
via the method ``string.format()``, which is built-in
to Python 2.6 and higher. :mod:`bps.text._string_format` is a pure-python
implementation of PEP 3101, used by BPS to backport this feature
to Python 2.5 (see :mod:`bps.text` for usage).
While the current implementation has been rewritten drastically
(to pass the python 2.6 format() unittests), it was originally
based on the one created by Patrick Maupin and Eric V. Smith, as found in
the PEP 3101 sandbox at `<http://svn.python.org/view/sandbox/trunk/pep3101/>`_.
While no license was attached, it is assumed to have been released
under an equivalent license to the `Python source code`_.
Python Source Code
------------------
BPS contains many small fragments taken from the Python 2.6.2 source code,
mainly for the purpose of backporting 2.6 features to python 2.5:
* :mod:`bps.text._string_format`, contains a modified copy of
Python 2.6's :class:`string.Formatter`, as part of BPS's
Python 2.6-compatible PEP3101 implementation for Python 2.5.
* :class:`bps.types.namedtuple` is a adaptation of
the Python 2.6 namedtuple class, for use with Python 2.5.
The Python 2.6.2 source code is licensed under the
`Python Software Foundation License, Version 2 <http://www.python.org/download/releases/2.6.2/license/>`_.
UnixCrypt.java
--------------
`UnixCrypt.java <http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt>`_
......@@ -122,8 +92,8 @@ is 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.
:mod:`bps.security._unix_crypt` is a python translation of this code,
which is used as a fallback backend for :class:`bps.security.pwhash.UnixCrypt`
:mod:`passlib._unix_crypt` is a python translation of this code,
which is used as a fallback backend for :class:`passlib.hash.UnixCrypt`
for platforms where stdlib's :mod:`crypt` is not available.
This is the license and copyright for UnixCrypt.java::
......
==========================================
BPS |release| documentation
PassLib |release| documentation
==========================================
Introduction
============
Welcome to the documentation for BPS.
Welcome to the documentation for PassLib.
BPS is a "swiss army knife"-style library,
composed of a number of smaller interdependant modules.
Collectively, these modules form a package which provides
a wide array of useful tools and classes for writing
programs under Python. There are good odds that BPS contains
something useful for any python program, large or small.
PassLib is a
A quick sample of some of the more frequently used modules:
......@@ -19,7 +14,7 @@ A quick sample of some of the more frequently used modules:
* :mod:`bps.host` -- desktop and host resources
* :mod:`bps.logs` -- enhancements to Python's logging system
* :mod:`bps.text` -- text parsing and formatting
* :mod:`bps.security.pwhash` -- password hashing algorithms
* :mod:`passlib.hash` -- password hashing algorithms
... see the :doc:`library overview <overview>` for a complete list.
......
......@@ -4,50 +4,48 @@ Installation
Requirements
============
BPS tries to use pure-python implementations of things whereever possible,
PassLib tries to use pure-python implementations of things whereever possible,
and have as few dependancies as possible. The current set of requirements is:
* Python 2.5 or better is required (Python 2.6 is supported).
* BPS is no longer tested for Python 2.4.x or earlier,
no guarantees are made about whether BPS will work with them.
* PassLib is no longer tested for Python 2.4.x or earlier,
no guarantees are made about whether PassLib will work with them.
* Python 3.0 has **not** been assessed for compatibility. It probably won't work.
* The `pywin32 <http://sourceforge.net/projects/pywin32/>`_ package is required
when running under windows.
The following libraries will be used if present, but they are not required:
* If installed, `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_ will be
used instead of BPS's slower pure-python bcrypt implementation.
(see :class:`bps.security.pwhash.BCrypt`).
used instead of PassLib's slower pure-python bcrypt implementation.
(see :class:`passlib.hash.BCrypt`).
Installing
==========
BPS can be installed with easy_install, linked/copied into sys.path directly
from it's source directory, or installed using "setup.py".
BPS is pure python, there is nothing to compile or configure.
PassLib can be installed with easy_install, linked/copied into sys.path directly
from it's source directory, or installed using ``$SOURCE/setup.py install``,
where ``$SOURCE`` is the path to the PassLib source directory.
PassLib is pure python, there is nothing to compile or configure.
Testing
=======
BPS contains a number of unittests (sadly, coverage is not yet complete).
all of which are contained within the :mod:`bps.tests` module,
PassLib contains a number of unittests (sadly, coverage is not yet complete).
all of which are contained within the :mod:`passlib.tests` module,
and are designed to be run use the `nose <http://somethingaboutorange.com/mrl/projects/nose>`_ library.
Once BPS and nose have been installed, you may run the following commands::
Once PassLib and nose have been installed, you may run the following commands::
#to run the full bps test suite
nosetests bps.tests
#to run the standard passlib test suite:
nosetests passlib/tests
#the full suite with some extra longer-running tests
export BPS_DEV_TESTS=true
nosetests bps.tests
#to run the standard suite + some additional longer-running tests:
export PASSLIB_DEV_TESTS=true
nosetests passlib/tests
Documentation
=============
BPS uses Sphinx to generate it's documentation.
To create your own copy, make sure you have Sphinx 0.6.3 or better installed,
as well as BPS, and run ``python $SOURCE/docs/make.py clean html``,
where ``$SOURCE`` is the path to the BPS source directory.
PassLib uses Sphinx to generate it's documentation.
To create your own copy, make sure you have Sphinx 1.0 or better installed,
as well as PassLib, and run ``python $SOURCE/docs/make.py clean html``,
where ``$SOURCE`` is the path to the PassLib source directory.
Once this completes, point a browser to the file at ``$SOURCE/docs/_build/html/index.html``
to access the BPS documentation.
to access the PassLib documentation in html.
================================================
:mod:`bps.security.pwgen` -- Password Generation
:mod:`passlib.gen` -- Password Generation
================================================
.. module:: bps.security.pwgen
.. module:: passlib.gen
:synopsis: password generation algorithms
The following single function allows
......@@ -12,4 +12,3 @@ easy password generation in a number of styles:
.. todo::
document internal classes
=============================================
:mod:`bps.security.pwhash` - Password Hashing
:mod:`passlib.hash` - Password Hashing
=============================================
.. module:: bps.security.pwhash
.. module:: passlib.hash
:synopsis: password hashing (unix-crypt, md5-crypt, etc)
Overview
......@@ -21,24 +21,24 @@ The algorithms currently supported by default in BPS:
* MD5-Crypt
* BCrypt
* SHA-Crypt (256 & 512 bit modes)
* PostgreSQL & MySQL password hashes
Sections
========
The documentation for the pwhash module is broken into the following sections:
* :doc:`Quick Start <bps.security.pwhash/quickstart>` -- frontend funcs for quickly creating / validating hashes
* :doc:`Crypt Contexts <bps.security.pwhash/contexts>` -- for using just the algorithms your application needs
* :doc:`Crypt Algorithms <bps.security.pwhash/algorithms>` -- details of the algorithms BPS implements
* :doc:`Implementing a Custom Crypt Algorithm <bps.security.pwhash/implementation>` -- Roll your own
* :doc:`Helper Functions <bps.security.pwhash/utils>`
* :doc:`Quick Start <passlib.hash/quickstart>` -- frontend funcs for quickly creating / validating hashes
* :doc:`Crypt Contexts <passlib.hash/contexts>` -- for using just the algorithms your application needs
* :doc:`Crypt Algorithms <passlib.hash/algorithms>` -- details of the algorithms BPS implements
* :doc:`Implementing a Custom Crypt Algorithm <passlib.hash/implementation>` -- Roll your own
* :doc:`Helper Functions <passlib.hash/utils>`
.. toctree::
:hidden:
bps.security.pwhash/quickstart
bps.security.pwhash/contexts
bps.security.pwhash/algorithms
bps.security.pwhash/implementation
bps.security.pwhash/utils
passlib.hash/quickstart
passlib.hash/contexts
passlib.hash/algorithms
passlib.hash/implementation
passlib.hash/utils
=============================================
:mod:`bps.security.pwhash` - Crypt Algorithms
:mod:`passlib.hash` - Crypt Algorithms
=============================================
.. currentmodule:: bps.security.pwhash
.. currentmodule:: passlib.hash
All of the crypt algorithms must inherit from :class:`CryptAlgorithm`,
which defines a common interface all algorithms must support.
......
=============================================
:mod:`bps.security.pwhash` - Crypt Contexts
:mod:`passlib.hash` - Crypt Contexts
=============================================
.. currentmodule:: bps.security.pwhash
.. currentmodule:: passlib.hash
For more complex deployment scenarios than
the frontend functions described in :doc:`Quick Start <quickstart>`,
......
===================================================================
:mod:`bps.security.pwhash` - Implementing a Custom Crypt Algorithm
:mod:`passlib.hash` - Implementing a Custom Crypt Algorithm
===================================================================
.. currentmodule:: bps.security.pwhash
.. currentmodule:: passlib.hash
New password algorithms can be implemented
by subclassing :class:`CryptAlgorithm`,
......
========================================
:mod:`bps.security.pwhash` - Quick Start
:mod:`passlib.hash` - Quick Start
========================================
.. currentmodule:: bps.security.pwhash
.. currentmodule:: passlib.hash
Usage Example
=============
......
=============================================
:mod:`bps.security.pwhash` - Helper Functions
:mod:`passlib.hash` - Helper Functions
=============================================
.. currentmodule:: bps.security.pwhash
.. currentmodule:: passlib.hash
A couple of utility functions are available,
mainly useful when writing custom password hash algorithms.
......
=================================================
:mod:`bps.rng` -- Random Number Generation
=================================================
.. module:: bps.rng
:synopsis: random number generation
This module is essentially just a wrapper for stdlib's
random module. It provides a few additional
methods for managing & getting random numbers,
but also provides a more useful interface
for the *type* of randomness you want.
Random Number Generators
========================
The following random number generator
instances are always available from this module:
.. data:: random
This will be an instance of the best pseudo random number generator
available (currently the python builtin prng), with as good
an entropic source as is available for seeding via
the seed() and reseed() methods.
Use this for most non-cryptographic purposes.
.. data:: srandom
This will be an instance of the strongest random number generator
available on your system. It will use python's SystemRandom
if os.urandom support is available, otherwise it will fall back
to the same generator as prandom. This should be used
for cryptographic purposes over the normal prng.
.. warning::
If urandom is present, this is dependant on the strength
of your system's urandom implementation. If urandom is missing,
the fallback (normal) may not have enough entropy to defend
from attackers. To help this somewhat, it is recommended
to call ``strong.reseed()`` before calls which will consume
randomness for critical purposes, just to help scramble things
as best as possible (reseed is a no-op if urandom is being used).
.. data:: drandom
This is a variant of the *random* generator,
except that all outside entropic
sources are disabled, so that it's state is completely
deteremined by the value passed into seed().
This is mainly useful in unitests, when you need
to reliably repeat the same results over an over.
Extra Methods
=============
In addition to the methods provided by stdlib's random module,
all the above rngs will contain the following extra methods:
.. function:: reseed()
Unlike seed(), which attempts to set the random number generator's
state explicitly, this method attempts to pull in outside
entropy sources (current rng state, time, etc) to help
randomize the state of your prng as much as possible.
.. todo::
In the future, need a way for app to add entropy to the system.
.. function:: getrandbytes()
.. function:: weightedchoice()
"Makefile for Sphinx documentation, adapted to python"
import os, sys
doc_root = os.path.abspath(os.path.join(__file__,os.path.pardir))
source_root = os.path.abspath(os.path.join(doc_root,os.path.pardir))
sys.path.insert(0, source_root)
from bps.unstable.bpsdoc.make_helper import SphinxMaker
SphinxMaker.execute(root=__file__)
=======
Roadmap
=======
Planned Features
================
The follow is the list of pending tasks which definitely need to be completed
for BPS, roughly in the order they will probably get done:
* Finish rewriting and documentation BPS's enhancements to the
standard logging system.
* Clean up "bps.host" interface system, and document it.
* Make sure config_parser module has been converted.
* Unittests do not have good overall coverage.
* The following modules have yet to be documented:
- bps.numeric
- bps.undef
- bps.logs
* Release to public.
This is being put off until documentation and unittests are fleshed out more,
and some needed redesigns are done before external apps become dependant
on legacy behaviors.
Wishlist
========
The following are things which it would be nice to add to BPS,
but the need is not pressing, and no particular plans have been drawn up:
* Merge into BPS the security policy framework
currently used by many of our projects.
(probably under "bps.security.policy").
* Fix major bug: :func:`bps.fs.filepath` does not support unicode.
* Merge in the planetbox numeric and stream routines.
* Merge in the threading and dispatcher routines
from internal "pxhelpers" library.
* Merge into BPS the user-interaction subsystem from our internal
"automigrate" library (probably under "bps.host.interact").
* Merge in "signals", "app.locking", and "app.command"
packages from the internal company library "astllc".
Todos
=====
.. todolist::
"""passlib._bcrypt
Derivation
History
==========
This is a pure-python implementation of the bcrypt hash algorithm.
It's based off the java bcrypt implementation jBcrypt 0.2,
downloaded from http://www.mindrot.org/projects/jBCrypt/.
This is a pure-python implementation of the bcrypt hash algorithm,
based off the java bcrypt implementation jBcrypt 0.2,
as downloaded from http://www.mindrot.org/projects/jBCrypt/.
The original jBcrypt was released with the following license::
jBcrypt was released under the BSD license::
Copyright (c) 2006 Damien Miller <djm@mindrot.org>
......@@ -22,15 +22,17 @@ The original jBcrypt was released with the following license::
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
The original jBcrypt source was converted line-by-line from java
and then optimized for python by Eli Collins <elic@astllc.org>
This python implementation was adapted from jBcrypt by Eli Collins <elic@astllc.org>,
and released under the BSD license as part of PassLib.
This is meant mainly as a fall-back for passlib to use,
if you need speedy bcrypt support, install the python-bcrypt
library, and passlib will use _it_ instead of this module.
This module is meant mainly as a fall-back for PassLib to use as a last restore.
If you need speedy bcrypt support, install the python-bcrypt library,
and passlib will use it instead of this module.
This module is not suitable for production use, as it's incredibly slow.
The bcrypt unit-tests in passlib.test.test_bcrypt
will test all available backends.
The bcrypt unit-tests in passlib.tests.test_bcrypt
will test all bcrypt backends found, not just the preferred one,
in order to ensure no impedance mismatch.
Usage
=====
......
......@@ -2,10 +2,8 @@
History
=======
This python implementation was created by Eli Collins <elic@astllc.org>,
by doing a line-by-line conversion of the Java-based implementation found at
http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt
and then precalculating tables and pythonizing as much as possible.
This is a pure-python implementation of the unix "crypt" algorithm,
based on the Java implementation found at http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt
The copyright & license for that source is as follows::
......@@ -34,10 +32,12 @@ The copyright & license for that source is as follows::
@version $Id: UnixCrypt2.txt,v 1.1.1.1 2005/09/13 22:20:13 christos Exp $
@author Greg Wilkins (gregw)
---
converted to python and modified
June 2009
by Eli Collins <elic@astllc.org>
This python implementation was adapted from this source by Eli Collins <elic@astllc.org>,
and released under the BSD license as part of PassLib.
This module is mainly meant as a fallback when stdlib does not supply a ``crypt`` implementation,
such as on windows systems. As such, it attempts to have a public interface
which is compatible with stdlib, so it can be used as a drop-in replacement.
"""
#=========================================================
......@@ -64,7 +64,7 @@ RR12_1 = range(11, 1, -1)
PCXROT = IE3264 = SPE = CF6464 = None #placeholders filled in by load_tables
def load_tables():
"delay loading data until it's needed for the first time"
"delay loading tables until they are actually needed"
global PCXROT, IE3264, SPE, CF6464
#---------------------------------------------------
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment