various documentation updates

8 files changed, 33 insertions, 24 deletions

diff --git a/docs/lib/passlib.hash.bsdi_crypt.rst b/docs/lib/passlib.hash.bsdi_crypt.rst
index 2ef5df0..bd2d334 100644
--- a/docs/lib/passlib.hash.bsdi_crypt.rst
+++ b/docs/lib/passlib.hash.bsdi_crypt.rst
@@ -67,7 +67,7 @@ The checksum is formed by a modified version of the DES cipher in encrypt mode:
    The salt string uses little-endian
    :func:`hash64 <passlib.utils.h64.decode_int24>` encoding.
 
-4. The password is NULL-padded on the end to the smallests non-zero multiple of 8 bytes.
+4. The password is NULL-padded on the end to the smallest non-zero multiple of 8 bytes.
 
 5. The lower 7 bits of the first 8 bytes of the password are used
    to form a 56-bit integer; with the first byte providing
@@ -81,7 +81,7 @@ The checksum is formed by a modified version of the DES cipher in encrypt mode:
     b. Step 5 is repeated for the current 8-byte block, and xored against the
        existing DES key.
 
-7. Repeated rounds of modified DES encryption are performed;
+7. Repeated rounds of (modified) DES encryption are performed;
    starting with a null input block,
    and using the 56-bit integer from step 5/6 as the DES key.
 
@@ -89,7 +89,7 @@ The checksum is formed by a modified version of the DES cipher in encrypt mode:
    by swapping bits :samp:`{i}` and :samp:`{i}+24` in the DES E-Box output
    if and only if bit :samp:`{i}` is set in the salt value.
 
-   The number of rounds to is controlled by the value decoded in step 2.
+   The number of rounds is controlled by the value decoded in step 2.
 
 8. The 64-bit result of the last round of step 7 is then
    lsb-padded with 2 zero bits.
diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst
index 4855e9a..5893da4 100644
--- a/docs/lib/passlib.hash.des_crypt.rst
+++ b/docs/lib/passlib.hash.des_crypt.rst
@@ -105,9 +105,10 @@ This implementation of des-crypt differs from others in a few ways:
 
 * Minimum salt string:
 
-  Some implementations of des-crypt allow empty and single-character salt strings.
-  However, the behavior in these cases varies wildly between implementations,
-  including errors and broken hashes.
+  Some implementations of des-crypt permit empty and single-character salt strings.
+  However, behavior in these cases varies wildly;
+  with implementations returning everything from errors
+  to incorrect hashes that never validate.
   To avoid all this, PassLib will throw an "invalid salt" if the provided
   salt string is not at least 2 characters.
 
diff --git a/docs/lib/passlib.hash.oracle10.rst b/docs/lib/passlib.hash.oracle10.rst
index d5bb113..a276a0f 100644
--- a/docs/lib/passlib.hash.oracle10.rst
+++ b/docs/lib/passlib.hash.oracle10.rst
@@ -76,7 +76,7 @@ Oracle10 hashes can be formed by the following procedure:
 Security Issues
 ===============
 This algorithm it not suitable for *any* use besides manipulating existing
