diff options
Diffstat (limited to 'secure/usr.bin/bdes/bdes.1')
| -rw-r--r-- | secure/usr.bin/bdes/bdes.1 | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/secure/usr.bin/bdes/bdes.1 b/secure/usr.bin/bdes/bdes.1 new file mode 100644 index 0000000..114cf04 --- /dev/null +++ b/secure/usr.bin/bdes/bdes.1 @@ -0,0 +1,390 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Matt Bishop of Dartmouth College. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)bdes.1 8.1 (Berkeley) 6/29/93 +.\" $FreeBSD$ +.\" +.Dd September 20, 2013 +.Dt BDES 1 +.Os +.Sh NAME +.Nm bdes +.Nd "encrypt / decrypt using the Data Encryption Standard (DES)" +.Sh SYNOPSIS +.Nm +.Op Fl abdp +.Op Fl F Ar N +.Op Fl f Ar N +.Op Fl k Ar key +.Op Fl m Ar N +.Op Fl o Ar N +.Op Fl v Ar vector +.Sh DESCRIPTION +.Bf -symbolic +The DES cipher should no longer be considered secure. +Please consider using a more modern alternative. +.Ef +.Pp +The +.Nm +utility implements all +.Tn DES +modes of operation described in +.%T "FIPS PUB 81" , +including alternative cipher feedback mode and both authentication +modes. +The +.Nm +utility reads from the standard input +and writes to the standard output. +By default, +the input is encrypted +using cipher block chaining (CBC) mode. +Using the same key +for encryption and decryption +preserves plain text. +.Pp +All modes but the electronic code book (ECB) mode +require an initialization vector; +if none is supplied, +the zero vector is used. +If no +.Ar key +is specified on the command line, +the user is prompted for one (see +.Xr getpass 3 +for more details). +.Pp +The options are as follows: +.Bl -tag -width indent +.It Fl a +The key and initialization vector strings +are to be taken as +.Tn ASCII , +suppressing the special interpretation given to leading +.Dq Li 0X , +.Dq Li 0x , +.Dq Li 0B , +and +.Dq Li 0b +characters. +This flag applies to +.Em both +the key and initialization vector. +.It Fl b +Use ECB mode. +.It Fl d +Decrypt the input. +.It Fl F Ar N +Use +.Ar N Ns \-bit +alternative CFB mode. +Currently +.Ar N +must be a multiple of 7 +between 7 and 56 inclusive +(this does not conform to the alternative CFB mode specification). +.It Fl f Ar N +Use +.Ar N Ns \-bit +CFB mode. +Currently +.Ar N +must be a multiple of 8 between 8 and 64 inclusive (this does not conform +to the standard CFB mode specification). +.It Fl k Ar key +Use +.Ar key +as the cryptographic key. +.It Fl m Ar N +Compute a message authentication code (MAC) of +.Ar N +bits on the input. +The value of +.Ar N +must be between 1 and 64 inclusive; if +.Ar N +is not a multiple of 8, +enough 0 bits will be added +to pad the MAC length +to the nearest multiple of 8. +Only the MAC is output. +MACs are only available +in CBC mode +or in CFB mode. +.It Fl o Ar N +Use +.Ar N Ns \-bit +output feedback (OFB) mode. +Currently +.Ar N +must be a multiple of 8 between 8 and 64 inclusive (this does not conform +to the OFB mode specification). +.It Fl p +Disable the resetting of the parity bit. +This flag forces +the parity bit of the key +to be used as typed, +rather than making +each character be of odd parity. +It is used only if the key is given in +.Tn ASCII . +.It Fl v Ar vector +Set the initialization vector to +.Ar vector ; +the vector is interpreted in the same way as the key. +The vector is ignored in ECB mode. +.El +.Pp +The key and initialization vector +are taken as sequences of +.Tn ASCII +characters which are then mapped +into their bit representations. +If either begins with +.Dq Li 0X +or +.Dq Li 0x , +that one is taken +as a sequence of hexadecimal digits +indicating the bit pattern; +if either begins with +.Dq Li 0B +or +.Dq Li 0b , +that one is taken +as a sequence of binary digits +indicating the bit pattern. +In either case, +only the leading 64 bits +of the key or initialization vector +are used, +and if fewer than 64 bits are provided, +enough 0 bits are appended +to pad the key to 64 bits. +.Pp +According to the +.Tn DES +standard, +the low-order bit of each character +in the key string is deleted. +Since most +.Tn ASCII +representations +set the high-order bit to 0, +simply deleting the low-order bit +effectively reduces the size of the key space +from 2^56 to 2^48 keys. +To prevent this, +the high-order bit must be a function +depending in part upon the low-order bit; +so, +the high-order bit is set +to whatever value gives odd parity. +This preserves the key space size. +Note this resetting of the parity bit is +.Em not +done if the key +is given in binary or hex, +and can be disabled for +.Tn ASCII +keys as well. +.Sh IMPLEMENTATION NOTES +For implementors wishing to write +software compatible with this program, +the following notes are provided. +This software is believed +to be compatible with the implementation +of the data encryption standard +distributed by Sun Microsystems, Inc. +.Pp +In the ECB and CBC modes, +plaintext is encrypted in units of 64 bits +(8 bytes, also called a block). +To ensure that the plaintext file +is encrypted correctly, +.Nm +will (internally) append from 1 to 8 bytes, +the last byte containing an integer +stating how many bytes of that final block +are from the plaintext file, +and encrypt the resulting block. +Hence, +when decrypting, +the last block may contain from 0 to 7 characters +present in the plaintext file, +and the last byte tells how many. +Note that if during decryption +the last byte of the file +does not contain an integer between 0 and 7, +either the file has been corrupted +or an incorrect key has been given. +A similar mechanism is used +for the OFB and CFB modes, +except that those +simply require the length of the input +to be a multiple of the mode size, +and the final byte contains an integer +between 0 and one less than the number +of bytes being used as the mode. +(This was another reason +that the mode size must be +a multiple of 8 for those modes.) +.Pp +Unlike Sun's implementation, +unused bytes of that last block +are not filled with random data, +but instead contain +what was in those byte positions +in the preceding block. +This is quicker and more portable, +and does not weaken the encryption significantly. +.Pp +If the key is entered in +.Tn ASCII , +the parity bits of the key characters +are set so that each key character +is of odd parity. +Unlike Sun's implementation, +it is possible to enter binary or hexadecimal +keys on the command line, +and if this is done, +the parity bits are +.Em not +reset. +This allows testing +using arbitrary bit patterns as keys. +.Pp +The Sun implementation +always uses an initialization vector of 0 +(that is, all zeroes). +By default, +.Nm +does too, +but this may be changed +from the command line. +.Sh SEE ALSO +.Xr getpass 3 +.Rs +.%T "Data Encryption Standard" +.%R "Federal Information Processing Standard #46" +.%Q "National Bureau of Standards, U.S. Department of Commerce, Washington DC" +.%D "January 1977" +.Re +.Rs +.%T "DES Modes of Operation" +.%R "Federal Information Processing Standard #81" +.%Q "National Bureau of Standards, U.S. Department of Commerce, Washington DC" +.%D "December 1980" +.Re +.Rs +.%A "Dorothy Denning" +.%B "Cryptography and Data Security" +.%Q "Addison-Wesley Publishing Co., Reading, MA" +.%D 1982 +.Re +.Rs +.%A "Matt Bishop" +.%T "Implementation Notes on bdes(1)" +.%R "Technical Report PCS-TR-91-158" +.%Q "Department of Mathematics and Computer Science, Dartmouth College, Hanover, NH 03755" +.%D "April 1991" +.Re +.Sh DISCLAIMER +.Bd -literal +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. +.Ed +.Sh BUGS +As the key or key schedule +is stored in memory, +the encryption can be +compromised if memory is readable. +Additionally, +programs which display programs' arguments +may compromise the key and initialization vector, +if they are specified on the command line. +To avoid this +.Nm +overwrites its arguments, +however, +the obvious race +cannot currently be avoided. +.Pp +Certain specific keys +should be avoided +because they introduce +potential weaknesses; +these keys, +called the +.Em weak +and +.Em semiweak +keys, are (in hex notation, where +.Ar p +is either 0 or 1, and +.Ar P +is either +.Ql e +or +.Ql f ) : +.Bl -column "0x0p0p0p0p0p0p0p0p" -offset indent +.It "0x0p0p0p0p0p0p0p0p 0x0p1P0p1P0p0P0p0P" +.It "0x0pep0pep0pfp0pfp 0x0pfP0pfP0pfP0pfP" +.It "0x1P0p1P0p0P0p0P0p 0x1P1P1P1P0P0P0P0P" +.It "0x1Pep1Pep0Pfp0Pfp 0x1PfP1PfP0PfP0PfP" +.It "0xep0pep0pfp0pfp0p 0xep1Pep1pfp0Pfp0P" +.It "0xepepepepepepepep 0xepfPepfPfpfPfpfP" +.It "0xfP0pfP0pfP0pfP0p 0xfP1PfP1PfP0PfP0P" +.It "0xfPepfPepfPepfPep 0xfPfPfPfPfPfPfPfP" +.El +.Pp +This is inherent in the +.Tn DES +algorithm; +see +.Rs +.%A Moore +.%A Simmons +.%T "Cycle structure of the DES with weak and semi-weak keys" +.%B "Advances in Cryptology \- Crypto '86 Proceedings" +.%Q "Springer-Verlag New York" +.%D 1987 +.%P "pp. 9-32" +.Re |
