minor doc tweaks

3 files changed, 37 insertions, 35 deletions

diff --git a/docs/lib/passlib.hash.mysql323.rst b/docs/lib/passlib.hash.mysql323.rst
index 2f4f366..1a18372 100644
--- a/docs/lib/passlib.hash.mysql323.rst
+++ b/docs/lib/passlib.hash.mysql323.rst
@@ -61,4 +61,5 @@ this is not secure, and should not be used for *any* purpose but verifying exist
 References
 ==========
 .. [#f1] Source of implementation used by passlib - `<http://djangosnippets.org/snippets/1508/>`_
+
 * Mysql document describing transition - `<http://dev.mysql.com/doc/refman/4.1/en/password-hashing.html>`_
diff --git a/docs/lib/passlib.hash.nthash.rst b/docs/lib/passlib.hash.nthash.rst
index c9bff2d..fa28cfb 100644
--- a/docs/lib/passlib.hash.nthash.rst
+++ b/docs/lib/passlib.hash.nthash.rst
@@ -26,6 +26,7 @@ Interface
 =========
 .. autoclass:: nthash
 
+
 ..
 
     In addition to the normal password hash api, this module also exposes
diff --git a/docs/lib/passlib.hash.sun_md5_crypt.rst b/docs/lib/passlib.hash.sun_md5_crypt.rst
index fc1caa7..6f02dc7 100644
--- a/docs/lib/passlib.hash.sun_md5_crypt.rst
+++ b/docs/lib/passlib.hash.sun_md5_crypt.rst
@@ -45,13 +45,6 @@ An alternate format, ``$md5${salt}${checksum}`` is used when the rounds value is
     Solaris seems to deviate from the :ref:`modular-crypt-format` in that
     it considers ``$`` *or* ``,`` to indicate the end of the identifier.
 
-.. warning::
-
-    One of the remaining issues with this implementation is that some
-    existing sun-md5-crypt hashes found on the web use a ``$`` in place of the ``,``.
-    It is unclear whether this is an accepted alternate format or just a typo,
-    nor whether this is supposed to affect the checksum in the resulting hash string.
-
 .. rst-class:: html-toggle
 
 Algorithm
@@ -62,29 +55,22 @@ by one of the creators).
 1. Given a password, the number of rounds, and a salt string.
 
 2. an initial MD5 digest is created from the concatentation of the password,
-  and the configuration string (using the format ``$md5,rounds={rounds}${salt}``).
+   and the configuration string (using the format ``$md5,rounds={rounds}${salt}``).
 
 3. for rounds+4096 iterations, a new digest is created:
     - ``MuffetCoinToss(rounds, previous digest)`` is called, resulting in a 0 or 1.
-    - if a 1, the next digest is the MD5 of: the last digest concatenated with a constant
+    - if it results in a 1, the next digest is the MD5 of: the previous digest, concatenated with a constant
       data string, along with the current iteration number as an ascii string.
-    - if a 0, the same as 1, except that magic constant data is not included.
+    - otherwise, the same operation is performed, except that magic constant data is not included.
 
-4. The final checksum is then encoded into :mod:`hash64 <~passlib.hash.h64>` using the same
-  transposed byte order that :class:`~passlib.hash.md5_crypt` uses.
+4. The final checksum is then encoded into :mod:`hash64 <passlib.hash.h64>` format using the same
+   transposed byte order that :class:`~passlib.hash.md5_crypt` uses.
 
