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