Debian Codegraph @

upstream/debian-unstable/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 sm3-yescrypt
195 sm3-yescrypt uses the output from yescrypt as an input message to HMAC with
196 the ShangMi 3 hash function with a 256-bit digest.
197 Thus, yescrypt's cryptographic properties are superseded by those of the
198 ShangMi 3 hash function.
199 This hashing method is useful in applications that need modern passphrase
200 hashing, but have to rely on algorithms approved by the Chinese Office of
201 State Commercial Cryptography Administration (OSCCA).
202 The ShangMi 3 hash function has been published in Part 3: "Dedicated
203 hash-functions" of the ISO/IEC 10118-3:2018.
204 Acceptable for new hashes where required.
205 .hash "$sm3y$" "\e$sm3y\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)"
206 .Ss scrypt
207 scrypt is a password-based key derivation function created by Colin Percival,
208 originally for the Tarsnap online backup service.
209 The algorithm was specifically designed to make it costly to perform
210 large-scale custom hardware attacks by requiring large amounts of memory.
211 In 2016, the scrypt algorithm was published by IETF as RFC 7914.
212 .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)"
213 .Ss bcrypt
214 A hash based on the Blowfish block cipher,
215 modified to have an extra-expensive key schedule.
216 Originally developed by Niels Provos and David Mazieres for OpenBSD
217 and also supported on recent versions of FreeBSD and NetBSD,
218 on Solaris 10 and newer, and on several GNU/*/Linux distributions.
219 .hash "$2b$" "\e$2[abxy]\e$[0-9]{2}\e$[./A-Za-z0-9]{53}" 72 8 184 184 128 "4 to 31 (logarithmic)"
220 .Pp
221 The alternative prefix "$2y$" is equivalent to "$2b$".
222 It exists for historical reasons only.
223 The alternative prefixes "$2a$" and "$2x$"
224 provide bug-compatibility with crypt_blowfish 1.0.4 and earlier,
225 which incorrectly processed characters with the 8th bit set.
226 .Ss sha512crypt
227 A hash based on SHA-2 with 512-bit output,
228 originally developed by Ulrich Drepper for GNU libc.
229 Supported on Linux but not common elsewhere.
230 Acceptable for new hashes.
231 The default processing cost parameter is 5000,
232 which is too low for modern hardware.
233 .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"
234 .Ss sha256crypt
235 A hash based on SHA-2 with 256-bit output,
236 originally developed by Ulrich Drepper for GNU libc.
237 Supported on Linux but not common elsewhere.
238 Acceptable for new hashes.
239 The default processing cost parameter is 5000,
240 which is too low for modern hardware.
241 .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"
242 .Ss sm3crypt
243 A hash based on the ShangMi 3 hash function
244 with 256-bit output, that uses the same design as
245 sha256crypt and/or sha512crypt.
246 Supported on EulerOS, Kylin, openEuler, and openKylin,
247 but not common elsewhere.
248 Acceptable for new hashes where required.
249 The default processing cost parameter is 5000,
250 which is too low for modern hardware.
251 .hash "$sm3$" "\e$sm3\e$(rounds=[1-9][0-9]+\e$)?[^$:\(rsn]{1,16}\e$[./0-9A-Za-z]{86}" unlimited 8 256 256 "6 to 96" "1000 to 999,999,999"
252 .Ss sha1crypt
253 A hash based on HMAC-SHA1.
254 Originally developed by Simon Gerraty for NetBSD.
255 Not as weak as the DES-based hashes below,
256 but SHA-1 is so cheap on modern hardware
257 that it should not be used for new hashes.
258 .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"
259 .Ss SunMD5
260 A hash based on the MD5 algorithm,
261 originally developed by Alec David Muffett for Solaris.
262 Not adopted elsewhere, to our knowledge.
263 Not as weak as the DES-based hashes below,
264 but MD5 is so cheap on modern hardware
265 that it should not be used for new hashes.
266 .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"
267 .Ss md5crypt
268 A hash based on the MD5 algorithm, originally developed by
269 Poul-Henning Kamp for FreeBSD.
270 Supported on most free Unixes and newer versions of Solaris.
271 Not as weak as the DES-based hashes below,
272 but MD5 is so cheap on modern hardware
273 that it should not be used for new hashes.
274 Processing cost is not adjustable.
275 .hash "$1$" "\e$1\e$[^$:\(rsn]{1,8}\e$[./0-9A-Za-z]{22}" unlimited 8 128 128 "6 to 48" 1000
276 .Ss bsdicrypt (BSDI extended DES)
277 An extension of traditional DES,
278 which eliminates the length limit,
279 increases the salt size,
280 and makes the time cost tunable.
281 It originates with BSDI BSD/OS
282 and is also available on at least NetBSD, OpenBSD, and FreeBSD
283 due to the use of David Burren's FreeSec library.
284 It is much better than traditional DES and bigcrypt,
285 but still should not be used for new hashes.
286 .hash _ "_[./0-9A-Za-z]{19}" unlimited 7 "up to 56" 64 24 "1 to 16,777,215 (must be odd)"
287 .Ss descrypt (Traditional DES)
288 The original hashing method from Unix V7, based on the DES block cipher.
289 Because DES is cheap on modern hardware,
290 because there are only 4096 possible salts and 2**56 distinct passphrases,
291 which it truncates to 8 characters,
292 it is feasible to discover
293 .Em any
294 passphrase hashed with this method.
295 It should only be used if you absolutely have to generate hashes
296 that will work on an old operating system that supports nothing else.
297 .hash "" "[./0-9A-Za-z]{13}" 8 7 "up to 56" 64 12 25
298 .Ss bigcrypt
299 A weak extension of traditional DES,
300 available on some commercial Unixes.
301 All it does is raise the length limit from 8 to 128 characters,
302 and it does this in a crude way that allows attackers to
303 guess chunks of a long passphrase separately and in parallel,
304 which may make guessing even easier than for traditional DES above.
305 It should not be used for new hashes.
306 .hash "" "[./0-9A-Za-z]{13,178}" 128 7 "up to 56" "up to 1024" 12 25
307 .Ss NT
308 The hashing method used for network authentication
309 in some versions of the SMB/CIFS protocol.
310 Available, for cross-compatibility's sake, on FreeBSD.
311 Based on MD4.
312 Has no salt or tunable cost parameter.
313 It is so weak that almost
314 .Em any
315 human-chosen passphrase hashed with this method is guessable.
316 It should only be used if you absolutely have to generate hashes
317 that will work on an old operating system that supports nothing else.
318 .hash "$3$" "\e$3\e$\e$[0-9a-f]{32}" unlimited 8 256 256 0 1
319 .Sh SEE ALSO
320 .Xr crypt 3 ,
321 .Xr crypt_gensalt 3 ,
322 .Xr getpwent 3 ,
323 .Xr passwd 5 ,
324 .Xr shadow 5 ,
325 .Xr pam 8
326 .Rs
327 .%A Niels Provos
328 .%A David Mazieres
329 .%T A Future-Adaptable Password Scheme
330 .%B Proceedings of the 1999 USENIX Annual Technical Conference
331 .%D June 1999
332 .%U https://www.usenix.org/events/usenix99/provos.html
333 .Re
334 .Rs
335 .%A Robert Morris
336 .%A Ken Thompson
337 .%T Password Security: A Case History
338 .%J Communications of the ACM
339 .%V 22
340 .%N 11
341 .%D 1979
342 .%U http://wolfram.schneider.org/bsd/7thEdManVol2/password/password.pdf
343 .Re