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