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