Commit | Line | Data |
---|---|---|
74155b62 KB |
1 | .\" Copyright (c) 1989, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
7d129e3b | 3 | .\" |
ad787160 C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
7d129e3b | 19 | .\" |
ad787160 C |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. | |
0ce943ed | 31 | .\" |
ed554bc5 | 32 | .\" @(#)crypt.3 8.2 (Berkeley) 12/11/93 |
ad787160 | 33 | .\" |
ed554bc5 | 34 | .Dd December 11, 1993 |
ae59e04c CL |
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 | .Nd DES encryption | |
44 | .Sh SYNOPSIS | |
45 | .Ft char | |
46 | .Fn *crypt "const char *key" "const char *setting" | |
6d6f8196 | 47 | .Ft int |
ae59e04c | 48 | .Fn setkey "char *key" |
6d6f8196 | 49 | .Ft int |
ae59e04c | 50 | .Fn encrypt "char *block" "int flag" |
6d6f8196 | 51 | .Ft int |
ae59e04c | 52 | .Fn des_setkey "const char *key" |
6d6f8196 | 53 | .Ft int |
4d7f51d0 | 54 | .Fn des_cipher "const char *in" "char *out" "long salt" "int count" |
ae59e04c CL |
55 | .Sh DESCRIPTION |
56 | The | |
57 | .Xr crypt | |
58 | function | |
59 | performs password encryption. | |
60 | It is derived from the | |
61 | .Tn NBS | |
62 | Data Encryption Standard. | |
63 | Additional code has been added to deter | |
64 | key search attempts. | |
65 | The first argument to | |
66 | .Nm crypt | |
67 | is | |
68 | a | |
69 | .Dv NUL Ns -terminated | |
4d7f51d0 | 70 | string (normally a password typed by a user). |
7d129e3b KB |
71 | The second is a character array, 9 bytes in length, consisting of an |
72 | underscore (``_'') followed by 4 bytes of iteration count and 4 bytes | |
73 | of salt. | |
74 | Both the iteration | |
ae59e04c | 75 | .Fa count |
7d129e3b | 76 | and the |
ae59e04c | 77 | .Fa salt |
b7db8405 | 78 | are encoded with 6 bits per character, least significant bits first. |
7d129e3b KB |
79 | The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'', |
80 | respectively. | |
b7db8405 | 81 | .Pp |
0ce943ed | 82 | The |
ae59e04c CL |
83 | .Fa salt |
84 | is used to induce disorder in to the | |
85 | .Tn DES | |
86 | algorithm | |
87 | in one of 16777216 | |
88 | possible ways | |
7d129e3b | 89 | (specifically, if bit |
b7db8405 | 90 | .Em i |
7d129e3b | 91 | of the |
ae59e04c | 92 | .Ar salt |
7d129e3b | 93 | is set then bits |
b7db8405 | 94 | .Em i |
7d129e3b | 95 | and |
b7db8405 | 96 | .Em i+24 |
ae59e04c CL |
97 | are swapped in the |
98 | .Tn DES | |
99 | ``E'' box output). | |
b7db8405 | 100 | The |
ae59e04c | 101 | .Ar key |
b7db8405 | 102 | is divided into groups of 8 characters (a short final group is null-padded) |
653ba8b6 | 103 | and the low-order 7 bits of each character (56 bits per group) are |
b7db8405 KB |
104 | used to form the DES key as follows: the first group of 56 bits becomes the |
105 | initial DES key. | |
106 | For each additional group, the XOR of the group bits and the encryption of | |
107 | the DES key with itself becomes the next DES key. | |
108 | Then the final DES key is used to perform | |
ae59e04c | 109 | .Ar count |
7d129e3b | 110 | cumulative encryptions of a 64-bit constant. |
b7db8405 KB |
111 | The value returned is a |
112 | .Dv NUL Ns -terminated | |
113 | string, 20 bytes in length, consisting | |
7d129e3b | 114 | of the |
ae59e04c | 115 | .Ar setting |
7d129e3b | 116 | followed by the encoded 64-bit encryption. |
ae59e04c | 117 | .Pp |
7d129e3b | 118 | For compatibility with historical versions of |
ae59e04c | 119 | .Xr crypt 3 , |
7d129e3b | 120 | the |
ae59e04c | 121 | .Ar setting |
7d129e3b KB |
122 | may consist of 2 bytes of salt, encoded as above, in which case an |
123 | iteration | |
ae59e04c CL |
124 | .Ar count |
125 | of 25 is used, fewer perturbations of | |
126 | .Tn DES | |
127 | are available, at most 8 | |
7d129e3b | 128 | characters of |
ae59e04c | 129 | .Ar key |
b7db8405 KB |
130 | are used, and the returned value is a |
131 | .Dv NUL Ns -terminated | |
132 | string 13 bytes in length. | |
ae59e04c CL |
133 | .Pp |
134 | The | |
135 | functions, | |
136 | .Fn encrypt , | |
137 | .Fn setkey , | |
138 | .Fn des_setkey | |
139 | and | |
140 | .Fn des_cipher | |
141 | allow limited access to the | |
142 | .Tn DES | |
143 | algorithm itself. | |
144 | The | |
145 | .Ar key | |
146 | argument to | |
147 | .Fn setkey | |
148 | is a 64 character array of | |
b7db8405 KB |
149 | binary values (numeric 0 or 1). |
150 | A 56-bit key is derived from this array by dividing the array | |
7d129e3b | 151 | into groups of 8 and ignoring the last bit in each group. |
ad787160 C |
152 | .Pp |
153 | The | |
154 | .Fn encrypt | |
155 | argument | |
156 | .Fa block | |
157 | is also a 64 character array of | |
158 | binary values. | |
159 | If the value of | |
160 | .Fa flag | |
161 | is 0, | |
162 | the argument | |
163 | .Fa block | |
164 | is encrypted, otherwise it | |
165 | is decrypted. | |
166 | The encryption or decryption is returned in the original | |
167 | array | |
168 | .Fa block | |
169 | after using the | |
170 | key specified | |
171 | by | |
172 | .Fn setkey | |
173 | to process it. | |
174 | .Pp | |
175 | The | |
176 | .Fn des_setkey | |
177 | and | |
178 | .Fn des_cipher | |
179 | functions are faster but less portable than | |
180 | .Fn setkey | |
181 | and | |
182 | .Fn encrypt . | |
183 | The argument to | |
184 | .Fn des_setkey | |
185 | is a character array of length 8. | |
186 | The | |
187 | .Em least | |
188 | significant bit in each character is ignored and the next 7 bits of each | |
189 | character are concatenated to yield a 56-bit key. | |
190 | The function | |
191 | .Fn des_cipher | |
192 | encrypts (or decrypts if | |
193 | .Fa count | |
194 | is negative) the 64-bits stored in the 8 characters at | |
195 | .Fa in | |
196 | using | |
197 | .Xr abs 3 | |
198 | of | |
199 | .Fa count | |
200 | iterations of | |
201 | .Tn DES | |
202 | and stores the 64-bit result in the 8 characters at | |
203 | .Fa out . | |
204 | The | |
ae59e04c CL |
205 | .Fa salt |
206 | specifies perturbations to | |
207 | .Tn DES | |
208 | as described above. | |
6d6f8196 KB |
209 | .Pp |
210 | The function | |
211 | .Fn crypt | |
212 | returns a pointer to the encrypted value on success and NULL on failure. | |
213 | The functions | |
214 | .Fn setkey , | |
215 | .Fn encrypt , | |
216 | .Fn des_setkey , | |
217 | and | |
218 | .Fn des_cipher | |
219 | return 0 on success and 1 on failure. | |
220 | Historically, the functions | |
221 | .Fn setkey | |
222 | and | |
223 | .Fn encrypt | |
224 | did not return any value. | |
225 | They have been provided return values primarily to distinguish | |
226 | implementations where hardware support is provided but not | |
227 | available or where the DES encryption is not available due to the | |
228 | usual political silliness. | |
ae59e04c CL |
229 | .Sh SEE ALSO |
230 | .Xr login 1 , | |
231 | .Xr passwd 1 , | |
232 | .Xr getpass 3 , | |
233 | .Xr passwd 5 | |
4d7f51d0 | 234 | .sp |
ae59e04c CL |
235 | .Rs |
236 | .%T "Mathematical Cryptology for Computer Scientists and Mathematicians" | |
237 | .%A Wayne Patterson | |
238 | .%D 1987 | |
239 | .%N ISBN 0-8476-7438-X | |
240 | .Re | |
241 | .Rs | |
242 | .%T "Password Security: A Case History" | |
243 | .%A R. Morris | |
244 | .%A Ken Thompson | |
245 | .%J "Communications of the ACM" | |
246 | .%V vol. 22 | |
247 | .%P pp. 594-597 | |
248 | .%D Nov. 1979 | |
249 | .Re | |
250 | .Rs | |
251 | .%T "DES will be Totally Insecure within Ten Years" | |
252 | .%A M.E. Hellman | |
253 | .%J "IEEE Spectrum" | |
254 | .%V vol. 16 | |
255 | .%P pp. 32-39 | |
256 | .%D July 1979 | |
257 | .Re | |
258 | .Sh HISTORY | |
903d7e7e | 259 | A rotor-based |
ae59e04c CL |
260 | .Fn crypt |
261 | function appeared in | |
262 | .At v6 . | |
903d7e7e KB |
263 | The current style |
264 | .Fn crypt | |
265 | first appeared in | |
266 | .At v7 . | |
ae59e04c | 267 | .Sh BUGS |
7d129e3b | 268 | Dropping the |
ae59e04c | 269 | .Em least |
7d129e3b | 270 | significant bit in each character of the argument to |
ae59e04c | 271 | .Fn des_setkey |
7d129e3b | 272 | is ridiculous. |
ae59e04c CL |
273 | .Pp |
274 | The | |
275 | .Fn crypt | |
276 | function leaves its result in an internal static object and returns | |
6d6f8196 KB |
277 | a pointer to that object. |
278 | Subsequent calls to | |
ae59e04c CL |
279 | .Fn crypt |
280 | will modify the same object. |