| blob | b6da1da7ded997631fc743c72b2d5c390b593db8 |
1 .\" $NetBSD: crypt.3,v 1.27 2012/03/23 18:08:35 njoly 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 January 1, 2012
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 .Fn crypt ,
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
248 .Fn crypt
249 has 128 bits of
250 .Fa salt
251 in order to make building dictionaries of common passwords space consuming.
252 The initial state of the
253 .Tn Blowfish
254 cipher is expanded using the
255 .Fa salt
256 and the
257 .Fa password
258 repeating the process a variable number of rounds, which is encoded in
259 the password string.
260 The maximum password length is 72.
261 The final Blowfish password entry is created by encrypting the string
262 .Pp
263 .Dq OrpheanBeholderScryDoubt
264 .Pp
265 with the
266 .Tn Blowfish
267 state 64 times.
268 .Pp
269 The version number, the logarithm of the number of rounds and
270 the concatenation of salt and hashed password are separated by the
271 .Ql $
272 character.
273 An encoded
274 .Sq 8
275 would specify 256 rounds.
276 A valid Blowfish password looks like this:
277 .Pp
278 .Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
279 .Pp
280 The whole Blowfish password string is passed as
281 .Fa setting
282 for interpretation.
283 .Sh RETURN VALUES
284 The function
285 .Fn crypt
286 returns a pointer to the encrypted value on success.
287 .Pp
288 The behavior of
289 .Fn crypt
290 on errors isn't well standardized.
291 Some implementations simply can't fail (unless the process dies, in which
292 case they obviously can't return), others return
293 .Dv NULL
294 or a fixed string.
295 Most implementations don't set
296 .Va errno ,
297 but some do.
298 .St -susv2
299 specifies
300 only returning
301 .Dv NULL
302 and setting
303 .Va errno
304 as a valid behavior, and defines
305 only one possible error
306 .Er ( ENOSYS ,
307 .Dq "The functionality is not supported on this implementation." )
308 Unfortunately, most existing applications aren't prepared to handle
309 .Dv NULL
310 returns from
311 .Fn crypt .
312 The description below corresponds to this implementation of
313 .Fn crypt
314 only.
315 The behavior may change to match standards, other implementations or existing
316 applications.
317 .Pp
318 .Fn crypt
319 may only fail (and return) when passed an invalid or unsupported
320 .Fa setting ,
321 in which case it returns a pointer to a magic string that is shorter than 13
322 characters and is guaranteed to differ from
323 .Fa setting .
324 This behavior is safe for older applications which assume that
325 .Fn crypt
326 can't fail, when both setting new passwords and authenticating against
327 existing password hashes.
328 .Pp
329 The functions
330 .Fn setkey ,
331 .Fn encrypt ,
332 .Fn des_setkey ,
333 and
334 .Fn des_cipher
335 return 0 on success and 1 on failure.
336 Historically, the functions
337 .Fn setkey
338 and
339 .Fn encrypt
340 did not return any value.
341 They have been provided return values primarily to distinguish
342 implementations where hardware support is provided but not
343 available or where the DES encryption is not available due to the
344 usual political silliness.
345 .Sh SEE ALSO
346 .Xr login 1 ,
347 .Xr passwd 1 ,
348 .Xr pwhash 1 ,
349 .Xr getpass 3 ,
350 .Xr md5 3 ,
351 .Xr passwd 5 ,
352 .Xr passwd.conf 5
353 .Rs
354 .%T "Mathematical Cryptology for Computer Scientists and Mathematicians"
355 .%A Wayne Patterson
356 .%D 1987
357 .%N ISBN 0-8476-7438-X
358 .Re
359 .Rs
360 .%T "Password Security: A Case History"
361 .%A R. Morris
362 .%A Ken Thompson
363 .%J "Communications of the ACM"
364 .%V vol. 22
365 .%P pp. 594-597
366 .%D Nov. 1979
367 .Re
368 .Rs
369 .%T "DES will be Totally Insecure within Ten Years"
370 .%A M.E. Hellman
371 .%J "IEEE Spectrum"
372 .%V vol. 16
373 .%P pp. 32-39
374 .%D July 1979
375 .Re
376 .Sh HISTORY
377 A rotor-based
378 .Fn crypt
379 function appeared in
380 .At v6 .
381 The current style
382 .Fn crypt
383 first appeared in
384 .At v7 .
385 .Sh BUGS
386 Dropping the
387 .Em least
388 significant bit in each character of the argument to
389 .Fn des_setkey
390 is ridiculous.
391 .Pp
392 The
393 .Fn crypt
394 function leaves its result in an internal static object and returns
395 a pointer to that object.
396 Subsequent calls to
397 .Fn crypt
398 will modify the same object.
399 .Pp
400 Before
401 .Nx 6.0
402 .Fn crypt
403 returned either
404 .Dv NULL
405 or
406 .Dv \&:
407 on error.