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