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