added example hashes to scram documentation, other doc tweaks

2 files changed, 45 insertions, 38 deletions

diff --git a/docs/lib/passlib.hash.scram.rst b/docs/lib/passlib.hash.scram.rst
index 0a22c93..fff87bf 100644
--- a/docs/lib/passlib.hash.scram.rst
+++ b/docs/lib/passlib.hash.scram.rst
@@ -34,16 +34,16 @@ This class can be used like any other Passlib hash, as follows::
 
     >>> #generate new salt, encrypt password against default list of algorithms
     >>> h = scram.encrypt("password")
-    >>> h
-    '$scram$40000$xxxxxx$sha-1=..............................,\
-    sha-256=........................................,\
-    sha-512=.........................................'
+    >>> h # (output split over multiple lines for readability)
+    '$scram$6400$.Z/znnNOKWUsBaCU$sha-1=cRseQyJpnuPGn3e6d6u6JdJWk.0,sha-256=5G\
+    cjEbRaUIIci1r6NAMdI9OPZbxl9S5CFR6la9CHXYc,sha-512=.DHbIm82ajXbFR196Y.9Ttbs\
+    gzvGjbMeuWCtKve8TPjRMNoZK9EGyHQ6y0lW9OtWdHZrDZbBUhB9ou./VI2mlw'
 
     >>> #same, but with explict number of rounds
-    >>> scram.encrypt("password", rounds=10000)
-    '$scram$40000$xxxxxx$sha-1=..............................,\
-    sha-256=........................................,\
-    sha-512=.........................................'
+    >>> scram.encrypt("password", rounds=8000)
+    '$scram$8000$Y0zp/R/DeO89h/De$sha-1=eE8dq1f1P1hZm21lfzsr3CMbiEA,sha-256=Nf\
+    kaDFMzn/yHr/HTv7KEFZqaONo6psRu5LBBFLEbZ.o,sha-512=XnGG11X.J2VGSG1qTbkR3FVr\
+    9j5JwsnV5Fd094uuC.GtVDE087m8e7rGoiVEgXnduL48B2fPsUD9grBjURjkiA'
 
     >>> #check if hash is recognized
     >>> scram.identify(h)
@@ -63,69 +63,76 @@ for SCRAM-specific actions::
 
     >>> from passlib.hash import scram
     >>> # generate new salt, encrypt password against default list of algorithms
-    >>> h = scram.encrypt("password")
-    >>> h
-    '$scram$40000$xxxxxx$sha-1=..............................,\
-    sha-256=........................................,\
-    sha-512=.........................................'
+    >>> scram.encrypt("password")
+    '$scram$6400$.Z/znnNOKWUsBaCU$sha-1=cRseQyJpnuPGn3e6d6u6JdJWk.0,sha-256=5G\
+    cjEbRaUIIci1r6NAMdI9OPZbxl9S5CFR6la9CHXYc,sha-512=.DHbIm82ajXbFR196Y.9Ttbs\
+    gzvGjbMeuWCtKve8TPjRMNoZK9EGyHQ6y0lW9OtWdHZrDZbBUhB9ou./VI2mlw'
 
     >>> # generate new salt, encrypt password against specific list of algorithms
     >>> # and choose explicit number of rounds
     >>> h = scram.encrypt("password", rounds=1000, algs="sha-1,sha-256,md5")
     >>> h
-    '$scram$40000$xxxxxx$sha-1=..............................,\
-    sha-256=........................................,\
-    md5=.........................................'
+    '$scram$1000$RsgZo7T2/l8rBUBI$md5=iKsH555d3ctn795Za4S7bQ,sha-1=dRcE2AUjALLF\
+    tX5DstdLCXZ9Afw,sha-256=WYE/LF7OntriUUdFXIrYE19OY2yL0N5qsQmdPNFn7JE'
 
     >>> # given a scram hash, retrieve the information SCRAM needs
     >>> # to authenticate using a specific mechanism -
     >>> # returns salt, rounds, digest
-    >>> scram.extact_digest_info("sha-1")
-    (b"xxxxxx", 400000, b".................")
+    >>> scram.extact_digest_info(h, "sha-1")
+    ('F\xc8\x19\xa3\xb4\xf6\xfe_+\x05@H',
+     1000,
+     'u\x17\x04\xd8\x05#\x00\xb2\xc5\xb5~C\xb2\xd7K\tv}\x01\xfc')
 
     >>> # given a scram hash, return list of digest algs present
     >>> scram.extract_digest_algs(h)
-    ["sha-1","sha-256","md5"]
+    ["md5", "sha-1", "sha-256"]
 
-    >>> # and a standalone helper that can calculated the SaltedPassword
-    >>> # portion of the SCRAM protocol.
-    >>> scram.derive_digest("password", b'xxxxx', 40000, 'sha-1')
-    b'..............................'
+    >>> # and a standalone helper that can calculate the SaltedPassword
+    >>> # portion of the SCRAM protocol, taking care of SASLPrep as well.
+    >>> scram.derive_digest("password", b'\x01\x02\x03', 1000, "sha-1")
+    b'k\x086vg\xb3\xfciz\xb4\xb4\xe2JRZ\xaet\xe4`\xe7'
 
 Interface
 =========
 .. autoclass:: scram(algs=None, salt=None, rounds=None, strict=False)
 
+.. rst-class:: html-toggle
+
 Format & Algorithm
 ==================