-Oracle10 account passwords, due to the following flaws:
+Oracle10 account passwords, due to the following flaws [#flaws]:
 
 * It's use of the username as a salt value means that common usernames
   (eg ``system``) will occur more frequently as salts,
@@ -112,5 +112,9 @@ References
           PassLib uses ``utf-16-be``, as this is both compatible with existing test vectors
           and supports unicode input.
 
+.. [#flaws] Whitepaper analyzing flaws in this algorithm - 
+            `<http://www.isg.rhul.ac.uk/~ccid/publications/oracle_passwd.pdf>`_.
+
 .. [#] Description of Oracle10g and Oracle11g algorithms -
        `<http://www.notesbit.com/index.php/scripts-oracle/oracle-11g-new-password-algorithm-is-revealed-by-seclistsorg/>`_.
+
diff --git a/docs/lib/passlib.hash.oracle11.rst b/docs/lib/passlib.hash.oracle11.rst
index 84e6ee6..09fef12 100644
--- a/docs/lib/passlib.hash.oracle11.rst
+++ b/docs/lib/passlib.hash.oracle11.rst
@@ -44,7 +44,7 @@ Format & Algorithm
 ==================
 An example oracle11 hash (of the string ``password``) is:
 
-    ``'S:4143053633E59B4992A8EA17D2FF542C9EDEB335C886EED9C80450C1B4E6'``
+    ``S:4143053633E59B4992A8EA17D2FF542C9EDEB335C886EED9C80450C1B4E6``
 
 An oracle11 hash string has the format :samp:`S:{checksum}{salt}`, where:
 
diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst
index a87a338..64c9b3a 100644
--- a/docs/lib/passlib.hash.pbkdf2_digest.rst
+++ b/docs/lib/passlib.hash.pbkdf2_digest.rst
@@ -42,6 +42,8 @@ Interface
 
 .. autoclass:: pbkdf2_sha512()
 
+.. _mcf-pbkdf2-format:
+
 Format & Algorithm
 ==================
 An example :class:`!pbkdf2_sha256` hash (of ``password``)::
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index 4824b6a..7855ac3 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -144,8 +144,8 @@ but follow the LDAP format:
 
     passlib.hash.ldap_other
 
-* :class:`ldap_hex_md5` - Hex-encoded MD5 Digest
-* :class:`ldap_hex_sha1` - Hex-encoded SHA1 Digest
+* :class:`passlib.hash.ldap_hex_md5` - Hex-encoded MD5 Digest
+* :class:`passlib.hash.ldap_hex_sha1` - Hex-encoded SHA1 Digest
 
 .. toctree::
     :maxdepth: 1
@@ -153,7 +153,7 @@ but follow the LDAP format:
     passlib.hash.ldap_pbkdf2_digest
     passlib.hash.atlassian_pbkdf2_sha1
 
-* :class:`roundup_plaintext` - Roundup-specific LDAP Plaintext Handler
+* :class:`passlib.hash.roundup_plaintext` - Roundup-specific LDAP Plaintext Handler
 
 .. _database-hashes:
 
diff --git a/docs/lib/passlib.hash.sha512_crypt.rst b/docs/lib/passlib.hash.sha512_crypt.rst
index a5c63d5..86378ea 100644
--- a/docs/lib/passlib.hash.sha512_crypt.rst
+++ b/docs/lib/passlib.hash.sha512_crypt.rst
@@ -4,7 +4,7 @@
 
 .. currentmodule:: passlib.hash
 
-SHA-512 Crypt and SHA-256 Crypt were developed in 2008 by Ulrich Drepper
+SHA-512 Crypt and SHA-256 Crypt were developed in 2008 by Ulrich Drepper [#f1]_
 as a successor to :class:`~passlib.hash.md5_crypt`. They includes fixes
 and advancements such as variable rounds, and use of NIST-approved cryptgraphic primitives.
 SHA-256 / SHA-512 Crypt are currently the default password hash for many systems
diff --git a/docs/lib/passlib.utils.handlers.rst b/docs/lib/passlib.utils.handlers.rst
index c35a589..4670fe7 100644
--- a/docs/lib/passlib.utils.handlers.rst
+++ b/docs/lib/passlib.utils.handlers.rst
@@ -43,12 +43,12 @@ Most of the handlers built into PassLib are based around the :class:`GenericHand
 class. This class is designed under the assumption that the common
 workflow for hashes is some combination of the following:
 
-1. parse hash into constituent parts - performed by :meth:`GenericHandler.from_string`.
+1. parse hash into constituent parts - performed by :meth:`~GenericHandler.from_string`.
 2. validate constituent parts - performed by :class:`!GenericHandler`'s constructor,
-   add the normalization functions such as :meth:`norm_checksum` and :meth:`norm_salt`
+   and the normalization functions such as :meth:`~GenericHandler.norm_checksum` and :meth:`~HasSalt.norm_salt`
    which are provided by it's related mixin classes.
-3. calculate the raw checksum for a specific password - performed by :meth:`GenericHandler.calc_checksum`.
-4. assemble hash, including new checksum, into a new string - performed by :meth:`GenericHandler.to_string`.
+3. calculate the raw checksum for a specific password - performed by :meth:`~GenericHandler.calc_checksum`.
+4. assemble hash, including new checksum, into a new string - performed by :meth:`~GenericHandler.to_string`.
 
 With this in mind, :class:`!GenericHandler` provides implementations
 of most of the :ref:`password-hash-api` methods, eliminating the need
@@ -92,16 +92,18 @@ In order to use :class:`!GenericHandler`, just subclass it, and then do the foll
 
 Some additional notes:
 
-    * In addition to simple subclassing :class:`!GenericHandler`, most handlers
+    * In addition to simply subclassing :class:`!GenericHandler`, most handlers
       will also benefit from adding in some of the mixin classes
       that are designed to add features to :class:`!GenericHandler`.
       See :ref:`generic-handler-mixins` for more details.
 
-    * Most implementations will want to optimize the behavior of the default :meth:`identify` method.
-      If left alone, it will identify any hash which :meth:`from_string` does not raise :exc:`ValueError` for.
-      For faster identification purposes, subclasses may fill in the :attr:`ident` attribute
-      with the hash's identifying prefix, which :meth:`identify` will then be use instead.
-      For more complex situations, a custom implementation can be provided, though
+    * Most implementations will want to alter/override the default :meth:`~GenericHandler.identify` method.
+      By default, it returns ``True`` for all hashes that :meth:`~GenericHandler.from_string`
+      can parse without raising a :exc:`ValueError`; which is reliable, but somewhat slow.
+      For faster identification purposes, subclasses may fill in the :attr:`~GenericHandler.ident` attribute
+      with the hash's identifying prefix, which :meth:`~GenericHandler.identify` will then test for
+      instead of calling :meth:`~GenericHandler.from_string`.
+      For more complex situations, a custom implementation should be used; 
       the :class:`HasManyIdents` mixin may also be helpful.
 
     * This class does not support context kwds of any type,
@@ -140,12 +142,12 @@ The StaticHandler class
 .. index::
     pair: custom hash handler; testing
 
-.. _testing-hash-handlers:
-
 Other Constructors
 ==================
 .. autoclass:: PrefixWrapper
 
+.. _testing-hash-handlers:
+
 Testing Hash Handlers
 =====================
 Within it's unittests, Passlib provides the :class:`~passlib.tests.utils.HandlerCase` class,