Debian Codegraph @

upstream/debian-trixie/man5/crypt.5

raw
1 .\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2024.
2 .\" Revised by Zack Weinberg <zackw at panix.com> in 2017.
3 .\" Converted to mdoc format by Zack Weinberg in 2018.
4 .\"
5 .\" No copyright is claimed, and this man page is hereby placed in the public
6 .\" domain. In case this attempt to disclaim copyright and place the man page
7 .\" in the public domain is deemed null and void, then the man page is
8 .\" Copyright 2000-2011 Solar Designer, 2017 Zack Weinberg, and it is
9 .\" hereby released to the general public under the following terms:
10 .\"
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted.
13 .\"
14 .\" There's ABSOLUTELY NO WARRANTY, express or implied.
15 .\"
16 .Dd March 27, 2024
17 .Dt CRYPT 5
18 .Os "Openwall Project"
19 .Sh NAME
20 .Nm crypt
21 .Nd storage format for hashed passphrases and available hashing methods
22 .Sh DESCRIPTION
23 The hashing methods implemented by
24 .Xr crypt 3
25 are designed only to process user passphrases for storage and authentication;
26 they are not suitable for use as general-purpose cryptographic hashes.
27 .Pp
28 Passphrase hashing is not a replacement for strong passphrases.
29 It is always possible
30 for an attacker with access to the hashed passphrases
31 to guess and check possible cleartext passphrases.
32 However, with a strong hashing method,
33 guessing will be too slow for the attacker
34 to discover a strong passphrase.
35 .Pp
36 Most of the hashing methods use a
37 .Dq salt
38 to perturb the hash function,
39 so that the same passphrase may produce many possible hashes.
40 Newer methods accept longer salt strings.
41 The salt should be chosen at random for each user.
42 Salt defeats a number of attacks:
43 .Bl -enum
44 .It
45 It is not possible to hash a passphrase once
46 and then test it against each account's stored hash;
47 the hash calculation must be repeated for each account.
48 .It
49 It is not possible to tell whether two accounts use the same passphrase
50 without successfully guessing one of the phrases.
51 .It
52 Tables of precalculated hashes of commonly used passphrases
53 must have an entry for each possible salt,
54 which makes them impractically large.
55 .El
56 .Pp
57 Most of the hashing methods are also deliberately engineered to be slow;
58 they use many iterations of an underlying cryptographic primitive
59 to increase the cost of each guess.
60 The newer hashing methods allow the number of iterations to be adjusted,
61 using the
62 .Dq processing cost
63 parameter to
64 .Xr crypt_gensalt 3 .
65 For memory-hard hashing methods such as yescrypt,
66 this parameter also adjusts the amount of memory needed to compute a hash.
67 Having this configurable makes it possible to keep password guessing attacks
68 against the hashes slow and costly as hardware improves.
69 .Sh FORMAT OF HASHED PASSPHRASES
70 All of the hashing methods supported by
71 .Xr crypt 3
72 produce a hashed passphrase which consists of four components:
73 .Ar prefix ,
74 .Ar options ,
75 .Ar salt ,
76 and
77 .Ar hash .
78 The prefix controls which hashing method is to be used, and is the
79 appropriate string to pass to
80 .Xr crypt_gensalt 3
81 to select that method.
82 The contents of
83 .Ar options ,
84 .Ar salt ,
85 and
86 .Ar hash
87 are up to the method.
88 Depending on the method, the
89 .Ar prefix
90 and
91 .Ar options
92 components may be empty.
93 .Pp
94 The
95 .Fa setting
96 argument to
97 .Xr crypt 3
98 must begin with the first three components of a valid hashed passphrase,
99 but anything after that is ignored.
100 This makes authentication simple:
101 hash the input passphrase using the stored hashed passphrase as the setting,
102 and then compare the result to the stored hashed passphrase.
103 .Pp
104 Hashed passphrases are always entirely printable ASCII,
105 and do not contain any whitespace
106 or the characters
107 .Sq Li \&: ,
108 .Sq Li \&; ,
109 .Sq Li \&* ,
110 .Sq Li \&! ,
111 or
112 .Sq Li \&\e .
113 (These characters are used as delimiters and special markers in the
114 .Xr passwd 5
115 and
116 .Xr shadow 5
117 files.)
118 .Pp
119 The syntax of each component of a hashed passphrase
120 is up to the hashing method.
121 .Sq Li \&$
122 characters usually delimit components,
123 and the salt and hash are usually encoded as numerals in base 64.
124 The details of this base-64 encoding vary among hashing methods.
125 The common
126 .Dq base64
127 encoding specified by RFC 4648 is usually
128 .Em not
129 used.
130 .Sh AVAILABLE HASHING METHODS
131 This is a list of
132 .Em all
133 the hashing methods supported by
134 .Xr crypt 3 ,
135 roughly in decreasing order of strength.
136 Many of the older methods
137 are now considered too weak to use for new passphrases.
138 The hashed passphrase format is expressed
139 with extended regular expressions (see
140 .Xr regex 7 )
141 and does not show the division into prefix, options, salt, and hash.
142 .de hash
143 .Bl -tag -width 2n
144 .It Sy Prefix
145 .\" mandoc bug: .Qq comes out with curly quotes.
146 .\" mandoc bug: .Li is hyperlinked to itself for no apparent reason.
147 .Bf Li
148 "\\$1"
149 .Ef
150 .if "\\$1"" (empty string)
151 .It Sy Hashed passphrase format
152 .\" mandoc bug: .Li is hyperlinked to itself for no apparent reason.
153 .Bf -literal
154 \&\\$2
155 .Ef
156 .It Sy Maximum passphrase length
157 .ie "\\$3"unlimited" unlimited
158 .el \\$3 characters
159 .if "\\$4"7" (ignores 8th bit)
160 .It Sy Hash size
161 \\$6 bits
162 .if !"\\$5"\\$6" \{\
163 .It Sy Effective key size
164 \&\\$5 bits
165 .\}
166 .It Sy Salt size
167 \\$7 bits
168 .It Sy Processing cost parameter
169 \\$8
170 .El
171 ..
172 .Ss yescrypt
173 yescrypt is a scalable passphrase hashing scheme designed by Solar Designer,
174 which is based on Colin Percival's scrypt.
175 While yescrypt's strength against password guessing attacks comes from its
176 algorithm design, its cryptographic security is guaranteed by its use of
177 SHA-256 on the outer layer.
178 The SHA-256 hash function has been published by NIST in FIPS PUB 180-2
179 (and its subsequent revisions such as FIPS PUB 180-4)
180 and by the IETF as RFC 4634 (and subsequently RFC 6234).
181 Recommended for new hashes.
182 .hash "$y$" "\e$y\e$[./A-Za-z0-9]+\e$[./A-Za-z0-9]{,86}\e$[./A-Za-z0-9]{43}" unlimited 8 256 256 "up to 512 (128+ recommended)" "1 to 11 (logarithmic, also affects memory usage)"
183 .Ss gost-yescrypt
184 gost-yescrypt uses the output from yescrypt as an input message to HMAC with
185 the GOST R 34.11-2012 (Streebog) hash function with a 256-bit digest.
186 Thus, yescrypt's cryptographic properties are superseded by those of the GOST
187 hash function.
188 This hashing method is useful in applications that need modern passphrase
189 hashing, but have to rely on GOST algorithms.
190 The GOST R 34.11-2012 (Streebog) hash function has been published by the IETF
191 as RFC 6986.
192 Acceptable for new hashes where required.
193 .hash "$gy$" "\e$gy\e$[./A-Za-z0-9]+\e$[./A-Za-z0-9]{,86}\e$[./A-Za-z0-9]{43}" unlimited 8 256 256 "up to 512 (128+ recommended)" "1 to 11 (logarithmic, also affects memory usage)"
194 .Ss scrypt
195 scrypt is a password-based key derivation function created by Colin Percival,
196 originally for the Tarsnap online backup service.
197 The algorithm was specifically designed to make it costly to perform
198 large-scale custom hardware attacks by requiring large amounts of memory.
199 In 2016, the scrypt algorithm was published by IETF as RFC 7914.
200 .hash "$7$" "\e$7\e$[./A-Za-z0-9]{11,97}\e$[./A-Za-z0-9]{43}" unlimited 8 256 256 "up to 512 (128+ recommended)" "6 to 11 (logarithmic, also affects memory usage)"
201 .Ss bcrypt
202 A hash based on the Blowfish block cipher,
203 modified to have an extra-expensive key schedule.
204 Originally developed by Niels Provos and David Mazieres for OpenBSD
205 and also supported on recent versions of FreeBSD and NetBSD,
206 on Solaris 10 and newer, and on several GNU/*/Linux distributions.
207 .hash "$2b$" "\e$2[abxy]\e$[0-9]{2}\e$[./A-Za-z0-9]{53}" 72 8 184 184 128 "4 to 31 (logarithmic)"
208 .Pp
209 The alternative prefix "$2y$" is equivalent to "$2b$".
210 It exists for historical reasons only.
211 The alternative prefixes "$2a$" and "$2x$"
212 provide bug-compatibility with crypt_blowfish 1.0.4 and earlier,
213 which incorrectly processed characters with the 8th bit set.
214 .Ss sha512crypt
215 A hash based on SHA-2 with 512-bit output,
216 originally developed by Ulrich Drepper for GNU libc.
217 Supported on Linux but not common elsewhere.
218 Acceptable for new hashes.
219 The default processing cost parameter is 5000,
220 which is too low for modern hardware.
221 .hash "$6$" "\e$6\e$(rounds=[1-9][0-9]+\e$)?[^$:\(rsn]{1,16}\e$[./0-9A-Za-z]{86}" unlimited 8 512 512 "6 to 96" "1000 to 999,999,999"
222 .Ss sha256crypt
223 A hash based on SHA-2 with 256-bit output,
224 originally developed by Ulrich Drepper for GNU libc.
225 Supported on Linux but not common elsewhere.
226 Acceptable for new hashes.
227 The default processing cost parameter is 5000,
228 which is too low for modern hardware.
229 .hash "$5$" "\e$5\e$(rounds=[1-9][0-9]+\e$)?[^$:\(rsn]{1,16}\e$[./0-9A-Za-z]{43}" unlimited 8 256 256 "6 to 96" "1000 to 999,999,999"
230 .Ss sha1crypt
231 A hash based on HMAC-SHA1.
232 Originally developed by Simon Gerraty for NetBSD.
233 Not as weak as the DES-based hashes below,
234 but SHA-1 is so cheap on modern hardware
235 that it should not be used for new hashes.
236 .hash "$sha1" "\e$sha1\e$[1-9][0-9]+\e$[./0-9A-Za-z]{1,64}\e$[./0-9A-Za-z]{8,64}[./0-9A-Za-z]{32}" unlimited 8 160 160 "6 to 384" "4 to 4,294,967,295"
237 .Ss SunMD5
238 A hash based on the MD5 algorithm,
239 originally developed by Alec David Muffett for Solaris.
240 Not adopted elsewhere, to our knowledge.
241 Not as weak as the DES-based hashes below,
242 but MD5 is so cheap on modern hardware
243 that it should not be used for new hashes.
244 .hash "$md5" "\e$md5(,rounds=[1-9][0-9]+)?\e$[./0-9A-Za-z]{8}\e${1,2}[./0-9A-Za-z]{22}" unlimited 8 128 128 48 "4096 to 4,294,963,199"
245 .Ss md5crypt
246 A hash based on the MD5 algorithm, originally developed by
247 Poul-Henning Kamp for FreeBSD.
248 Supported on most free Unixes and newer versions of Solaris.
249 Not as weak as the DES-based hashes below,
250 but MD5 is so cheap on modern hardware
251 that it should not be used for new hashes.
252 Processing cost is not adjustable.
253 .hash "$1$" "\e$1\e$[^$:\(rsn]{1,8}\e$[./0-9A-Za-z]{22}" unlimited 8 128 128 "6 to 48" 1000
254 .Ss bsdicrypt (BSDI extended DES)
255 An extension of traditional DES,
256 which eliminates the length limit,
257 increases the salt size,
258 and makes the time cost tunable.
259 It originates with BSDI BSD/OS
260 and is also available on at least NetBSD, OpenBSD, and FreeBSD
261 due to the use of David Burren's FreeSec library.
262 It is much better than traditional DES and bigcrypt,
263 but still should not be used for new hashes.
264 .hash _ "_[./0-9A-Za-z]{19}" unlimited 7 "up to 56" 64 24 "1 to 16,777,215 (must be odd)"
265 .Ss descrypt (Traditional DES)
266 The original hashing method from Unix V7, based on the DES block cipher.
267 Because DES is cheap on modern hardware,
268 because there are only 4096 possible salts and 2**56 distinct passphrases,
269 which it truncates to 8 characters,
270 it is feasible to discover
271 .Em any
272 passphrase hashed with this method.
273 It should only be used if you absolutely have to generate hashes
274 that will work on an old operating system that supports nothing else.
275 .hash "" "[./0-9A-Za-z]{13}" 8 7 "up to 56" 64 12 25
276 .Ss bigcrypt
277 A weak extension of traditional DES,
278 available on some commercial Unixes.
279 All it does is raise the length limit from 8 to 128 characters,
280 and it does this in a crude way that allows attackers to
281 guess chunks of a long passphrase separately and in parallel,
282 which may make guessing even easier than for traditional DES above.
283 It should not be used for new hashes.
284 .hash "" "[./0-9A-Za-z]{13,178}" 128 7 "up to 56" "up to 1024" 12 25
285 .Ss NT
286 The hashing method used for network authentication
287 in some versions of the SMB/CIFS protocol.
288 Available, for cross-compatibility's sake, on FreeBSD.
289 Based on MD4.
290 Has no salt or tunable cost parameter.
291 It is so weak that almost
292 .Em any
293 human-chosen passphrase hashed with this method is guessable.
294 It should only be used if you absolutely have to generate hashes
295 that will work on an old operating system that supports nothing else.
296 .hash "$3$" "\e$3\e$\e$[0-9a-f]{32}" unlimited 8 256 256 0 1
297 .Sh SEE ALSO
298 .Xr crypt 3 ,
299 .Xr crypt_gensalt 3 ,
300 .Xr getpwent 3 ,
301 .Xr passwd 5 ,
302 .Xr shadow 5 ,
303 .Xr pam 8
304 .Rs
305 .%A Niels Provos
306 .%A David Mazieres
307 .%T A Future-Adaptable Password Scheme
308 .%B Proceedings of the 1999 USENIX Annual Technical Conference
309 .%D June 1999
310 .%U https://www.usenix.org/events/usenix99/provos.html
311 .Re
312 .Rs
313 .%A Robert Morris
314 .%A Ken Thompson
315 .%T Password Security: A Case History
316 .%J Communications of the ACM
317 .%V 22
318 .%N 11
319 .%D 1979
320 .%U http://wolfram.schneider.org/bsd/7thEdManVol2/password/password.pdf
321 .Re