1:mod:`crypt` --- Function to check Unix passwords 2================================================= 3 4.. module:: crypt 5 :platform: Unix 6 :synopsis: The crypt() function used to check Unix passwords. 7 8.. moduleauthor:: Steven D. Majewski <sdm7g@virginia.edu> 9.. sectionauthor:: Steven D. Majewski <sdm7g@virginia.edu> 10.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de> 11 12**Source code:** :source:`Lib/crypt.py` 13 14.. index:: 15 single: crypt(3) 16 pair: cipher; DES 17 18-------------- 19 20This module implements an interface to the :manpage:`crypt(3)` routine, which is 21a one-way hash function based upon a modified DES algorithm; see the Unix man 22page for further details. Possible uses include storing hashed passwords 23so you can check passwords without storing the actual password, or attempting 24to crack Unix passwords with a dictionary. 25 26.. index:: single: crypt(3) 27 28Notice that the behavior of this module depends on the actual implementation of 29the :manpage:`crypt(3)` routine in the running system. Therefore, any 30extensions available on the current implementation will also be available on 31this module. 32 33.. availability:: Unix. Not available on VxWorks. 34 35Hashing Methods 36--------------- 37 38.. versionadded:: 3.3 39 40The :mod:`crypt` module defines the list of hashing methods (not all methods 41are available on all platforms): 42 43.. data:: METHOD_SHA512 44 45 A Modular Crypt Format method with 16 character salt and 86 character 46 hash based on the SHA-512 hash function. This is the strongest method. 47 48.. data:: METHOD_SHA256 49 50 Another Modular Crypt Format method with 16 character salt and 43 51 character hash based on the SHA-256 hash function. 52 53.. data:: METHOD_BLOWFISH 54 55 Another Modular Crypt Format method with 22 character salt and 31 56 character hash based on the Blowfish cipher. 57 58 .. versionadded:: 3.7 59 60.. data:: METHOD_MD5 61 62 Another Modular Crypt Format method with 8 character salt and 22 63 character hash based on the MD5 hash function. 64 65.. data:: METHOD_CRYPT 66 67 The traditional method with a 2 character salt and 13 characters of 68 hash. This is the weakest method. 69 70 71Module Attributes 72----------------- 73 74.. versionadded:: 3.3 75 76.. attribute:: methods 77 78 A list of available password hashing algorithms, as 79 ``crypt.METHOD_*`` objects. This list is sorted from strongest to 80 weakest. 81 82 83Module Functions 84---------------- 85 86The :mod:`crypt` module defines the following functions: 87 88.. function:: crypt(word, salt=None) 89 90 *word* will usually be a user's password as typed at a prompt or in a graphical 91 interface. The optional *salt* is either a string as returned from 92 :func:`mksalt`, one of the ``crypt.METHOD_*`` values (though not all 93 may be available on all platforms), or a full encrypted password 94 including salt, as returned by this function. If *salt* is not 95 provided, the strongest method will be used (as returned by 96 :func:`methods`). 97 98 Checking a password is usually done by passing the plain-text password 99 as *word* and the full results of a previous :func:`crypt` call, 100 which should be the same as the results of this call. 101 102 *salt* (either a random 2 or 16 character string, possibly prefixed with 103 ``$digit$`` to indicate the method) which will be used to perturb the 104 encryption algorithm. The characters in *salt* must be in the set 105 ``[./a-zA-Z0-9]``, with the exception of Modular Crypt Format which 106 prefixes a ``$digit$``. 107 108 Returns the hashed password as a string, which will be composed of 109 characters from the same alphabet as the salt. 110 111 .. index:: single: crypt(3) 112 113 Since a few :manpage:`crypt(3)` extensions allow different values, with 114 different sizes in the *salt*, it is recommended to use the full crypted 115 password as salt when checking for a password. 116 117 .. versionchanged:: 3.3 118 Accept ``crypt.METHOD_*`` values in addition to strings for *salt*. 119 120 121.. function:: mksalt(method=None, *, rounds=None) 122 123 Return a randomly generated salt of the specified method. If no 124 *method* is given, the strongest method available as returned by 125 :func:`methods` is used. 126 127 The return value is a string suitable for passing as the *salt* argument 128 to :func:`crypt`. 129 130 *rounds* specifies the number of rounds for ``METHOD_SHA256``, 131 ``METHOD_SHA512`` and ``METHOD_BLOWFISH``. 132 For ``METHOD_SHA256`` and ``METHOD_SHA512`` it must be an integer between 133 ``1000`` and ``999_999_999``, the default is ``5000``. For 134 ``METHOD_BLOWFISH`` it must be a power of two between ``16`` (2\ :sup:`4`) 135 and ``2_147_483_648`` (2\ :sup:`31`), the default is ``4096`` 136 (2\ :sup:`12`). 137 138 .. versionadded:: 3.3 139 140 .. versionchanged:: 3.7 141 Added the *rounds* parameter. 142 143 144Examples 145-------- 146 147A simple example illustrating typical use (a constant-time comparison 148operation is needed to limit exposure to timing attacks. 149:func:`hmac.compare_digest` is suitable for this purpose):: 150 151 import pwd 152 import crypt 153 import getpass 154 from hmac import compare_digest as compare_hash 155 156 def login(): 157 username = input('Python login: ') 158 cryptedpasswd = pwd.getpwnam(username)[1] 159 if cryptedpasswd: 160 if cryptedpasswd == 'x' or cryptedpasswd == '*': 161 raise ValueError('no support for shadow passwords') 162 cleartext = getpass.getpass() 163 return compare_hash(crypt.crypt(cleartext, cryptedpasswd), cryptedpasswd) 164 else: 165 return True 166 167To generate a hash of a password using the strongest available method and 168check it against the original:: 169 170 import crypt 171 from hmac import compare_digest as compare_hash 172 173 hashed = crypt.crypt(plaintext) 174 if not compare_hash(hashed, crypt.crypt(plaintext, hashed)): 175 raise ValueError("hashed version doesn't validate against original") 176