| blob | 1c2876b288d57d7f6592fb1dea5b6492db2ef3f4 |
1 .\" Copyright (c) 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Matt Bishop of Dartmouth College.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" SUCH DAMAGE.
34 .\"
35 .\" @(#)bdes.1 8.1 (Berkeley) 6/29/93
36 .\" $FreeBSD: src/secure/usr.bin/bdes/bdes.1,v 1.2.8.2 2001/01/16 15:36:41 ru Exp $
37 .\" $DragonFly: src/secure/usr.bin/bdes/bdes.1,v 1.2 2003/06/17 04:27:48 dillon Exp $
38 .\"
39 .Dd June 29, 1993
40 .Dt BDES 1
41 .Os
42 .Sh NAME
43 .Nm bdes
44 .Nd "encrypt/decrypt using the Data Encryption Standard"
45 .Sh SYNOPSIS
46 .Nm
47 .Op Fl abdp
48 .Op Fl F Ar N
49 .Op Fl f Ar N
50 .Op Fl k Ar key
51 .Op Fl m Ar N
52 .Op Fl o Ar N
53 .Op Fl v Ar vector
54 .Sh DESCRIPTION
55 .Nm Bdes
56 implements all
57 .Tn DES
58 modes of operation described in
59 .%T "FIPS PUB 81" ,
60 including alternative cipher feedback mode and both authentication
61 modes.
62 .Nm Bdes
63 reads from the standard input and writes to the standard output.
64 By default, the input is encrypted using cipher block chaining mode.
65 Using the same key for encryption and decryption preserves plain text.
66 .Pp
67 All modes but the electronic code book mode require an initialization
68 vector; if none is supplied, the zero vector is used.
69 If no
70 .Ar key
71 is specified on the command line, the user is prompted for one (see
72 .Xr getpass 3
73 for more details).
74 .Pp
75 The options are as follows:
76 .Bl -tag -width indent
77 .It Fl a
78 The key and initialization vector strings are to be taken as
79 .Tn ASCII ,
80 suppressing the special interpretation given to leading
81 .Dq Li 0X ,
82 .Dq Li 0x ,
83 .Dq Li 0B ,
84 and
85 .Dq Li 0b
86 characters.
87 This flag applies to
88 .Em both
89 the key and initialization vector.
90 .It Fl b
91 Use electronic code book mode.
92 .It Fl d
93 Decrypt the input.
94 .It Fl F Ar N
95 Use
96 .Ar N Ns \-bit
97 alternative cipher feedback mode.
98 Currently
99 .Ar N
100 must be a multiple of 7 between 7 and 56 inclusive (this does not conform
101 to the alternative CFB mode specification).
102 .It Fl f Ar N
103 Use
104 .Ar N Ns \-bit
105 cipher feedback mode.
106 Currently
107 .Ar N
108 must be a multiple of 8 between 8 and 64 inclusive (this does not conform
109 to the standard CFB mode specification).
110 .It Fl k Ar key
111 Use
112 .Ar key
113 as the cryptographic key.
114 .It Fl m Ar N
115 Compute a message authentication code (MAC) of
116 .Ar N
117 bits on the input.
118 The value of
119 .Ar N
120 must be between 1 and 64 inclusive; if
121 .Ar N
122 is not a multiple of 8, enough 0 bits will be added to pad the MAC length
123 to the nearest multiple of 8.
124 Only the MAC is output.
125 MACs are only available in cipher block chaining mode or in cipher feedback
126 mode.
127 .It Fl o Ar N
128 Use
129 .Ar N Ns \-bit
130 output feedback mode.
131 Currently
132 .Ar N
133 must be a multiple of 8 between 8 and 64 inclusive (this does not conform
134 to the OFB mode specification).
135 .It Fl p
136 Disable the resetting of the parity bit.
137 This flag forces the parity bit of the key to be used as typed, rather than
138 making each character be of odd parity.
139 It is used only if the key is given in
140 .Tn ASCII .
141 .It Fl v Ar vector
142 Set the initialization vector to
143 .Ar vector ;
144 the vector is interpreted in the same way as the key.
145 The vector is ignored in electronic codebook mode.
146 .El
147 .Pp
148 The key and initialization vector are taken as sequences of
149 .Tn ASCII
150 characters which are then mapped into their bit representations.
151 If either begins with
152 .Dq Li 0X
153 or
154 .Dq Li 0x ,
155 that one is taken as a sequence of hexadecimal digits indicating the
156 bit pattern;
157 if either begins with
158 .Dq Li 0B
159 or
160 .Dq Li 0b ,
161 that one is taken as a sequence of binary digits indicating the bit pattern.
162 In either case,
163 only the leading 64 bits of the key or initialization vector
164 are used,
165 and if fewer than 64 bits are provided, enough 0 bits are appended
166 to pad the key to 64 bits.
167 .Pp
168 According to the
169 .Tn DES
170 standard, the low-order bit of each character in the
171 key string is deleted.
172 Since most
173 .Tn ASCII
174 representations set the high-order bit to 0, simply
175 deleting the low-order bit effectively reduces the size of the key space
176 from 2^56 to 2^48 keys.
177 To prevent this, the high-order bit must be a function depending in part
178 upon the low-order bit; so, the high-order bit is set to whatever value
179 gives odd parity.
180 This preserves the key space size.
181 Note this resetting of the parity bit is
182 .Em not
183 done if the key is given in binary or hex, and can be disabled for
184 .Tn ASCII
185 keys as well.
186 .Pp
187 The
188 .Tn DES
189 is considered a very strong cryptosystem, and other than table lookup
190 attacks, key search attacks, and Hellman's time-memory tradeoff (all of which
191 are very expensive and time-consuming), no cryptanalytic methods for breaking
192 the
193 .Tn DES
194 are known in the open literature.
195 No doubt the choice of keys and key security are the most vulnerable aspect
196 of
197 .Nm .
198 .Sh IMPLEMENTATION NOTES
199 For implementors wishing to write software compatible with this program,
200 the following notes are provided.
201 This software is believed to be compatible with the implementation of the
202 data encryption standard distributed by Sun Microsystems, Inc.
203 .Pp
204 In the ECB and CBC modes, plaintext is encrypted in units of 64 bits (8 bytes,
205 also called a block).
206 To ensure that the plaintext file is encrypted correctly,
207 .Nm
208 will (internally) append from 1 to 8 bytes, the last byte containing an
209 integer stating how many bytes of that final block are from the plaintext
210 file, and encrypt the resulting block.
211 Hence, when decrypting, the last block may contain from 0 to 7 characters
212 present in the plaintext file, and the last byte tells how many.
213 Note that if during decryption the last byte of the file does not contain an
214 integer between 0 and 7, either the file has been corrupted or an incorrect
215 key has been given.
216 A similar mechanism is used for the OFB and CFB modes, except that those
217 simply require the length of the input to be a multiple of the mode size,
218 and the final byte contains an integer between 0 and one less than the number
219 of bytes being used as the mode.
220 (This was another reason that the mode size must be a multiple of 8 for those
221 modes.)
222 .Pp
223 Unlike Sun's implementation, unused bytes of that last block are not filled
224 with random data, but instead contain what was in those byte positions in
225 the preceding block.
226 This is quicker and more portable, and does not weaken the encryption
227 significantly.
228 .Pp
229 If the key is entered in
230 .Tn ASCII ,
231 the parity bits of the key characters are set
232 so that each key character is of odd parity.
233 Unlike Sun's implementation, it is possible to enter binary or hexadecimal
234 keys on the command line, and if this is done, the parity bits are
235 .Em not
236 reset.
237 This allows testing using arbitrary bit patterns as keys.
238 .Pp
239 The Sun implementation always uses an initialization vector of 0
240 (that is, all zeroes).
241 By default,
242 .Nm
243 does too, but this may be changed from the command line.
244 .Sh SEE ALSO
245 .Xr crypt 3 ,
246 .Xr getpass 3
247 .Rs
248 .%T "Data Encryption Standard"
249 .%R "Federal Information Processing Standard #46"
250 .%Q "National Bureau of Standards, U.S. Department of Commerce, Washington DC"
251 .%D "January 1977"
252 .Re
253 .Rs
254 .%T "DES Modes of Operation"
255 .%R "Federal Information Processing Standard #81"
256 .%Q "National Bureau of Standards, U.S. Department of Commerce, Washington DC"
257 .%D "December 1980"
258 .Re
259 .Rs
260 .%A "Dorothy Denning"
261 .%B "Cryptography and Data Security"
262 .%Q "Addison-Wesley Publishing Co., Reading, MA"
263 .%D 1982
264 .Re
265 .Rs
266 .%A "Matt Bishop"
267 .%T "Implementation Notes on bdes(1)"
268 .%R "Technical Report PCS-TR-91-158"
269 .%Q "Department of Mathematics and Computer Science, Dartmouth College, Hanover, NH 03755"
270 .%D "April 1991"
271 .Re
272 .Sh DISCLAIMER
273 .Bd -literal
274 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
275 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
276 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
277 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
278 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
279 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
280 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
281 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
282 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
283 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
284 SUCH DAMAGE.
285 .Ed
286 .Sh BUGS
287 There is a controversy raging over whether the
288 .Tn DES
289 will still be secure
290 in a few years.
291 The advent of special-purpose hardware could reduce the cost of any of the
292 methods of attack named above so that they are no longer computationally
293 infeasible.
294 .Pp
295 As the key or key schedule is stored in memory, the encryption can be
296 compromised if memory is readable.
297 Additionally, programs which display programs' arguments may compromise the
298 key and initialization vector, if they are specified on the command line.
299 To avoid this
300 .Nm
301 overwrites its arguments, however, the obvious race cannot currently be
302 avoided.
303 .Pp
304 Certain specific keys should be avoided because they introduce potential
305 weaknesses; these keys, called the
306 .Em weak
307 and
308 .Em semiweak
309 keys, are (in hex notation, where
310 .Ar p
311 is either 0 or 1, and
312 .Ar P
313 is either
314 .Ql e
315 or
316 .Ql f ) :
317 .Bl -column "0x0p0p0p0p0p0p0p0p" -offset indent
318 .It "0x0p0p0p0p0p0p0p0p 0x0p1P0p1P0p0P0p0P"
319 .It "0x0pep0pep0pfp0pfp 0x0pfP0pfP0pfP0pfP"
320 .It "0x1P0p1P0p0P0p0P0p 0x1P1P1P1P0P0P0P0P"
321 .It "0x1Pep1Pep0Pfp0Pfp 0x1PfP1PfP0PfP0PfP"
322 .It "0xep0pep0pfp0pfp0p 0xep1Pep1pfp0Pfp0P"
323 .It "0xepepepepepepepep 0xepfPepfPfpfPfpfP"
324 .It "0xfP0pfP0pfP0pfP0p 0xfP1PfP1PfP0PfP0P"
325 .It "0xfPepfPepfPepfPep 0xfPfPfPfPfPfPfPfP"
326 .El
327 .Pp
328 This is inherent in the
329 .Tn DES
330 algorithm; see
331 .Rs
332 .%A Moore
333 .%A Simmons
334 .%T "Cycle structure of the DES with weak and semi-weak keys"
335 .%B "Advances in Cryptology \- Crypto '86 Proceedings"
336 .%Q "Springer-Verlag New York"
337 .%D 1987
338 .%P "pp. 9-32"
339 .Re