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