more docs

3 files changed, 127 insertions, 31 deletions

diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst
index 53ccb2b..0253487 100644
--- a/docs/lib/passlib.hash.des_crypt.rst
+++ b/docs/lib/passlib.hash.des_crypt.rst
@@ -55,7 +55,7 @@ forming a hash64-encoded 64-bit integer checksum.
 A des-crypt configuration string is also accepted by this module,
 consists of only the first 2 characters, corresponding to the salt only.
 
-Example: ``JQMuyS6H.AGMo`` contains a salt ``JQ``, and a checksum ``MuyS6H.AGMo``.
+An example hash (of ``password``) is ``JQMuyS6H.AGMo``, where the salt is ``JQ``, and the checksum ``MuyS6H.AGMo``.
 
 Algorithm
 =========
@@ -73,12 +73,13 @@ The checksum is formed by a modified version of the DES cipher in encrypt mode:
 
 Deviations
 ==========
-This implement of des-crypt differs from others in a few ways:
+This implementation of des-crypt differs from others in a few ways:
 
 * Unicode strings are encoded using UTF-8 before being passed into the algorithm.
   The original des-crypt was designed for 7-bit us-ascii, so this should not
   conflict with most existing hashes. As of this writing, the authors
-  know of no specification defining the behavior in this situtation.
+  know of no specification defining the official behavior that should be used
+  in this situtation.
 
 * Some implementations (eg: linux) accept empty and single-character salt strings,
   as well as salt strings containing other characters. The behavior for these
@@ -86,12 +87,6 @@ This implement of des-crypt differs from others in a few ways:
   Lacking even a de facto standard, this implementation will throw
   a "invalid salt" ValueError for such inputs.
 
-* While passlib contains a pure-python implementation of des-crypt,
-  it will use the native crypt() implementation if possible,
-  and there may be per-OS deviations. The unit tests should catch these.
-
-  other non-standard
-
 References
 ==========
 * `<http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt>`_ - java implementation of des-crypt, used as base for pure-python implementation
diff --git a/docs/lib/passlib.hash.ext_des_crypt.rst b/docs/lib/passlib.hash.ext_des_crypt.rst
index b228e75..c166cdb 100644
--- a/docs/lib/passlib.hash.ext_des_crypt.rst
+++ b/docs/lib/passlib.hash.ext_des_crypt.rst
@@ -1,5 +1,5 @@
 =================================================================================
-:mod:`passlib.hash.ext_des_crypt` - BSDi Extended DES Crypt password hash
+:mod:`passlib.hash.ext_des_crypt` - BSDi Extended DES Crypt
 =================================================================================
 
 .. module:: passlib.hash.ext_des_crypt
@@ -12,37 +12,67 @@ it should not be used in new applications.
 
 Usage
 =====
-Aside from a slight
+Aside from differences in format and salt size,
+ext-des-crypt usage is exactly the same as :mod:`~passlib.hash.des_crypt`.
+
+.. todo::
+
+    show examples when specifying number of rounds
 
 Functions
 =========
+.. autofunction:: genconfig
+.. autofunction:: genhash
+.. autofunction:: encrypt
+.. autofunction:: identify
+.. autofunction:: verify
 
 Format
 ======
+A ext-des-crypt hash string consists of an underscore ``_``, followed
+by 20 characters, drawn from ``[0-9a-zA-Z./]``.
+The first 4 characters after the underscore form a :mod:`hash64 <passlib.utils.h64>`-encoded
+24 bit integer determining the number of rounds.
+The next 4 characters form a hash64-encoded
+24 bit integer determining the salt.
+The final 11 characters form a hash64-encoded 64-bit integer checksum.
+
+A ext-des-crypt configuration string is also accepted by this module,
+and has the same format as the hash string, but with the final 11 checksum characters.
+
+An example hash (of ``password``) is ``_EQ0.jzhSVeUyoSqLupI``, where the rounds
+are encoded in ``EQ0.`` (=10000), the salt is ``jzhS``, and the checksum
+is ``VeUyoSqLupI``.
 
 Algorithm
 =========
+The checksum is formed by a modified version of the DES cipher in encrypt mode:
 
-Deviations
-==========
+* First, the lower 7 bits of the first 8 characters of the password are used
+  to form a 56-bit DES key, as in des-crypt.
 
-References
-==========
+* Unlike des-crypt, the remainder of the password is also used. For every additional
+  8 characters in the password, the key is encrypted using a single round of DES,
+  with itself as the input block. It is then xor'ed against the lower 7 bits
+  of the next 8 characters in the password.
 
-but uses twice the salt bits,
-a variable number of rounds, and includes all  Nonetheless, by modern standards, it's not very secure,
-and should not be used in new applications.
+* The checksum is then generated by recursively performing a variable number rounds of DES encryption
+  starting with a null input block. The 24 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).
 
