diff options
Diffstat (limited to 'src/lib/libc/crypt/crypt.3')
-rw-r--r-- | src/lib/libc/crypt/crypt.3 | 325 |
1 files changed, 0 insertions, 325 deletions
diff --git a/src/lib/libc/crypt/crypt.3 b/src/lib/libc/crypt/crypt.3 deleted file mode 100644 index 8415f28b9b..0000000000 --- a/src/lib/libc/crypt/crypt.3 +++ /dev/null | |||
@@ -1,325 +0,0 @@ | |||
1 | .\" $OpenBSD: crypt.3,v 1.28 2012/06/02 00:14:16 guenther Exp $ | ||
2 | .\" | ||
3 | .\" FreeSec: libcrypt | ||
4 | .\" | ||
5 | .\" Copyright (c) 1994 David Burren | ||
6 | .\" All rights reserved. | ||
7 | .\" | ||
8 | .\" Redistribution and use in source and binary forms, with or without | ||
9 | .\" modification, are permitted provided that the following conditions | ||
10 | .\" are met: | ||
11 | .\" 1. Redistributions of source code must retain the above copyright | ||
12 | .\" notice, this list of conditions and the following disclaimer. | ||
13 | .\" 2. Redistributions in binary form must reproduce the above copyright | ||
14 | .\" notice, this list of conditions and the following disclaimer in the | ||
15 | .\" documentation and/or other materials provided with the distribution. | ||
16 | .\" 4. Neither the name of the author nor the names of other contributors | ||
17 | .\" may be used to endorse or promote products derived from this software | ||
18 | .\" without specific prior written permission. | ||
19 | .\" | ||
20 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | ||
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | ||
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||
30 | .\" SUCH DAMAGE. | ||
31 | .\" | ||
32 | .\" Manual page, using -mandoc macros | ||
33 | .\" | ||
34 | .Dd $Mdocdate: June 2 2012 $ | ||
35 | .Dt CRYPT 3 | ||
36 | .Os | ||
37 | .Sh NAME | ||
38 | .Nm crypt , | ||
39 | .Nm setkey , | ||
40 | .Nm encrypt , | ||
41 | .Nm des_setkey , | ||
42 | .Nm des_cipher , | ||
43 | .Nm bcrypt_gensalt , | ||
44 | .Nm bcrypt , | ||
45 | .Nm md5crypt | ||
46 | .Nd DES encryption | ||
47 | .Sh SYNOPSIS | ||
48 | .Fd #include <stdlib.h> | ||
49 | .Ft int | ||
50 | .Fn setkey "const char *key" | ||
51 | .Pp | ||
52 | .Fd #include <unistd.h> | ||
53 | .Ft char * | ||
54 | .Fn crypt "const char *key" "const char *setting" | ||
55 | .Ft int | ||
56 | .Fn encrypt "char *block" "int flag" | ||
57 | .Ft int | ||
58 | .Fn des_setkey "const char *key" | ||
59 | .Ft int | ||
60 | .Fn des_cipher "const char *in" "char *out" "int32_t salt" "int count" | ||
61 | .Ft char * | ||
62 | .Fn bcrypt_gensalt "u_int8_t log_rounds" | ||
63 | .Ft char * | ||
64 | .Fn bcrypt "const char *key" "const char *salt" | ||
65 | .Ft char * | ||
66 | .Fn md5crypt "const char *key" "const char *salt" | ||
67 | .Sh DESCRIPTION | ||
68 | The | ||
69 | .Fn crypt | ||
70 | function performs password encryption based on the | ||
71 | .Tn NBS | ||
72 | Data Encryption Standard (DES). | ||
73 | Additional code has been added to deter key search attempts and to use | ||
74 | stronger hashing algorithms. | ||
75 | .Pp | ||
76 | The first argument to | ||
77 | .Fn crypt | ||
78 | is a | ||
79 | .Dv NUL Ns -terminated | ||
80 | string, typically a user's typed password. | ||
81 | The second is in one of three forms: | ||
82 | if it begins with an underscore | ||
83 | .Pq Ql _ | ||
84 | then an extended format is used | ||
85 | in interpreting both the key and the setting, as outlined below. | ||
86 | If it begins | ||
87 | with a string character | ||
88 | .Pq Ql $ | ||
89 | and a number then a different algorithm is used depending on the number. | ||
90 | At the moment a | ||
91 | .Ql $1 | ||
92 | chooses MD5 hashing and a | ||
93 | .Ql $2 | ||
94 | chooses Blowfish hashing; see below for more information. | ||
95 | .Ss Extended crypt | ||
96 | The | ||
97 | .Ar key | ||
98 | is divided into groups of 8 characters (the last group is null-padded) | ||
99 | and the low-order 7 bits of each character (56 bits per group) are | ||
100 | used to form the DES key as follows: | ||
101 | the first group of 56 bits becomes the initial DES key. | ||
102 | For each additional group, the XOR of the encryption of the current DES | ||
103 | key with itself and the group bits becomes the next DES key. | ||
104 | .Pp | ||
105 | The setting is a 9-character array consisting of an underscore followed | ||
106 | by 4 bytes of iteration count and 4 bytes of salt. | ||
107 | These are encoded as printable characters, 6 bits per character, | ||
108 | least significant character first. | ||
109 | The values 0 to 63 are encoded as | ||
110 | .Dq \&./0-9A-Za-z . | ||
111 | This allows 24 bits for both | ||
112 | .Fa count | ||
113 | and | ||
114 | .Fa salt . | ||
115 | .Ss "MD5" crypt | ||
116 | For | ||
117 | .Tn MD5 | ||
118 | crypt the version number, | ||
119 | .Fa salt | ||
120 | and the hashed password are separated by the | ||
121 | .Ql $ | ||
122 | character. | ||
123 | The maximum length of a password is limited by | ||
124 | the length counter of the MD5 context, which is about | ||
125 | 2**64. | ||
126 | A valid MD5 password entry looks like this: | ||
127 | .Pp | ||
128 | .Dq $1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1 . | ||
129 | .Pp | ||
130 | The whole MD5 password string is passed as | ||
131 | .Fa setting | ||
132 | for interpretation. | ||
133 | .Ss "Blowfish" crypt | ||
134 | The | ||
135 | .Tn Blowfish | ||
136 | version of crypt has 128 bits of | ||
137 | .Fa salt | ||
138 | in order to make building dictionaries of common passwords space consuming. | ||
139 | The initial state of the | ||
140 | .Tn Blowfish | ||
141 | cipher is expanded using the | ||
142 | .Fa salt | ||
143 | and the | ||
144 | .Fa password | ||
145 | repeating the process a variable number of rounds, which is encoded in | ||
146 | the password string. | ||
147 | The maximum password length is 72. | ||
148 | The final Blowfish password entry is created by encrypting the string | ||
149 | .Pp | ||
150 | .Dq OrpheanBeholderScryDoubt | ||
151 | .Pp | ||
152 | with the | ||
153 | .Tn Blowfish | ||
154 | state 64 times. | ||
155 | .Pp | ||
156 | The version number, the logarithm of the number of rounds and | ||
157 | the concatenation of salt and hashed password are separated by the | ||
158 | .Ql $ | ||
159 | character. | ||
160 | An encoded | ||
161 | .Sq 8 | ||
162 | would specify 256 rounds. | ||
163 | A valid Blowfish password looks like this: | ||
164 | .Pp | ||
165 | .Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC . | ||
166 | .Pp | ||
167 | The whole Blowfish password string is passed as | ||
168 | .Fa setting | ||
169 | for interpretation. | ||
170 | .Ss "Traditional" crypt | ||
171 | The first 8 bytes of the key are null-padded, and the low-order 7 bits of | ||
172 | each character is used to form the 56-bit | ||
173 | .Tn DES | ||
174 | key. | ||
175 | .Pp | ||
176 | The setting is a 2-character array of the ASCII-encoded salt. | ||
177 | Thus only 12 bits of | ||
178 | .Fa salt | ||
179 | are used. | ||
180 | .Fa count | ||
181 | is set to 25. | ||
182 | .Ss DES Algorithm | ||
183 | The | ||
184 | .Fa salt | ||
185 | introduces disorder in the | ||
186 | .Tn DES | ||
187 | algorithm in one of 16777216 or 4096 possible ways | ||
188 | (i.e., with 24 or 12 bits: if bit | ||
189 | .Em i | ||
190 | of the | ||
191 | .Ar salt | ||
192 | is set, then bits | ||
193 | .Em i | ||
194 | and | ||
195 | .Em i+24 | ||
196 | are swapped in the | ||
197 | .Tn DES | ||
198 | E-box output). | ||
199 | .Pp | ||
200 | The DES key is used to encrypt a 64-bit constant using | ||
201 | .Ar count | ||
202 | iterations of | ||
203 | .Tn DES . | ||
204 | The value returned is a | ||
205 | .Dv NUL Ns -terminated | ||
206 | string, 20 or 13 bytes (plus NUL) in length, consisting of the | ||
207 | .Ar setting | ||
208 | followed by the encoded 64-bit encryption. | ||
209 | .Pp | ||
210 | The functions | ||
211 | .Fn encrypt , | ||
212 | .Fn setkey , | ||
213 | .Fn des_setkey , | ||
214 | and | ||
215 | .Fn des_cipher | ||
216 | provide access to the | ||
217 | .Tn DES | ||
218 | algorithm itself. | ||
219 | .Fn setkey | ||
220 | is passed a 64-byte array of binary values (numeric 0 or 1). | ||
221 | A 56-bit key is extracted from this array by dividing the | ||
222 | array into groups of 8, and ignoring the last bit in each group. | ||
223 | That bit is reserved for a byte parity check by DES, but is ignored | ||
224 | by these functions. | ||
225 | .Pp | ||
226 | The | ||
227 | .Fa block | ||
228 | argument to | ||
229 | .Fn encrypt | ||
230 | is also a 64-byte array of binary values. | ||
231 | If the value of | ||
232 | .Fa flag | ||
233 | is 0, | ||
234 | .Fa block | ||
235 | is encrypted otherwise it is decrypted. | ||
236 | The result is returned in the original array | ||
237 | .Fa block | ||
238 | after using the key specified by | ||
239 | .Fn setkey | ||
240 | to process it. | ||
241 | .Pp | ||
242 | The argument to | ||
243 | .Fn des_setkey | ||
244 | is a character array of length 8. | ||
245 | The least significant bit (the parity bit) in each character is ignored, | ||
246 | and the remaining bits are concatenated to form a 56-bit key. | ||
247 | The function | ||
248 | .Fn des_cipher | ||
249 | encrypts (or decrypts if | ||
250 | .Fa count | ||
251 | is negative) the 64-bits stored in the 8 characters at | ||
252 | .Fa in | ||
253 | using | ||
254 | .Xr abs 3 | ||
255 | of | ||
256 | .Fa count | ||
257 | iterations of | ||
258 | .Tn DES | ||
259 | and stores the 64-bit result in the 8 characters at | ||
260 | .Fa out | ||
261 | (which may be the same as | ||
262 | .Fa in ) . | ||
263 | The | ||
264 | .Fa salt | ||
265 | specifies perturbations to the | ||
266 | .Tn DES | ||
267 | E-box output as described above. | ||
268 | .Pp | ||
269 | The | ||
270 | .Fn crypt , | ||
271 | .Fn setkey , | ||
272 | and | ||
273 | .Fn des_setkey | ||
274 | functions all manipulate the same key space. | ||
275 | .Sh RETURN VALUES | ||
276 | The function | ||
277 | .Fn crypt | ||
278 | returns a pointer to the encrypted value on success, and | ||
279 | .Dv NULL | ||
280 | on failure. | ||
281 | The functions | ||
282 | .Fn setkey , | ||
283 | .Fn encrypt , | ||
284 | .Fn des_setkey , | ||
285 | and | ||
286 | .Fn des_cipher | ||
287 | return 0 on success and 1 on failure. | ||
288 | .Sh SEE ALSO | ||
289 | .Xr login 1 , | ||
290 | .Xr passwd 1 , | ||
291 | .Xr blowfish 3 , | ||
292 | .Xr getpass 3 , | ||
293 | .Xr md5 3 , | ||
294 | .Xr passwd 5 | ||
295 | .Sh HISTORY | ||
296 | A rotor-based | ||
297 | .Fn crypt | ||
298 | function appeared in | ||
299 | .At v3 . | ||
300 | The current style | ||
301 | .Fn crypt | ||
302 | first appeared in | ||
303 | .At v7 . | ||
304 | .Pp | ||
305 | This library (FreeSec 1.0) was developed outside the United States of America | ||
306 | as an unencumbered replacement for the U.S.-only libcrypt encryption | ||
307 | library. | ||
308 | Programs linked against the | ||
309 | .Fn crypt | ||
310 | interface may be exported from the U.S.A. only if they use | ||
311 | .Fn crypt | ||
312 | solely for authentication purposes and avoid use of | ||
313 | the other programmer interfaces listed above. | ||
314 | Special care has been taken | ||
315 | in the library so that programs which only use the | ||
316 | .Fn crypt | ||
317 | interface do not pull in the other components. | ||
318 | .Sh AUTHORS | ||
319 | .An David Burren Aq davidb@werj.com.au | ||
320 | .Sh BUGS | ||
321 | The | ||
322 | .Fn crypt | ||
323 | function returns a pointer to static data, and subsequent calls to | ||
324 | .Fn crypt | ||
325 | will modify the same object. | ||