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