| blob | fa45652b3cecd5d62514c30b0b50c572e68eec91 |
1 .\" $NetBSD: crypt.3,v 1.20 2005/09/05 03:37:15 hubertf Exp $
2 .\"
3 .\" Copyright (c) 1989, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)crypt.3 8.2 (Berkeley) 12/11/93
31 .\"
32 .Dd September 4, 2005
33 .Dt CRYPT 3
34 .Os
35 .Sh NAME
36 .Nm crypt ,
37 .Nm setkey ,
38 .Nm encrypt ,
39 .Nm des_setkey ,
40 .Nm des_cipher
41 .Nd password encryption
42 .Sh LIBRARY
43 .Lb libcrypt
44 .Sh SYNOPSIS
45 .In unistd.h
46 .Ft char
47 .Fn *crypt "const char *key" "const char *setting"
48 .Ft int
49 .Fn encrypt "char *block" "int flag"
50 .Ft int
51 .Fn des_setkey "const char *key"
52 .Ft int
53 .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
54 .In stdlib.h
55 .Ft int
56 .Fn setkey "const char *key"
57 .Sh DESCRIPTION
58 The
59 .Fn crypt
60 function
61 performs password encryption.
62 The encryption scheme used by
63 .Fn crypt
64 is dependent upon the contents of the
65 .Dv NUL Ns -terminated
66 string
67 .Ar setting .
68 If it begins
69 with a string character
70 .Pq Ql $
71 and a number then a different algorithm is used depending on the number.
72 At the moment a
73 .Ql $1
74 chooses MD5 hashing and a
75 .Ql $2
76 chooses Blowfish hashing; see below for more information.
77 If
78 .Ar setting
79 begins with the ``_'' character, DES encryption with a user specified number
80 of perturbations is selected.
81 If
82 .Ar setting
83 begins with any other character, DES encryption with a fixed number
84 of perturbations is selected.
85 .Ss DES encryption
86 The DES encryption scheme is derived from the
87 .Tn NBS
88 Data Encryption Standard.
89 Additional code has been added to deter key search attempts and to use
90 stronger hashing algorithms.
91 In the DES case, the second argument to
92 .Fn crypt
93 is a character array, 9 bytes in length, consisting of an underscore (``_'')
94 followed by 4 bytes of iteration count and 4 bytes of salt.
95 Both the iteration
96 .Fa count
97 and the
98 .Fa salt
99 are encoded with 6 bits per character, least significant bits first.
100 The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'',
101 respectively.
102 .Pp
103 The
104 .Fa salt
105 is used to induce disorder in to the
106 .Tn DES
107 algorithm
108 in one of 16777216
109 possible ways
110 (specifically, if bit
111 .Em i
112 of the
113 .Ar salt
114 is set then bits
115 .Em i
116 and
117 .Em i+24
118 are swapped in the
119 .Tn DES
120 ``E'' box output).
121 The
122 .Ar key
123 is divided into groups of 8 characters (a short final group is null-padded)
124 and the low-order 7 bits of each character (56 bits per group) are
125 used to form the DES key as follows: the first group of 56 bits becomes the
126 initial DES key.
127 For each additional group, the XOR of the group bits and the encryption of
128 the DES key with itself becomes the next DES key.
129 Then the final DES key is used to perform
130 .Ar count
131 cumulative encryptions of a 64-bit constant.
132 The value returned is a
133 .Dv NUL Ns -terminated
134 string, 20 bytes in length, consisting
135 of the
136 .Ar setting
137 followed by the encoded 64-bit encryption.
138 .Pp
139 For compatibility with historical versions of
140 .Xr crypt 3 ,
141 the
142 .Ar setting
143 may consist of 2 bytes of salt, encoded as above, in which case an
144 iteration
145 .Ar count
146 of 25 is used, fewer perturbations of
147 .Tn DES
148 are available, at most 8
149 characters of
150 .Ar key
151 are used, and the returned value is a
152 .Dv NUL Ns -terminated
153 string 13 bytes in length.
154 .Pp
155 The
156 functions
157 .Fn encrypt ,
158 .Fn setkey ,
159 .Fn des_setkey
160 and
161 .Fn des_cipher
162 allow limited access to the
163 .Tn DES
164 algorithm itself.
165 The
166 .Ar key
167 argument to
168 .Fn setkey
169 is a 64 character array of
170 binary values (numeric 0 or 1).
171 A 56-bit key is derived from this array by dividing the array
172 into groups of 8 and ignoring the last bit in each group.
173 .Pp
174 The
175 .Fn encrypt
176 argument
177 .Fa block
178 is also a 64 character array of
179 binary values.
180 If the value of
181 .Fa flag
182 is 0,
183 the argument
184 .Fa block
185 is encrypted, otherwise it
186 is decrypted.
187 The encryption or decryption is returned in the original
188 array
189 .Fa block
190 after using the
191 key specified
192 by
193 .Fn setkey
194 to process it.
195 .Pp
196 The
197 .Fn des_setkey
198 and
199 .Fn des_cipher
200 functions are faster but less portable than
201 .Fn setkey
202 and
203 .Fn encrypt .
204 The argument to
205 .Fn des_setkey
206 is a character array of length 8.
207 The
208 .Em least
209 significant bit in each character is ignored and the next 7 bits of each
210 character are concatenated to yield a 56-bit key.
211 The function
212 .Fn des_cipher
213 encrypts (or decrypts if
214 .Fa count
215 is negative) the 64-bits stored in the 8 characters at
216 .Fa in
217 using
218 .Xr abs 3
219 of
220 .Fa count
221 iterations of
222 .Tn DES
223 and stores the 64-bit result in the 8 characters at
224 .Fa out .
225 The
226 .Fa salt
227 specifies perturbations to
228 .Tn DES
229 as described above.
230 .Ss MD5 encryption
231 For the
232 .Tn MD5
233 encryption scheme, the version number (in this case ``1''),
234 .Fa salt
235 and the hashed password are separated
236 by the ``$'' character.
237 A valid password looks like this:
238 .Pp
239 ``$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H.''.
240 .Pp
241 The entire password string is passed as
242 .Fa setting
243 for interpretation.
244 .Ss "Blowfish" crypt
245 The
246 .Tn Blowfish
247 version of crypt has 128 bits of
248 .Fa salt
249 in order to make building dictionaries of common passwords space consuming.
250 The initial state of the
251 .Tn Blowfish
252 cipher is expanded using the
253 .Fa salt
254 and the
255 .Fa password
256 repeating the process a variable number of rounds, which is encoded in
257 the password string.
258 The maximum password length is 72.
259 The final Blowfish password entry is created by encrypting the string
260 .Pp
261 .Dq OrpheanBeholderScryDoubt
262 .Pp
263 with the
264 .Tn Blowfish
265 state 64 times.
266 .Pp
267 The version number, the logarithm of the number of rounds and
268 the concatenation of salt and hashed password are separated by the
269 .Ql $
270 character.
271 An encoded
272 .Sq 8
273 would specify 256 rounds.
274 A valid Blowfish password looks like this:
275 .Pp
276 .Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
277 .Pp
278 The whole Blowfish password string is passed as
279 .Fa setting
280 for interpretation.
281 .Sh RETURN VALUES
282 The function
283 .Fn crypt
284 returns a pointer to the encrypted value on success and NULL on failure.
285 The functions
286 .Fn setkey ,
287 .Fn encrypt ,
288 .Fn des_setkey ,
289 and
290 .Fn des_cipher
291 return 0 on success and 1 on failure.
292 Historically, the functions
293 .Fn setkey
294 and
295 .Fn encrypt
296 did not return any value.
297 They have been provided return values primarily to distinguish
298 implementations where hardware support is provided but not
299 available or where the DES encryption is not available due to the
300 usual political silliness.
301 .Sh SEE ALSO
302 .Xr login 1 ,
303 .Xr passwd 1 ,
304 .Xr pwhash 1 ,
305 .Xr getpass 3 ,
306 .Xr md5 3 ,
307 .Xr passwd 5 ,
308 .Xr passwd.conf 5
309 .Rs
310 .%T "Mathematical Cryptology for Computer Scientists and Mathematicians"
311 .%A Wayne Patterson
312 .%D 1987
313 .%N ISBN 0-8476-7438-X
314 .Re
315 .Rs
316 .%T "Password Security: A Case History"
317 .%A R. Morris
318 .%A Ken Thompson
319 .%J "Communications of the ACM"
320 .%V vol. 22
321 .%P pp. 594-597
322 .%D Nov. 1979
323 .Re
324 .Rs
325 .%T "DES will be Totally Insecure within Ten Years"
326 .%A M.E. Hellman
327 .%J "IEEE Spectrum"
328 .%V vol. 16
329 .%P pp. 32-39
330 .%D July 1979
331 .Re
332 .Sh HISTORY
333 A rotor-based
334 .Fn crypt
335 function appeared in
336 .At v6 .
337 The current style
338 .Fn crypt
339 first appeared in
340 .At v7 .
341 .Sh BUGS
342 Dropping the
343 .Em least
344 significant bit in each character of the argument to
345 .Fn des_setkey
346 is ridiculous.
347 .Pp
348 The
349 .Fn crypt
350 function leaves its result in an internal static object and returns
351 a pointer to that object.
352 Subsequent calls to
353 .Fn crypt
354 will modify the same object.