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