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