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