renamed nthash -> bsd_nthash; added real nthash implemented

after some thought, realized the 'nthash' name should implement
the raw hash. since bsd_nthash was very rarely used, it shouldn't
present backwards incompatibility issues at this point to go
ahead and rename it.

2 files changed, 55 insertions, 30 deletions

diff --git a/docs/lib/passlib.hash.nthash.rst b/docs/lib/passlib.hash.nthash.rst
index 5bd2246..d0c4811 100644
--- a/docs/lib/passlib.hash.nthash.rst
+++ b/docs/lib/passlib.hash.nthash.rst
@@ -1,63 +1,86 @@
+.. index:: windows; nt hash
+
 ==================================================================
-:class:`passlib.hash.nthash` - Windows NT-HASH for Unix
+:class:`passlib.hash.nthash` - Windows' NT-HASH
 ==================================================================
 
 .. currentmodule:: passlib.hash
 
-This class implements the Windows NT-HASH algorithm,
-encoded in a manner compatible with the :ref:`modular-crypt-format`.
-It is found on some unix systems where the administrator has decided
-to store user passwords in a manner compatible with the SMB/CIFS protocol.
+This class implements the NT-HASH algorithm, used by Microsoft Windows NT
+and successors to store user account passwords, supplanting
+the much weaker :doc:`lmhash <passlib.hash.lmhash>` algorithm.
 
 .. warning::
 
-    This scheme is notoriously weak (since it's based on :mod:`~passlib.utils.md4`).
-    Online tables exist for quickly performing pre-image attacks on this scheme.
-    **Do not use** in new code. Stop using in old code if possible.
+    This scheme is very weak, the :mod:`~passlib.utils.md4` digest
+    it is based on has been severely compromised for many years.
+    It should be used for compatibility with existing systems;
+    **do not use** in new code.
 
 Usage
 =====
-
 This class can be used directly as follows::
 
-    >>> from passlib.hash import nthash as nt
+    >>> from passlib.hash import nthash
 
     >>> #encrypt password
-    >>> h = nt.encrypt("password")
+    >>> h = nthash.encrypt("password")
     >>> h
-    '$3$$8846f7eaee8fb117ad06bdd830b7586c'
+    '8846f7eaee8fb117ad06bdd830b7586c'
 
-    >>> nt.identify(h) #check if hash is recognized
+    >>> #check if hash is recognized
+    >>> nthash.identify(h)
     True
-    >>> nt.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if some other hash is recognized
+    >>> #check if some other hash is recognized
+    >>> nthash.identify('3azHgidD$SrJPt7B.9rekpmwJwtON31')
     False
 
-    >>> nt.verify("password", h) #verify correct password
+    >>> #verify correct password
+    >>> nthash.verify("password", h)
     True
-    >>> nt.verify("secret", h) #verify incorrect password
+    >>> #verify incorrect password
+    >>> nthash.verify("secret", h)
     False
 
 Interface
 =========
 .. autoclass:: nthash
 
-In addition to the standard methods, this class exposes the following:
+Format & Algorithm
+==================
+A nthash consists of 32 hexidecimal digits, which encode the digest.
+An example hash (of ``password``) is ``8846f7eaee8fb117ad06bdd830b7586c``.
+
+The digest is calculated by encoding the secret using ``UTF-16-LE``,
+taking the :mod:`~passlib.utils.md4` digest, and then encoding
+that as hexidecimal.
 
-.. staticmethod:: passlib.hash.nthash.raw_nthash(secret, hex=False)
+FreeBSD Variant
+===============
+For cross-compatibility, FreeBSD's :func:`!crypt` supports storing
+NTHASH digests in a manner compatible with the :ref:`modular-crypt-format`,
+to enable administrators to store user passwords in a manner compatible with
+the SMB/CIFS protocol. This is accomplished by assigning NTHASH digests the
+identifier ``$3$``, and prepending the identifier to the normal (lowercase)
+NTHASH digest. An example digest (of ``password``) is
+``$3$$8846f7eaee8fb117ad06bdd830b7586c`` (note the doubled ``$$``).
 
-    perform raw nthash calculation, returning either
-    raw digest, or as lower-case hexidecimal characters.
+.. data:: bsd_nthash
 
-Format & Algorithm
-==================
-A nthash encoded for crypt consists of :samp:`$3$${checksum}` or
-:samp:`$NT${checksum}`; where :samp:`{checksum}` is 32 hexidecimal digits
-encoding the checksum. An example hash (of ``password``) is ``$3$$8846f7eaee8fb117ad06bdd830b7586c``.
+    This object supports FreeBSD's representation of NTHASH
+    (which is compatible with the :ref:`modular-crypt-format`),
+    and follows the :ref:`password-hash-api`.
 
-The checksum is simply the :mod:`~passlib.utils.md4` digest
-of the secret using the ``UTF16-LE`` encoding, encoded in hexidecimal.
+    It has no salt and a single fixed round.
+
+    The :meth:`encrypt()` and :meth:`genconfig` methods accept no optional keywords.
 
 Security Issues
 ===============
-This algorithm should be considered *completely* broken: rainbow tables
-exist for quickly reversing this hash.
+This algorithm should be considered *completely* broken:
+
+* It has no salt.
+* The MD4 message digest has been severely compromised by collision and
+  preimage attacks.
+* Brute-force and pre-computed attacks exist targeting MD4 hashes in general,
+  and the encoding used by NTHASH in particular.
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index ae15eab..fa73060 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -90,12 +90,13 @@ they can be used compatibly along side other modular crypt format hashes.
 
     passlib.hash.apr_md5_crypt
     passlib.hash.phpass
-    passlib.hash.nthash
     passlib.hash.pbkdf2_digest
     passlib.hash.cta_pbkdf2_sha1
     passlib.hash.dlitz_pbkdf2_sha1
     passlib.hash.scram
 
+* :class:`passlib.hash.bsd_nthash` - FreeBSD's MCF-compatible :doc:`nthash <passlib.hash.nthash>` encoding
+
 Special note should be made of the fallback helper,
 which is not an actual hash scheme, but provides "disabled account"
 behavior found in many Linux & BSD password files:
@@ -192,6 +193,7 @@ in one of the above categories:
     :maxdepth: 1
 
     passlib.hash.lmhash
+    passlib.hash.nthash
     passlib.hash.cisco_pix
 
 * *Cisco "Type 5" hashes* - see :doc:`md5_crypt <passlib.hash.md5_crypt>`