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