-An example scram hash (of the string ``password``) is:
+An example scram hash (of the string ``password``) is::
 
-    ``$6$rounds=40000$JvTuqzqw9bQ8iBl6$SxklIkW4gz00LvuOsKRCfNEllLciOqY/FSAwODHon45YTJEozmy.QAWiyVpuiq7XMTUMWbIWWEuQytdHkigcN/``.
+    $scram$6400$.Z/znnNOKWUsBaCU$sha-1=cRseQyJpnuPGn3e6d6u6JdJWk.0,sha-256=5G
+    cjEbRaUIIci1r6NAMdI9OPZbxl9S5CFR6la9CHXYc,sha-512=.DHbIm82ajXbFR196Y.9Ttb
+    sgzvGjbMeuWCtKve8TPjRMNoZK9EGyHQ6y0lW9OtWdHZrDZbBUhB9ou./VI2mlw'
 
-An scram hash string has the format :samp:`$scram${rounds}${salt}${alg}={digest}{,...}`, where:
+An scram hash string has the format :samp:`$scram${rounds}${salt}${alg1}={digest1},{alg2}={digest2},{...}`, where:
 
 * ``$scram$`` is the prefix used to identify Passlib scram hashes,
   following the :ref:`modular-crypt-format`
 
-* :samp:`{rounds}` is the decimal number of rounds to use (40000 in the example).
+* :samp:`{rounds}` is the decimal number of rounds to use (6400 in the example).
 
-* :samp:`{salt}` is a base64 encoded salt string (``JvTuqzqw9bQ8iBl6`` in the example).
+* :samp:`{salt}` is a base64 encoded salt string (``.Z/znnNOKWUsBaCU`` in the example).
 
 * :samp:`{alg}` is a lowercase IANA hash function name, which should
   match the digest in the SCRAM mechanism name.
 
 * :samp:`{digest}` is a base64 digest for the specific algorithm.
+  Digests for ``sha-1``, ``sha-256``, and ``sha-512`` are present in the example.
 
-* There will be one or more `{alg}={digest}` pairs, separated by a comma;
+* There will be one or more :samp:`{alg}={digest}` pairs, separated by a comma;
   per the SCRAM specification, the algorithm ``sha-1`` should always be present.
 
 There is also an alternate format :samp:`$scram${rounds}${salt}${alg}{,...}`
 which is used to represent a configuration string that doesn't contain
 any digests.
 
-The algorithm used to calculate each digest is
-``pbkdf2(salsprep(password).encode("utf-8"), salt, rounds, -1, alg)``,
-as laid out in the SCRAM specification. All digests
+The algorithm used to calculate each digest is::
+
+    pbkdf2(salsprep(password).encode("utf-8"), salt, rounds, -1, alg)
+
+...as laid out in the SCRAM specification. All digests
 verify against the same password, or the hash should be considered malformed.
 
 .. note::
@@ -133,4 +140,4 @@ verify against the same password, or the hash should be considered malformed.
     This format is similar in spirit to the LDAP storage format for SCRAM hashes,
     defined in :rfc:`5803`, except that it encodes everything into a single
     string, and does not have any storage requirements (outside of the ability
-    to store 1024+ character ascii strings).
+    to store 512+ character ascii strings).
diff --git a/docs/modular_crypt_format.rst b/docs/modular_crypt_format.rst
index 5db4905..bc96ffe 100644
--- a/docs/modular_crypt_format.rst
+++ b/docs/modular_crypt_format.rst
@@ -149,20 +149,20 @@ Scheme                                      Prefix              Primary Use (if
 =========================================== =================== ===========================
 :class:`~passlib.hash.apr_md5_crypt`        ``$apr1$``          Apache htdigest files
 :class:`~passlib.hash.phpass`               ``$P$``, ``$H$``    PHPass-based applications
-:class:`~passlib.hash.pbkdf2_sha1`          ``$pbkdf2$``
-:class:`~passlib.hash.pbkdf2_sha256`        ``$pbkdf2-sha256$``
-:class:`~passlib.hash.pbkdf2_sha512`        ``$pbkdf2-sha512$``
+:class:`~passlib.hash.pbkdf2_sha1`          ``$pbkdf2$``        Passlib-specific
+:class:`~passlib.hash.pbkdf2_sha256`        ``$pbkdf2-sha256$`` Passlib-specific
+:class:`~passlib.hash.pbkdf2_sha512`        ``$pbkdf2-sha512$`` Passlib-specific
+:class:`~passlib.hash.scram`                ``$scram$``         Passlib-specific
 :class:`~passlib.hash.cta_pbkdf2_sha1`      ``$p5k2$`` [#cta]_
 :class:`~passlib.hash.dlitz_pbkdf2_sha1`    ``$p5k2$`` [#cta]_
 =========================================== =================== ===========================
 
 .. rubric:: Footnotes
 
-.. [#gae] As of 2011-08-19, Google App Engine's :mod:`crypt` implementation 
+.. [#gae] As of 2011-08-19, Google App Engine's :mod:`crypt` implementation
           appears to provide hash support matching that of a typical Linux system.
 
 .. [#cta] :class:`!cta_pbkdf2_sha1` and :class:`!dlitz_pbkdf2_sha1` both use
           the same identifier. They can be distinguished
           by the fact that cta hashes will always end in ``=``, while dlitz
           hashes contain no ``=`` at all.
-