man(7) -> mdoc(7).

1 files changed, 173 insertions, 140 deletions

diff --git a/secure/usr.bin/bdes/bdes.1 b/secure/usr.bin/bdes/bdes.1
index a0ad666..579bbab 100644
--- a/secure/usr.bin/bdes/bdes.1
+++ b/secure/usr.bin/bdes/bdes.1
@@ -35,154 +35,175 @@
 .\"	@(#)bdes.1	8.1 (Berkeley) 6/29/93
 .\" $FreeBSD$
 .\"
-.TH BDES 1 "June 29, 1993"
-.UC 6
-.SH NAME
-bdes \- encrypt/decrypt using the Data Encryption Standard
-.SH SYNOPSIS
-.nf
-.ft B
-bdes [ \-abdp ] [ \-F N ] [ \-f N ] [ \-k key ]
-.ti +5
-[ \-m N ] [ \-o N ] [ \-v vector ]
-.ft R
-.fi
-.SH DESCRIPTION
-.I Bdes
-implements all DES modes of operation described in FIPS PUB 81, 
+.Dd June 29, 1993
+.Dt BDES 1
+.Os
+.Sh NAME
+.Nm bdes
+.Nd "encrypt/decrypt using the Data Encryption Standard"
+.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
+.Nm Bdes
+implements all
+.Tn DES
+modes of operation described in
+.%T "FIPS PUB 81" ,
 including alternative cipher feedback mode and both authentication
 modes.
-.I Bdes
+.Nm Bdes
 reads from the standard input and writes to the standard output.
 By default, the input is encrypted using cipher block chaining mode.
 Using the same key for encryption and decryption preserves plain text.
-.PP
+.Pp
 All modes but the electronic code book mode require an initialization
 vector; if none is supplied, the zero vector is used.
 If no
-.I key
+.Ar key
 is specified on the command line, the user is prompted for one (see
-.IR getpass (3)
+.Xr getpass 3
 for more details).
-.PP
+.Pp
 The options are as follows:
-.TP
-\-a
-The key and initialization vector strings are to be taken as ASCII,
-suppressing the special interpretation given to leading ``0X'', ``0x'',
-``0B'', and ``0b'' characters.
+.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
-.I both
+.Em both
 the key and initialization vector.
-.TP
-\-b
+.It Fl b
 Use electronic code book mode.
-.TP
-\-d
+.It Fl d
 Decrypt the input.
-.TP
-\-F
+.It Fl F Ar N
 Use
-.IR N -bit
+.Ar N Ns \-bit
 alternative cipher feedback mode.
 Currently
-.I N
+.Ar N
 must be a multiple of 7 between 7 and 56 inclusive (this does not conform
 to the alternative CFB mode specification).
-.TP
-\-f
+.It Fl f Ar N
 Use
-.IR N -bit
+.Ar N Ns \-bit
 cipher feedback mode.
 Currently
-.I N
+.Ar N
 must be a multiple of 8 between 8 and 64 inclusive (this does not conform
 to the standard CFB mode specification).
-.TP
-\-k
+.It Fl k Ar key
 Use
-.I key
+.Ar key
 as the cryptographic key.
-.TP
-\-m
+.It Fl m Ar N
 Compute a message authentication code (MAC) of
-.I N
+.Ar N
 bits on the input.
 The value of
-.I N
+.Ar N
 must be between 1 and 64 inclusive; if
-.I N
+.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 cipher block chaining mode or in cipher feedback
 mode.
-.TP
-\-o
+.It Fl o Ar N
 Use
-.IR N -bit
+.Ar N Ns \-bit
 output feedback mode.
 Currently
-.I N
+.Ar N
 must be a multiple of 8 between 8 and 64 inclusive (this does not conform
 to the OFB mode specification).
-.TP
-\-p
+.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 ASCII.
-.TP
-\-v
+It is used only if the key is given in
+.Tn ASCII .
+.It Fl v Ar vector
 Set the initialization vector to
-.IR vector ;
+.Ar vector ;
 the vector is interpreted in the same way as the key.
 The vector is ignored in electronic codebook mode.
-.PP
-The key and initialization vector are taken as sequences of ASCII
+.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 ``0X'' or ``0x'',
+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 ``0B'' or ``0b'',
+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 DES standard, the low-order bit of each character in the
+.Pp
+According to the
+.Tn DES
+standard, the low-order bit of each character in the
 key string is deleted.
