secure/usr.bin/bdes/bdes.1

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