| 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 |