added Window's DCC hashes (aka mscache / mscash) version 1 & 2

3 files changed, 206 insertions, 2 deletions

diff --git a/docs/lib/passlib.hash.msdcc.rst b/docs/lib/passlib.hash.msdcc.rst
new file mode 100644
index 0000000..737952d
--- /dev/null
+++ b/docs/lib/passlib.hash.msdcc.rst
@@ -0,0 +1,101 @@
+.. index:: msdcc; Windows; Domain Cached Credentials
+
+======================================================================
+:class:`passlib.hash.msdcc` - Windows' Domain Cached Credentials
+======================================================================
+
+.. currentmodule:: passlib.hash
+
+This class implements the DCC (Domain Cached Credentials) hash, used
+by Windows to cache and verify remote credentials when the relevant
+server is unavailable. It is known by a number of other names,
+including "mscache" and "mscash" (Microsoft CAched haSH). Security wise
+it is not particularly strong, as it's little more than :doc:`nthash <passlib.hash.nthash>`
+salted with a username. It was replaced by :doc:`msdcc2 <passlib.hash.msdcc2>`
+in Windows Vista.
+
+.. warning::
+
+    This hash is not very secure, and should mainly be used to verify
+    existing cached credentials.
+
+.. seealso::
+
+    :doc:`passlib.hash.msdcc2`
+
+Usage
+=====
+This class can be used directly as follows::
+
+    >>> from passlib.hash import msdcc
+
+    >>> # encrypt password using specified username
+    >>> h = msdcc.encrypt("password", "Administrator")
+    >>> h
+    '25fd08fa89795ed54207e6e8442a6ca0'
+
+    >>> #verify correct password
+    >>> msdcc.verify("password", h, "Administrator")
+    True
+    >>> #verify correct password w/ wrong username
+    >>> msdcc.verify("password", h, "User")
+    False
+    >>> #verify incorrect password
+    >>> msdcc.verify("letmein", h, "Administrator")
+    False
+
+    >>> # check if hash may belong to msdcc
+    >>> msdcc.identify(h)
+    True
+    >>> # check if foreign hash belongs to msdcc
+    >>> msdcc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31')
+    False
+
+Interface
+=========
+.. autoclass:: msdcc()
+
+.. rst-class:: html-toggle
+
+Format & Algorithm
+==================
+Much like :class:`!lmhash` and :class:`!nthash`, MS DCC hashes
+consists of a 16 byte digest, usually encoded as 32 hexidecimal characters.
+An example hash (of ``"password"`` with the account ``"Administrator"``) is
+``25fd08fa89795ed54207e6e8442a6ca0``.
+
+The digest is calculated as follows:
+
+1. The password is encoded using ``UTF-16-LE``.
+2. The MD4 digest of step 1 is calculated.
+   (The result of this step is identical to the :class:`~passlib.hash.nthash`
+   of the password).
+3. The unicode username is converted to lowercase,
+   and encoded using ``UTF-16-LE``.
+   This should be just the plain username (e.g. ``User``
+   not ``SOMEDOMAIN\\User``)
+4. The username from step 3 is appended to the
+   digest from step 2; and the MD4 digest of the result
+   is calculated.
+5. The result of step 4 is encoded into hexidecimal,
+   this is the DCC hash.
+
+Security Issues
+===============
+This algorithm is should not be used for any purpose besides
+manipulating existing DCC v1 hashes, due to the following flaws:
+
+* It's use of the username as a salt value (and lower-case at that),
+  means that common usernames (eg ``Administrator``) will occur
+  more frequently as salts, weakening the effectiveness of the salt in
+  foiling pre-computed tables.
+
+* The MD4 message digest has been severely compromised by collision and
+  preimage attacks.
+
+* Efficient brute-force attacks on MD4 exist.
+
+.. rubric:: Footnotes
+
+.. [#] Description of DCC v1 algorithm -
+       `<http://openwall.info/wiki/john/MSCash>`_
diff --git a/docs/lib/passlib.hash.msdcc2.rst b/docs/lib/passlib.hash.msdcc2.rst
new file mode 100644
index 0000000..3ff41e6
--- /dev/null
+++ b/docs/lib/passlib.hash.msdcc2.rst
@@ -0,0 +1,91 @@
+.. index:: msdcc; Windows; Domain Cached Credentials v2
+
+======================================================================
+:class:`passlib.hash.msdcc2` - Windows' Domain Cached Credentials v2
+======================================================================
+
+.. currentmodule:: passlib.hash
+
+This class implements the DCC2 (Domain Cached Credentials version 2) hash, used
+by Windows Vista and newer to cache and verify remote credentials when the relevant
+server is unavailable. It is known by a number of other names,
+including "mscache2" and "mscash2" (Microsoft CAched haSH). It replaces
+the weaker :doc:`msdcc (v1)<passlib.hash.msdcc>` hash used by previous releases
+of Windows. Security wise it is not particularly weak, but due to it's
+use of the username as a salt, it should probably not be used for anything
+but verifying existing cached credentials.
+
+Usage
+=====
+This class can be used directly as follows::
+
+    >>> from passlib.hash import msdcc2
+
+    >>> # encrypt password using specified username
+    >>> h = msdcc2.encrypt("password", "Administrator")
+    >>> h
+    '4c253e4b65c007a8cd683ea57bc43c76'
+
+    >>> #verify correct password
+    >>> msdcc2.verify("password", h, "Administrator")
+    True
+    >>> #verify correct password w/ wrong username
+    >>> msdcc2.verify("password", h, "User")
+    False
+    >>> #verify incorrect password
+    >>> msdcc2.verify("letmein", h, "Administrator")
+    False
+
+    >>> # check if hash may belong to msdcc
+    >>> msdcc2.identify(h)
+    True
+    >>> # check if foreign hash belongs to msdcc
+    >>> msdcc2.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31')
+    False
+
+Interface
+=========
+.. autoclass:: msdcc2()
+
+.. rst-class:: html-toggle
+
+Format & Algorithm
+==================
+Much like :class:`!lmhash`, :class:`!nthash`, and :class:`!msdcc`,
+MS DCC v2 hashes consists of a 16 byte digest, usually encoded as 32
+hexidecimal characters. An example hash (of ``"password"`` with the
+account ``"Administrator"``) is ``4c253e4b65c007a8cd683ea57bc43c76``.
+
+The digest is calculated as follows:
+
+1. The password is encoded using ``UTF-16-LE``.
+2. The MD4 digest of step 1 is calculated.
+   (The result of this is identical to the :class:`~passlib.hash.nthash`
+   digest of the password).
+3. The unicode username is converted to lowercase,
+   and encoded using ``UTF-16-LE``.
+   This should be just the plain username (e.g. ``User``
+   not ``SOMEDOMAIN\\User``)
+4. The username from step 3 is appended to the
+   digest from step 2; and the MD4 digest of the result
+   is calculated (The result of this is identicial to the
+   :class:`~passlib.hash.msdcc` digest).
+5. :func:`PBKDF2-HMAC-SHA1 <passlib.utils.pbkdf2.pbkdf2>` is then invoked,
+   using the result of step 4 as the secret, the username from step 3 as
+   the salt, 10240 rounds, and resulting in a 16 byte digest.
+6. The result of step 5 is encoded into hexidecimal;
+   this is the DCC2 hash.
+
+Security Issues
+===============
+This hash is essentially DCC v1 with a fixed-round PBKDF2 function
+wrapped around it. The number of rounds of PBKDF2 is currently
+sufficient to make this a semi-reasonable way to store passwords,
+but the use of the lowercase username as a salt, and the fact
+that the rounds can't be increased, means this hash is not particularly
+future-proof, and should not be used for new applications.
+
+.. rubric:: Footnotes
+
+.. [#] Description of DCC v2 algorithm -
+       `<http://openwall.info/wiki/john/MSCash2>`_
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index fa73060..d06fed1 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -183,6 +183,20 @@ not seen outside those specific contexts:
 
 .. _other-hashes:
 
+Windows Hashes
+==============
+The following hashes are used in various places by Microsoft Windows.
+As they were designed for "internal" use, they generally contain
+no identifying markers, identifying them is pretty much context-dependant.
+
+.. toctree::
+    :maxdepth: 1
+
+    passlib.hash.lmhash
+    passlib.hash.nthash
+    passlib.hash.msdcc
+    passlib.hash.msdcc2
+
 Other Hashes
 ============
 The following schemes are used in various contexts,
@@ -192,8 +206,6 @@ in one of the above categories:
 .. toctree::
     :maxdepth: 1
 
-    passlib.hash.lmhash
-    passlib.hash.nthash
     passlib.hash.cisco_pix
 
 * *Cisco "Type 5" hashes* - see :doc:`md5_crypt <passlib.hash.md5_crypt>`