documentation updates

=====================
* documentation added for mysql & postgres hashes
* enhanced autodocument() function's output
* added usage examples for more hashes

8 files changed, 172 insertions, 36 deletions

diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst
index 350fbac..7aa3041 100644
--- a/docs/lib/passlib.hash.des_crypt.rst
+++ b/docs/lib/passlib.hash.des_crypt.rst
@@ -24,17 +24,15 @@ This module can be used directly as follows::
 
     >>> dc.encrypt("password") #generate new salt, encrypt password
     'JQMuyS6H.AGMo'
-    >>> dc.genhash("password", "JQ") #generate password using existing config string
-    'JQMuyS6H.AGMo'
 
     >>> dc.identify('JQMuyS6H.AGMo') #check if hash is recognized
     True
-    >>> dc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if hash is recognized
+    >>> dc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if some other hash is recognized
     False
 
-    >>> dc.verify("password", 'JQMuyS6H.AGMo') #verify password
+    >>> dc.verify("password", 'JQMuyS6H.AGMo') #verify correct password
     True
-    >>> dc.verify("secret", 'JQMuyS6H.AGMo') #verify password
+    >>> dc.verify("secret", 'JQMuyS6H.AGMo') #verify incorrect password
     False
 
 Functions
@@ -64,7 +62,7 @@ The checksum is formed by a modified version of the DES cipher in encrypt mode:
 * First, the lower 7 bits of the first 8 characters of the password are used
   to form a 56-bit DES key. The remainder of the password is ignored.
 
-* The checksum is then generated by recursively performing 25 rounds of DES encryption
+* The checksum is then generated by recursively performing 25 rounds of DES encryption,
   starting with a null input block. The 12 bits of salt are used to mutate
   the action performed by each block of the DES key schedule (see the source
   of :func:`~passlib.utils.des.mdes_encrypt_int_block` for details).
diff --git a/docs/lib/passlib.hash.ext_des_crypt.rst b/docs/lib/passlib.hash.ext_des_crypt.rst
index 7b3911e..8c611a6 100644
--- a/docs/lib/passlib.hash.ext_des_crypt.rst
+++ b/docs/lib/passlib.hash.ext_des_crypt.rst
@@ -1,9 +1,9 @@
 =================================================================================
-:mod:`passlib.hash.ext_des_crypt` - BSDi Extended DES Crypt
+:mod:`passlib.hash.ext_des_crypt` - Extended DES Crypt
 =================================================================================
 
 .. module:: passlib.hash.ext_des_crypt
-    :synopsis: BSDi Extended Unix (DES) Crypt
+    :synopsis: Extended Unix (DES) Crypt
 
 This algorithm was developed by BSDi for their BSD/OS distribution.
 It's based on :mod:`~passlib.hash.des_crypt`, and contains a larger
@@ -16,6 +16,10 @@ Usage
 Aside from differences in format and salt size,
 ext-des-crypt usage is exactly the same as :mod:`~passlib.hash.des_crypt`.
 
+.. todo::
+
+    this needs separate usage, showing rounds parameter.
+
 Functions
 =========
 .. autofunction:: genconfig
diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst
index 333a6e1..ca55f93 100644
--- a/docs/lib/passlib.hash.md5_crypt.rst
+++ b/docs/lib/passlib.hash.md5_crypt.rst
@@ -17,9 +17,22 @@ should use a stronger scheme (eg :mod:`~passlib.hash.sha512_crypt`) if possible.
 
 Usage
 =====
-.. todo::
+This module can be used directly as follows::
 
