source: project/wiki/eggref/4/crypt @ 22209

Last change on this file since 22209 was 22209, checked in by sjamaan, 10 years ago

Improve wording a little bit

File size: 6.0 KB
Line 
1== crypt
2
3This egg provides functions for generating secure password hashes.
4
5This is done by providing Chicken bindings for the Unix crypt() function. It will attempt to use the system's crypt() for all available types, and supplies fallbacks when the native crypt does not implement a common scheme like Niels Provos' bcrypt() or Ulrich Drepper's SHA-2 based crypt().
6
7=== Basic usage
8
9Basic usage is extremely simple (just like Unix crypt()):
10
11==== Generating a new password hash
12
13<enscript highlight="scheme">
14(use crypt)
15
16(crypt "password") => "$2a$12$eeOD.RHX7kex47wGOu3ZVu2JhRyQBBOyORhd/mTWjQghMWbrxGNCy"
17</enscript>
18
19This will automatically use the hashing mechanism currently deemed most secure. At the moment that is the Blowfish hashing scheme with 2^12 rounds. A new random salt is automatically generated each time this procedure is invoked with only one argument.
20
21==== Checking whether a password matches a hash
22
23This is done just like Unix crypt() by checking whether the generated hash matches the input hash:
24
25<enscript highlight="scheme">
26(use crypt)
27
28(define h "$2a$12$eeOD.RHX7kex47wGOu3ZVu2JhRyQBBOyORhd/mTWjQghMWbrxGNCy")
29
30(string=? (crypt "password" h) h) => #t
31(string=? (crypt "wrong" h) h) => #f
32</enscript>
33
34=== Why use crypt()?
35
36The advantage of Unix crypt() over other password hashing schemes is that crypt() provides a way to upgrade the hashing mechanism to a more secure one without having to rehash all passwords; hashes are stored with a prefix code which indicates the hashing mechanism used to generate that hash, so they continue to work using the old algorithm while newly generated hashes are hashed using the stronger algorithm.
37
38Other languages might include [[http://codahale.com/how-to-safely-store-a-password/|just a library specifically for bcrypt()]], but this egg's author thinks it is silly to provide a separate library with a dedicated API, precisely because crypt() is ''designed'' to transparently upgrade to stronger algorithms as time progresses. bcrypt(), because it is [[http://www.usenix.org/events/usenix99/provos.html|adaptive for CPU speed improvements]], will provide good security for the foreseeable future ''as long as no weaknesses are discovered in the algorithm itself''. Once that happens (or a substantially better scheme is developed, etc) you would need to replace all calls to that library with a new one (or change bcrypt() to include whatevercrypt() code).
39
40==== Background info
41
42Crypt hashes come in three basic flavors:
43
44===== Raw DES
45
46 rEK1ecacw.7.c   (salt: re)
47
48This is just a raw base64-encoded DES password hash. The first two characters encode the salt, the rest is the hashed password.
49
50===== Extended DES
51
52Extended DES uses a variable number of encryption rounds and 24 bits of salt rather than 12 bits.
53
54  _J9..K0AyUubDrfOgO4s     (salt: _J9..K0Ay)
55
56The leading underscore indicates we're using the extended DES scheme here. The first four characters after the underscore indicate the number of iterations to run the encryption algorithm, the next four represent the salt and the final eleven are the hashed password.
57
58===== Modern, modular format
59
60This looks like the following:
61
62 $ALG$ALGSPECIFIC
63
64For example:
65
66 $1$O3JMY.Tw$AdLnLjQ/5jXF9.MTp3gHv/   (salt: $1$O3JMY.Tw)
67
68For more examples of hashes, see the [[http://openwall.info/wiki/john/sample-hashes|OpenWall/John the Ripper community wiki page with sample hashes]]
69
70The ALG encodes the algorithm used for generating the hash, the ALGSPECIFIC is usually the salt followed by the hash. Some schemes store some additional settings before the salt, and some separate the salt from the hash with a dollar sign.
71
72Currently, the following values for {{ALG}} are standardized:
73
74; {{$1$}} : Paul Hennig-Kamp's MD5 scheme. This is a very baroque system, introduced in FreeBSD, which runs MD5 for a large but ''fixed'' number of iterations on the password.
75; {{$2a$}} : Niels Provos' Blowfish scheme. This is an adaptable scheme introduced in OpenBSD, which allows the system administrator to determine the number of rounds to run the algorithm. As hardware speed improves, this number can be increased to compensate.
76; {{$5$}}: Ulrich Drepper's SHA-256 scheme. This is also an adaptable scheme, introduced in glibc.
77; {{$6$}}: Ulrich Drepper's SHA-512 scheme. Same as the above, except with hashes of double the size :)
78
79There are also some less common values:
80
81; {{$apr1$}} : Identical to {{$1$}}. This prefix is generated by the Apache Portable Runtime library (used by {{htpasswd}}, for example)
82; {SHA} : SHA-1 hash, also used by the Apache Portable Runtime library. (yes, this is not compatible with the standard dollar-sign prefix. Apparently these guys '''like''' being completely incompatible to the rest of the world)
83; {{$P$}} : MD5-based hash used by [[http://www.openwall.com/phpass/|PHPass - the Portable PHP password hashing framework]]
84; {{$H$}} : Same as above, but used by [[http://area51.phpbb.com/docs/code/phpBB3/_includes---functions.php.html#functionphpbb_hash|PHPbb]] because, well, they're PHP developers. (I wonder if these developers are somehow related to the people working on APR...)
85
86=== License
87
88  All code in this egg is explicitly placed in the public domain. You may do whatever you want with it.
89
90This egg contains code written by the following people:
91
92* Peter Bex (Chicken glue code, MD5 crypt implementation)
93* Colin Plumb (MD5 code)
94* [[http://www.akkadia.org/drepper/sha-crypt.html|Ulrich Drepper]] (SHA-2 implementation)
95* "[[http://www.openwall.org/crypt|Solar Designer]]" (Blowfish implementation, salt generation code)
96
97=== References
98
99* Shiro Kawai, "[[http://blog.practical-scheme.net/gauche/20100427-crypt-bcrypt|Blowfish password hashing]]"
100* Thomas Ptacek, "[[http://chargen.matasano.com/chargen/2007/9/7/enough-with-the-rainbow-tables-what-you-need-to-know-about-s.html|Enough With The Rainbow Tables: What You Need To Know About Secure Password Schemes]]"
101* Coda Hale, "[[http://codahale.com/how-to-safely-store-a-password/|How to safely store a password]]"
102* Niels Provos and David MaziÚres, "[[http://www.usenix.org/events/usenix99/provos.html|A Future-Adaptable Password Scheme]]"
Note: See TracBrowser for help on using the repository browser.