-This scheme does not follow the :ref:`modular-crypt-format`, instead
-is distinguished from des-crypt and other hashes by the fact that it begins
-with ``_``.
+* The rounds, salt, and checksum are then encoded according the format as described above.
 
-Implementation
-==============
-Passlib contains a pure-python implemented of this algorithm,
-based on the description found at `http://fuse4bsd.creo.hu/localcgi/man-cgi.cgi?crypt+3`_,
-as well as the documentation at `http://search.cpan.org/dist/Authen-Passphrase/lib/Authen/Passphrase/DESCrypt.pm`_.
+Deviations
+==========
+This implementation of ext-des-crypt differs from others in a few ways:
 
-.. todo::
+* Unicode strings are encoded using UTF-8 before being passed into the algorithm.
+  The original ext-des-crypt was designed for 7-bit us-ascii, so this should not
+  conflict with most existing hashes. As of this writing, the authors
+  know of no specification defining the official behavior that should be used
+  in this situtation.
 
-    write documentation
+References
+==========
+* `<http://fuse4bsd.creo.hu/localcgi/man-cgi.cgi?crypt+3>`_ - primary source used for description of ext-des-crypt format & algorithm
diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst
index c2d56ba..cea2991 100644
--- a/docs/lib/passlib.hash.md5_crypt.rst
+++ b/docs/lib/passlib.hash.md5_crypt.rst
@@ -1,12 +1,83 @@
 ==================================================================
-:mod:`passlib.hash.md5_crypt` - MD5 Crypt password hash
+:mod:`passlib.hash.md5_crypt` - MD5 Crypt
 ==================================================================
 
 .. module:: passlib.hash.md5_crypt
     :synopsis: MD5-Crypt
 
+Also known as BSD-MD5-Crypt,
+this algorithm was developed to replace the aging des-crypt crypt.
+It is supported by a wide variety of unix flavors, and is found
+in other contexts as well.
+
+Security-wise, MD5-Crypt lacks newer features,
+such as a variable number of rounds. Futhermore, the MD5 message digest
+algorithm which it's based around is considered broken,
+though pre-image attacks are currently only theoretical.
+Despite this, MD5-Crypt itself is not considered broken,
+and is still considered ok to use, though new applications
+should use a strong scheme if feasible.
+
+Usage
+=====
 .. todo::
 
-    write documentation
+    write usage instructions
+
+Functions
+=========
+.. autofunction:: genconfig
+.. autofunction:: genhash
+.. autofunction:: encrypt
+.. autofunction:: identify
+.. autofunction:: verify
+
+Format
+======
+This algorithm was created in parallel with
+the :ref:`modular-crypt-format`, and so it uses
+the identifier ``$1$`` for all of it's hashes.
+
+An md5-crypt hash string has length 26-34, with the format ``$1$<salt>$<checksum>``;
+where ``<salt>`` is 0-8 characters drawn from ``[0-9a-zA-Z./]``,
+and ``<checksum>`` is 22 characters drawn from the same set.
+
+An example hash (of ``password``) is ``$1$5pZSV9va$azfrPr6af3Fc7dLblQXVa0``.
+
+Algorithm
+=========
+The algorithm used by MD5-Crypt is convoluted,
+and is best described by examining the BSD implementation
+linked to below.
+
+It uses the MD5 message digest algorithm to generate
+various intermediate digests based on combinations
+of the secret, the salt, and some fixed constant strings.
+
+It then performs a fixed 1000 rounds of recursive digests,
+combining the secret, salt, and last digest in varying orders.
+
+The resulting checksum is a convoluted form of
+the last resulting digest, encoded in hash64.
+
+Deviations
+==========
+This implementation of md5-crypt differs from others in a few ways:
+
+* While the underlying algorithm technically allows salt strings
+  to contain any possible byte value besides ``\x00`` and ``$``,
+  this would conflict with many uses of md5-crypt, such as within
+  unix ``/etc/shadow`` files. Futhermore, most unix systems
+  will only generate salts using the standard 64 characters listed above.
+  This implementation follows along with that, by strictly limiting
+  salt strings to the known-good set, until counter-examples are found.
+
+* Unicode strings are encoded using UTF-8 before being passed into the algorithm.
+  While the algorithm accepts passwords containing any 8-bit value
+  except for ``\x00``, as of this writing, the authors
+  know of no specification defining the official behavior that should be used
+  for unicode strings.
 
-http://www.freebsd.org/cgi/cvsweb.cgi/~checkout~/src/lib/libcrypt/crypt.c?rev=1.2
+References
+==========
+* `<http://www.freebsd.org/cgi/cvsweb.cgi/~checkout~/src/lib/libcrypt/crypt.c?rev=1.2>` - primary reference used for information & implementation