-The constant data string is referenced above is a 1517 byte ascii string... an excerpt from Hamlet,
+The constant data string is referenced above is a 1517 byte ascii string... an excerpt from Hamlet [#f2]_,
 starting with ``To be, or not to be...`` and ending with ``...all my sins remember'd.\n``,
-with a null character appended (exact Project Gutenberg source linked to below).
+with a null character appended.
 
-.. warning::
-
-    Note that this has a weakness in that the per-round operation appends data
-    which is known to the attacker, the coin flip algorithm only serves to
-    frustrate brute-force attacks. Reversing this hash is dependant
-    on MD5's general pre-image attack resistance (which is currently theoretically vulnerable).
-
-Muffer Coin Toss
+Muffet Coin Toss
 ----------------
 The Muffet Coin Toss algorithm is as follows:
 Given the current round number, and a 16 byte MD5 digest, it returns a 0 or 1,
@@ -95,31 +81,39 @@ using the following formula:
     All references below to a specific bit of the digest should be interpreted mod 128.
     All references below to a specific byte of the digest should be interpreted mod 16.
 
-the coinflip generates two 8 bit integers ``X`` & ``Y`` as follows:
-
-1. ``X`` is generated from the following formula:
+1. A 8-bit integer ``X`` is generated from the following formula:
+   for each ``i`` in 0..7 inclusive:
 
-  for each ``i`` in 0..7 inclusive:
+    * let ``A`` be the ``i``'th byte of the digest, as an 8-bit int.
+    * let ``B`` be the ``i+3``'th byte of the digest, as an 8-bit int.
 
-    a. let ``A`` be the ``i``'th byte of the digest, as an 8-bit int.
-    b. let ``B`` be the ``i+3``'th byte of the digest, as an 8-bit int.
+    * let ``R`` be ``A`` shifted right by ``B % 5`` bits.
 
-    c. let ``R`` be ``A`` shifted right by ``B % 5`` bits.
+    * let ``V`` be the ``R``'th byte of the digest.
+    * if the ``A % 8``'th bit of ``B`` is 1, divide ``V`` by 2.
 
-    d. let ``V`` be the ``R``'th byte of the digest.
-    e. if the ``A % 8``'th bit of ``B`` is 1, divide ``V`` by 2.
+    * use the ``V``'th bit of the digest as the ``i``'th bit of ``X``.
 
-    f. use the ``V``'th bit of the digest as the ``i``'th bit of ``X``.
-
-2. ``Y`` is generated exactly the same as ``X``, except that
+2. Another 8-bit integer, ``Y``, is generated exactly the same as ``X``, except that
    ``A`` is the ``i+8``'th byte of the digest,
    and ``B`` is the ``i+11``'th byte of the digest.
 
 3. if bit ``round`` of the digest is 1, ``X`` is divided by 2.
+
 4. if bit ``round+64`` of the digest is 1, ``Y`` is divided by 2.
 
 5. the final result is ``X``'th bit of the digest XORed against ``Y``'th bit of the digest.
 
+..
+    todo: should review / verify this --
+
+    Security Issues
+    ===============
+    Note that this has a weakness in that the per-round operation appends data
+    which is known to the attacker, the coin flip algorithm only serves to
+    frustrate brute-force attacks. Reversing this hash is dependant
+    on MD5's general pre-image attack resistance (which is currently theoretically vulnerable).
+
 Deviations
 ==========
 Passlib's implementation of Sun-MD5-Crypt deviates from the official implementation
@@ -142,7 +136,13 @@ Since Passlib's pure python implmentation was written based on the algorithm
 description above, and has not been properly tested against a reference implementation,
 it may have other bugs and deviations from the correct behavior.
 
+* One of the remaining issues with this implementation is that some
+  existing sun-md5-crypt hashes found on the web use a ``$`` in place of the ``,``.
+  It is unclear whether this is an accepted alternate format or just a typo,
+  nor whether this is supposed to affect the checksum in the resulting hash string.
+
 References
 ==========
 * Overview of & motivations for the algorithm - `<http://dropsafe.crypticide.com/article/1389>`_
-* The source of Hamlet's speech, used byte-for-byte as the constant data - `<http://www.ibiblio.org/pub/docs/books/gutenberg/etext98/2ws2610.txt>`_
+
+.. [#f2] The source of Hamlet's speech, used byte-for-byte as the constant data - `<http://www.ibiblio.org/pub/docs/books/gutenberg/etext98/2ws2610.txt>`_