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