-Since most ASCII representations set the high-order bit to 0, simply
+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\u\s-356\s0\d to 2\u\s-348\s0\d keys.
+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
-.I not
-done if the key is given in binary or hex, and can be disabled for ASCII
+.Em not
+done if the key is given in binary or hex, and can be disabled for
+.Tn ASCII
 keys as well.
-.PP
-The DES is considered a very strong cryptosystem, and other than table lookup
+.Pp
+The
+.Tn DES
+is considered a very strong cryptosystem, and other than table lookup
 attacks, key search attacks, and Hellman's time-memory tradeoff (all of which
 are very expensive and time-consuming), no cryptanalytic methods for breaking
-the DES are known in the open literature.
+the
+.Tn DES
+are known in the open literature.
 No doubt the choice of keys and key security are the most vulnerable aspect
 of
-.IR bdes .
-.SH IMPLEMENTATION NOTES
+.Nm .
+.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
+.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,
-.I bdes
+.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.
@@ -197,58 +218,58 @@ 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
+.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 ASCII, the parity bits of the key characters are set
+.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
-.I not
+.Em not
 reset.
 This allows testing using arbitrary bit patterns as keys.
-.PP
+.Pp
 The Sun implementation always uses an initialization vector of 0
 (that is, all zeroes).
 By default,
-.I bdes
+.Nm
 does too, but this may be changed from the command line.
-.SH SEE ALSO
-crypt(3), getpass(3)
-.sp
-.IR "Data Encryption Standard" ,
-Federal Information Processing Standard #46,
-National Bureau of Standards,
-U.S. Department of Commerce,
-Washington DC
-(Jan. 1977)
-.sp
-.IR "DES Modes of Operation" ,
-Federal Information Processing Standard #81,
-National Bureau of Standards,
-U.S. Department of Commerce
-Washington DC
-(Dec. 1980)
-.sp
-Dorothy Denning,
-.IR "Cryptography and Data Security" ,
-Addison-Wesley Publishing Co.,
-Reading, MA
-\(co1982.
-.sp
-Matt Bishop,
-.IR "Implementation Notes on bdes(1)" ,
-Technical Report PCS-TR-91-158,
-Department of Mathematics and Computer Science,
-Dartmouth College,
-Hanover, NH  03755
-(Apr. 1991).
-.SH DISCLAIMER
-.nf
+.Sh SEE ALSO
+.Xr crypt 3 ,
+.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
@@ -260,46 +281,58 @@ 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.
-.fi
-.SH BUGS
-There is a controversy raging over whether the DES will still be secure
+.Ed
+.Sh BUGS
+There is a controversy raging over whether the
+.Tn DES
+will still be secure
 in a few years.
 The advent of special-purpose hardware could reduce the cost of any of the
 methods of attack named above so that they are no longer computationally
 infeasible.
-.PP
+.Pp
 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
-.I bdes
+.Nm
 overwrites its arguments, however, the obvious race cannot currently be
 avoided.
-.PP
+.Pp
 Certain specific keys should be avoided because they introduce potential
 weaknesses; these keys, called the
-.I weak
+.Em weak
 and
-.I semiweak
-keys, are (in hex notation, where p is either 0 or 1, and P is either
-e or f):
-.sp
-.nf
-.in +10n
-.ta \w'0x0p0p0p0p0p0p0p0p\0\0\0'u+5n
-0x0p0p0p0p0p0p0p0p	0x0p1P0p1P0p0P0p0P
-0x0pep0pep0pfp0pfp	0x0pfP0pfP0pfP0pfP
-0x1P0p1P0p0P0p0P0p	0x1P1P1P1P0P0P0P0P
-0x1Pep1Pep0Pfp0Pfp	0x1PfP1PfP0PfP0PfP
-0xep0pep0pfp0pfp0p	0xep1Pep1pfp0Pfp0P
-0xepepepepepepepep	0xepfPepfPfpfPfpfP
-0xfP0pfP0pfP0pfP0p	0xfP1PfP1PfP0PfP0P
-0xfPepfPepfPepfPep	0xfPfPfPfPfPfPfPfP
-.fi
-.in -10n
-.sp
-This is inherent in the DES algorithm (see Moore and Simmons,
-\*(LqCycle structure of the DES with weak and semi-weak keys,\*(Rq
-.I "Advances in Cryptology \- Crypto '86 Proceedings" ,
-Springer-Verlag New York, \(co1987, pp. 9-32.)
+.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