1.. index:: LAN Manager hash, Windows; LAN Manager hash
2
3==================================================================
4:class:`passlib.hash.lmhash` - LanManager Hash
5==================================================================
6
7.. include:: ../_fragments/insecure_hash_warning.rst
8
9.. versionadded:: 1.6
10
11.. currentmodule:: passlib.hash
12
13This class implements the LanManager Hash (aka *LanMan* or *LM* hash).
14It was used by early versions of Microsoft Windows to store user passwords,
15until it was supplanted (though not entirely replaced) by
16the :doc:`nthash <passlib.hash.nthash>` algorithm in Windows NT.
17It continues to crop up in production due to its integral role
18in the legacy NTLM authentication protocol.
19This class can be used directly as follows::
20
21    >>> from passlib.hash import lmhash
22
23    >>> # hash password
24    >>> h = lmhash.hash("password")
25    >>> h
26    'e52cac67419a9a224a3b108f3fa6cb6d'
27
28    >>> # verify correct password
29    >>> lmhash.verify("password", h)
30    True
31    >>> # verify incorrect password
32    >>> lmhash.verify("secret", h)
33    False
34
35.. seealso:: the generic :ref:`PasswordHash usage examples <password-hash-examples>`
36
37Interface
38=========
39.. autoclass:: lmhash()
40
41Issues with Non-ASCII Characters
42--------------------------------
43Passwords containing only ``ascii`` characters should hash and compare
44correctly across all LMhash implementations. However, due to historical
45issues, no two LMhash implementations handle non-``ascii`` characters in quite
46the same way. While Passlib makes every attempt to behave as close to correct
47as possible, the meaning of "correct" is dependant on the software you are
48interoperating with. If you think you will have passwords containing
49non-``ascii`` characters, please read the `Deviations`_ section (below) for
50details about the known interoperability issues. It's a mess of codepages.
51
52.. rst-class:: html-toggle
53
54Format & Algorithm
55==================
56A LM hash consists of 32 hexadecimal digits,
57which encode the 16 byte digest. An example hash (of ``password``) is
58``e52cac67419a9a224a3b108f3fa6cb6d``.
59
60The digest is calculated as follows:
61
621. First, the password should be converted to uppercase, and encoded
63   using the "OEM Codepage" of the Windows release that the host / target
64   server is running [#cp]_.
65
66   For pure-ASCII passwords, this step can be performed
67   using the ``us-ascii`` encoding (as most OEM Codepages are ASCII-compatible).
68   However, for passwords with non-ASCII characters, this step is fraught
69   with compatibility issues and border cases (see `Deviations`_ for details).
70
712. The password is then truncated to 14 bytes,
72   or the end NULL padded to 14 bytes; as appropriate.
73
743. The first 7 bytes of the truncated password from step 2 are used as a key
75   to DES encrypt the constant ``KGS!@#$%``, resulting
76   in the first 8 bytes of the final digest.
77
784. Step 3 is repeated using the second 7 bytes of the password from step 2,
79   resulting in the second 8 bytes of the final digest.
80
815. The combined digests from 3 and 4 are then encoded to hexadecimal.
82
83Security Issues
84===============
85Due to a myriad of flaws, and the existence high-speed password cracking software
86dedicated to LMHASH, this algorithm should be considered broken. The major flaws include:
87
88* It has no salt, making hashes easily pre-computable.
89
90* It limits the password to 14 characters, and converts the password to
91  uppercase before hashing, greatly reducing the keyspace.
92
93* By breaking the password into two independent chunks,
94  they can be attacked independently and simultaneously.
95
96* The independence of the chunks reveals significant information
97  about the original password: The second 8 bytes of the digest
98  are the same for all passwords < 8 bytes; and for passwords
99  of 8-9 characters, the second chunk can be broken *much* faster,
100  revealing part of the password, and reducing the likely
101  keyspace for the first chunk.
102
103Deviations
104==========
105Passlib's implementation differs from others in a few ways, all related to
106the handling of non-ASCII characters.
107
108* Unicode Policy:
109
110  Officially, unicode passwords should be encoded using the "OEM Codepage"
111  used [#cp]_ by the specific release of Windows that the host or target server
112  is running. Common encodings include ``cp437`` (used by the English
113  edition of Windows XP), ``cp580`` (used by many Western European editions
114  of XP), and ``cp866`` (used by many Eastern European editions of XP).
115  Complicating matters further, some third-party implementations are known
116  to use encodings such as ``latin-1`` and ``utf-8``, which cause
117  non-ASCII characters to hash in a manner incompatible with the canonical
118  MS Windows implementation.
119
120  Thus if an application wishes to provide support for non-ASCII passwords,
121  it must decide which encoding to use.
122
123  Passlib uses ``cp437`` as it's default encoding for unicode strings.
124  However, if your database used a different encoding, you will need to either
125  first encode the passwords into bytes, or override the default encoding
126  via ``lmhash.hash(secret, encoding="some-other-codec")``
127
128  All known encodings are ``us-ascii``-compatible, so for ASCII passwords,
129  the default should be sufficient.
130
131* Upper Case Conversion:
132
133  .. note::
134
135    Future releases of Passlib may change this behavior
136    as new information and code is integrated.
137
138  Once critical step in the LMHASH algorithm is converting the password
139  to upper case. While ASCII characters are uppercased as normal,
140  non-ASCII characters are converted in implementation-dependant ways:
141
142  Windows systems encode the password first, and then
143  convert it to uppercase using an codepage-specific table.
144  For the most part these tables seem to agree with the Unicode specification,
145  but there are some codepoints where they deviate (for example,
146  Unicode uppercases U+00B5 -> U+039C, but ``cp437`` leaves it unchanged [#uc]_).
147
148  In contrast, most third-party implementations (Passlib included)
149  perform the uppercase conversion first using the Unicode specification,
150  and then encode the password second; despite the non-ASCII border cases where the
151  resulting hash would not match the official Windows hash.
152
153.. rubric:: Footnotes
154
155.. [#] Article used as reference for algorithm -
156       `<http://www.linuxjournal.com/article/2717>`_.
157
158.. [#cp] The OEM codepage used by specific Window XP (and earlier) releases
159         can be found at `<http://msdn.microsoft.com/nl-nl/goglobal/cc563921%28en-us%29.aspx>`_.
160
161.. [#uc] Online discussion dealing with upper-case encoding issues -
162         `<http://www.openwall.com/lists/john-dev/2011/08/01/2>`_.
163