Commit | Line | Data |
---|---|---|
74155b62 KB |
1 | .\" Copyright (c) 1989, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
7d129e3b | 3 | .\" |
ae59e04c | 4 | .\" %sccs.include.redist.man% |
7d129e3b | 5 | .\" |
74155b62 | 6 | .\" @(#)crypt.3 8.1 (Berkeley) %G% |
0ce943ed | 7 | .\" |
ae59e04c CL |
8 | .Dd |
9 | .Dt CRYPT 3 | |
10 | .Os | |
11 | .Sh NAME | |
12 | .Nm crypt , | |
13 | .Nm setkey , | |
14 | .Nm encrypt , | |
15 | .Nm des_setkey , | |
16 | .Nm des_cipher | |
17 | .Nd DES encryption | |
18 | .Sh SYNOPSIS | |
19 | .Ft char | |
20 | .Fn *crypt "const char *key" "const char *setting" | |
6d6f8196 | 21 | .Ft int |
ae59e04c | 22 | .Fn setkey "char *key" |
6d6f8196 | 23 | .Ft int |
ae59e04c | 24 | .Fn encrypt "char *block" "int flag" |
6d6f8196 | 25 | .Ft int |
ae59e04c | 26 | .Fn des_setkey "const char *key" |
6d6f8196 | 27 | .Ft int |
4d7f51d0 | 28 | .Fn des_cipher "const char *in" "char *out" "long salt" "int count" |
ae59e04c CL |
29 | .Sh DESCRIPTION |
30 | The | |
31 | .Xr crypt | |
32 | function | |
33 | performs password encryption. | |
34 | It is derived from the | |
35 | .Tn NBS | |
36 | Data Encryption Standard. | |
37 | Additional code has been added to deter | |
38 | key search attempts. | |
39 | The first argument to | |
40 | .Nm crypt | |
41 | is | |
42 | a | |
43 | .Dv NUL Ns -terminated | |
4d7f51d0 | 44 | string (normally a password typed by a user). |
7d129e3b KB |
45 | The second is a character array, 9 bytes in length, consisting of an |
46 | underscore (``_'') followed by 4 bytes of iteration count and 4 bytes | |
47 | of salt. | |
48 | Both the iteration | |
ae59e04c | 49 | .Fa count |
7d129e3b | 50 | and the |
ae59e04c | 51 | .Fa salt |
b7db8405 | 52 | are encoded with 6 bits per character, least significant bits first. |
7d129e3b KB |
53 | The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'', |
54 | respectively. | |
b7db8405 | 55 | .Pp |
0ce943ed | 56 | The |
ae59e04c CL |
57 | .Fa salt |
58 | is used to induce disorder in to the | |
59 | .Tn DES | |
60 | algorithm | |
61 | in one of 16777216 | |
62 | possible ways | |
7d129e3b | 63 | (specifically, if bit |
b7db8405 | 64 | .Em i |
7d129e3b | 65 | of the |
ae59e04c | 66 | .Ar salt |
7d129e3b | 67 | is set then bits |
b7db8405 | 68 | .Em i |
7d129e3b | 69 | and |
b7db8405 | 70 | .Em i+24 |
ae59e04c CL |
71 | are swapped in the |
72 | .Tn DES | |
73 | ``E'' box output). | |
b7db8405 | 74 | The |
ae59e04c | 75 | .Ar key |
b7db8405 KB |
76 | is divided into groups of 8 characters (a short final group is null-padded) |
77 | and the low-order 7 bits of each each character (56 bits per group) are | |
78 | used to form the DES key as follows: the first group of 56 bits becomes the | |
79 | initial DES key. | |
80 | For each additional group, the XOR of the group bits and the encryption of | |
81 | the DES key with itself becomes the next DES key. | |
82 | Then the final DES key is used to perform | |
ae59e04c | 83 | .Ar count |
7d129e3b | 84 | cumulative encryptions of a 64-bit constant. |
b7db8405 KB |
85 | The value returned is a |
86 | .Dv NUL Ns -terminated | |
87 | string, 20 bytes in length, consisting | |
7d129e3b | 88 | of the |
ae59e04c | 89 | .Ar setting |
7d129e3b | 90 | followed by the encoded 64-bit encryption. |
ae59e04c | 91 | .Pp |
7d129e3b | 92 | For compatibility with historical versions of |
ae59e04c | 93 | .Xr crypt 3 , |
7d129e3b | 94 | the |
ae59e04c | 95 | .Ar setting |
7d129e3b KB |
96 | may consist of 2 bytes of salt, encoded as above, in which case an |
97 | iteration | |
ae59e04c CL |
98 | .Ar count |
99 | of 25 is used, fewer perturbations of | |
100 | .Tn DES | |
101 | are available, at most 8 | |
7d129e3b | 102 | characters of |
ae59e04c | 103 | .Ar key |
b7db8405 KB |
104 | are used, and the returned value is a |
105 | .Dv NUL Ns -terminated | |
106 | string 13 bytes in length. | |
ae59e04c CL |
107 | .Pp |
108 | The | |
109 | functions, | |
110 | .Fn encrypt , | |
111 | .Fn setkey , | |
112 | .Fn des_setkey | |
113 | and | |
114 | .Fn des_cipher | |
115 | allow limited access to the | |
116 | .Tn DES | |
117 | algorithm itself. | |
118 | The | |
119 | .Ar key | |
120 | argument to | |
121 | .Fn setkey | |
122 | is a 64 character array of | |
b7db8405 KB |
123 | binary values (numeric 0 or 1). |
124 | A 56-bit key is derived from this array by dividing the array | |
7d129e3b | 125 | into groups of 8 and ignoring the last bit in each group. |
ae59e04c CL |
126 | .Fa salt |
127 | specifies perturbations to | |
128 | .Tn DES | |
129 | as described above. | |
6d6f8196 KB |
130 | .Pp |
131 | The function | |
132 | .Fn crypt | |
133 | returns a pointer to the encrypted value on success and NULL on failure. | |
134 | The functions | |
135 | .Fn setkey , | |
136 | .Fn encrypt , | |
137 | .Fn des_setkey , | |
138 | and | |
139 | .Fn des_cipher | |
140 | return 0 on success and 1 on failure. | |
141 | Historically, the functions | |
142 | .Fn setkey | |
143 | and | |
144 | .Fn encrypt | |
145 | did not return any value. | |
146 | They have been provided return values primarily to distinguish | |
147 | implementations where hardware support is provided but not | |
148 | available or where the DES encryption is not available due to the | |
149 | usual political silliness. | |
ae59e04c CL |
150 | .Sh SEE ALSO |
151 | .Xr login 1 , | |
152 | .Xr passwd 1 , | |
153 | .Xr getpass 3 , | |
154 | .Xr passwd 5 | |
4d7f51d0 | 155 | .sp |
ae59e04c CL |
156 | .Rs |
157 | .%T "Mathematical Cryptology for Computer Scientists and Mathematicians" | |
158 | .%A Wayne Patterson | |
159 | .%D 1987 | |
160 | .%N ISBN 0-8476-7438-X | |
161 | .Re | |
162 | .Rs | |
163 | .%T "Password Security: A Case History" | |
164 | .%A R. Morris | |
165 | .%A Ken Thompson | |
166 | .%J "Communications of the ACM" | |
167 | .%V vol. 22 | |
168 | .%P pp. 594-597 | |
169 | .%D Nov. 1979 | |
170 | .Re | |
171 | .Rs | |
172 | .%T "DES will be Totally Insecure within Ten Years" | |
173 | .%A M.E. Hellman | |
174 | .%J "IEEE Spectrum" | |
175 | .%V vol. 16 | |
176 | .%P pp. 32-39 | |
177 | .%D July 1979 | |
178 | .Re | |
179 | .Sh HISTORY | |
903d7e7e | 180 | A rotor-based |
ae59e04c CL |
181 | .Fn crypt |
182 | function appeared in | |
183 | .At v6 . | |
903d7e7e KB |
184 | The current style |
185 | .Fn crypt | |
186 | first appeared in | |
187 | .At v7 . | |
ae59e04c | 188 | .Sh BUGS |
7d129e3b | 189 | Dropping the |
ae59e04c | 190 | .Em least |
7d129e3b | 191 | significant bit in each character of the argument to |
ae59e04c | 192 | .Fn des_setkey |
7d129e3b | 193 | is ridiculous. |
ae59e04c CL |
194 | .Pp |
195 | The | |
196 | .Fn crypt | |
197 | function leaves its result in an internal static object and returns | |
6d6f8196 KB |
198 | a pointer to that object. |
199 | Subsequent calls to | |
ae59e04c CL |
200 | .Fn crypt |
201 | will modify the same object. |