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