-    write usage instructions
+    >>> from passlib.hash import md5_crypt as mc
+
+    >>> mc.encrypt("password") #generate new salt, encrypt password
+    '$1$3azHgidD$SrJPt7B.9rekpmwJwtON31'
+
+    >>> mc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if hash is recognized
+    True
+    >>> mc.identify('JQMuyS6H.AGMo') #check if some other hash is recognized
+    False
+
+    >>> mc.verify("password", '$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #verify correct password
+    True
+    >>> mc.verify("secret", '$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #verify incorrect password
+    False
 
 Functions
 =========
diff --git a/docs/lib/passlib.hash.mysql_323.rst b/docs/lib/passlib.hash.mysql_323.rst
index d2df512..9d14ea7 100644
--- a/docs/lib/passlib.hash.mysql_323.rst
+++ b/docs/lib/passlib.hash.mysql_323.rst
@@ -5,6 +5,60 @@
 .. module:: passlib.hash.mysql_323
     :synopsis: MySQL 3.2.3 password hash
 
-.. todo::
+.. warning::
 
-    write documentation
+    This algorithm is extremely weak, and should not be used
+    for any purposes besides manipulating existing Mysql 3.2.3-4.0
+    password hashes.
+
+This module implements the first of MySQL's password hash functions,
+used to store it's user account passwords. Introduced in MySQL 3.2.3
+under the function ``PASSWORD()``, this function was renamed
+to ``OLD_PASSWORD()`` under MySQL 4.1, when a newer password
+hash algorithm was introduced (see :mod:`~passlib.hash.mysql_41`).
+Lacking any sort of salt, it's simplistic algorithm amounts to
+little more than a checksum, and should not be used for *any*
+purpose but verifying existing MySQL 3.2.3 - 4.0 password hashes.
+
+Usage
+=====
+Users will most likely find the frontends provided by :mod:`passlib.mysql`
+to be more useful than accessing this module directly.
+That aside, this module can be used directly as follows::
+
+    >>> from passlib.hash import mysql_323 as mold
+
+    >>> mold.encrypt("password") #encrypt password
+    '5d2e19393cc5ef67'
+
+    >>> mold.identify('5d2e19393cc5ef67') #check if hash is recognized
+    True
+    >>> mold.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if another type of hash is recognized
+    False
+
+    >>> mold.verify("password", '5d2e19393cc5ef67') #verify correct password
+    True
+    >>> mold.verify("secret", '5d2e19393cc5ef67') #verify incorrect password
+    False
+
+Functions
+=========
+.. autofunction:: genconfig
+.. autofunction:: genhash
+.. autofunction:: encrypt
+.. autofunction:: identify
+.. autofunction:: verify
+
+Format & Algorithm
+==================
+A mysql-323 password hash consists of 16 hexidecimal digits,
+directly encoding the 64 bit checksum. MySQL always uses
+lower-case letters, and so does PassLib
+(though PassLib will recognize upper case letters as well).
+The algorithm used is extremely simplistic, for details,
+see the source implementation linked to below.
+
+References
+==========
+* `<http://dev.mysql.com/doc/refman/4.1/en/password-hashing.html>`_ - mysql document describing transition
+* `<http://djangosnippets.org/snippets/1508/>`_ - source of implementation used by passlib
diff --git a/docs/lib/passlib.hash.mysql_41.rst b/docs/lib/passlib.hash.mysql_41.rst
index 6b8ba2e..ab8a6d5 100644
--- a/docs/lib/passlib.hash.mysql_41.rst
+++ b/docs/lib/passlib.hash.mysql_41.rst
@@ -5,6 +5,43 @@
 .. module:: passlib.hash.mysql_41
     :synopsis: MySQL 4.1 password hash
 
-.. todo::
+.. warning::
 
-    write documentation
+    This algorithm is extremely weak, and should not be used
+    for any purposes besides manipulating existing Mysql 4.1+
+    password hashes.
+
+This module implements the second of MySQL's password hash functions,
+used to store it's user account passwords. Introduced in MySQL 4.1.1
+under the function ``PASSWORD()``, it replaced the previous
+algorithm (:mod:`~passlib.hash.mysql_323`) as the default
+used by MySQL, and is still in active use under MySQL 5.
+Lacking any sort of salt, and using only 2 rounds
+of the common SHA1 message digest, it's not very secure,
+and should not be used for *any*
+purpose but verifying existing MySQL 4.1+ password hashes.
+
+Usage
+=====
+Users will most likely find the frontends provided by :mod:`passlib.mysql`
+to be more useful than accessing this module directly.
+That aside, this module can be used directly in the same manner
+as :mod:`~passlib.hash.mysql_323`.
+
+Functions
+=========
+.. autofunction:: genconfig
+.. autofunction:: genhash
+.. autofunction:: encrypt
+.. autofunction:: identify
+.. autofunction:: verify
+
+Format & Algorithm
+==================
+A mysql-41 password hash consists of an asterisk ``*`` followed
+by 40 hexidecimal digits, directly encoding the 160 bit checksum.
+An example hash (of ``password``) is ``*2470C0C06DEE42FD1618BB99005ADCA2EC9D1E19``.
+MySQL always uses upper-case letters,
+and so does PassLib (though PassLib will recognize lower-case letters as well).
+The checksum is calculated simply, as the SHA1 hash of the SHA1 hash of the password,
+which is then encoded into hexidecimal.
diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst
index 7f415f1..a9bbd36 100644
--- a/docs/lib/passlib.hash.postgres_md5.rst
+++ b/docs/lib/passlib.hash.postgres_md5.rst
@@ -1,33 +1,61 @@
 ==================================================================
-:mod:`passlib.hash.postgres_md5` - Postgres MD5 password hash
+:mod:`passlib.hash.postgres_md5` - PostgreSQL MD5 password hash
 ==================================================================
 
 .. module:: passlib.hash.postgres_md5
-    :synopsis: Postgres MD5 password hash
+    :synopsis: PostgreSQL MD5 password hash
 
-Stats: 512 bit checksum, username used as salt
-
-This implements the md5-based hash algorithm used by Postgres to store
-passwords in the pg_shadow table.
+.. warning::
 
-This algorithm shouldn't be used for any purpose besides Postgres interaction,
-it's a weak unsalted algorithm which could be attacked with a rainbow table
-built against common user names.
+    This hash is not secure, and should not be used for any purposes
+    besides manipulating existing PostgreSQL password hashes.
 
-.. warning::
-    This algorithm is slightly different from most of the others,
-    in that both encrypt() and verify() require you pass in
-    the name of the user account via the required 'user' keyword,
-    since postgres uses this in place of a salt :(
+This module implemented the md5-based hash algorithm used by PostgreSQL to store
+it's user account passwords. This scheme was introduced in PostgreSQL 7.2;
+prior to this PostgreSQL stored it's password in plain text. This scheme
+uses the username as a salt value, and so it only technically salted,
+as common user account names can be predicted and precalculated. Because
+of this, it's not suitable for *any* use besides manipulating existing
+PostgreSQL account passwords.
 
-Usage Example::
+Usage
+=====
+Users will most likely find the frontend provided by :mod:`passlib.postgres`
+to be more useful than accessing this module directly.
+That aside, this module can be used directly as follows::
 
     >>> from passlib.hash import postgres_md5 as pm
-    >>> pm.encrypt("mypass", user="postgres")
-    'md55fba2ea04fd36069d2574ea71c8efe9d'
-    >>> pm.verify("mypass", 'md55fba2ea04fd36069d2574ea71c8efe9d', user="postgres")
-    True
 
-.. todo::
+    >>> pm.encrypt("password", "username") #encrypt password using specified username
+    'md55a231fcdb710d73268c4f44283487ba2'
 
-    find references
+    >>> pm.identify('md55a231fcdb710d73268c4f44283487ba2') #check if hash is recognized
+    True
+    >>> pm.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if some other hash is recognized
+    False
+
+    >>> pm.verify("password", 'md55a231fcdb710d73268c4f44283487ba2', "username") #verify correct password
+    True
+    >>> pm.verify("password", 'md55a231fcdb710d73268c4f44283487ba2', "somebody") #verify correct password w/ wrong username
+    False
+    >>> pm.verify("password", 'md55a231fcdb710d73268c4f44283487ba2', "username") #verify incorrect password
+    False
+
+Functions
+=========
+.. autofunction:: genconfig
+.. autofunction:: genhash
+.. autofunction:: encrypt
+.. autofunction:: identify
+.. autofunction:: verify
+
+Format & Algorithm
+==================
+Postgres-MD5 hashes all have the format ``md5{checksum}``,
+where ``{checksum}`` is 32 hexidecimal digits, encoding a 128-bit checksum.
+This checksum is the MD5 message digest of the password concatenated with the username.
+
+References
+==========
+* `<http://archives.postgresql.org/pgsql-hackers/2001-06/msg00952.php>`_ - discussion leading up to design of algorithm
+* `<http://archives.postgresql.org/pgsql-php/2003-01/msg00021.php>`_ - message explaining postgres md5 hash algorithm
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index 91ae6e6..5b59854 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -54,7 +54,6 @@ the modular crypt format.
 
     These aren't fully implemented / tested yet:
 
-    * :mod:`~passlib.hash.nthash` - modular-crypt-format encoding of legacy NTHASH algorithm
     * :mod:`~passlib.hash.sun_md5_crypt` - MD5-based crypt descendant used by Solaris 10 (NOT related to md5-crypt above).
 
 Other Schemes
diff --git a/docs/notes.txt b/docs/notes.txt
index fcbfa01..3e93e8a 100644
--- a/docs/notes.txt
+++ b/docs/notes.txt
@@ -182,6 +182,9 @@ references for hashes & passwords
 http://chargen.matasano.com/chargen/2007/9/7/enough-with-the-rainbow-tables-what-you-need-to-know-about-s.html
 http://www.openwall.com/john/interviews/SF-20060222-p3
 
+oracle -
+http://www.notesbit.com/index.php/scripts-oracle/oracle-11g-new-password-algorithm-is-revealed-by-seclistsorg/
+
 ===========
 scrpyt
 http://www.tarsnap.com/scrypt.html