.ds ]T 4 Dec 90
.ds CP \s-2\(co\f3 Copyright 1990 by David G. Koontz\f1\s+2
.de}F
.ev1
.}E
.if\n()s 'sp |\n(.pu-1v-1p
.if\n()t 'sp |\n(.pu-3v
.ifn 'sp |\n(.pu-4v
.ifn .tl Page %\*(]T
.if\n()s .tl - % -
.if\n()t \{.if o .tl Page %\*(CP\*(]T
.ife .tl \*(]T\*(CPPage % \}
'bp
.ev
..
.de}C
..
.po 1.0i
.nrIN 0.5i
.nr)S 12
.TH \f3DES 1 "" "\s+1\f6/dev/ktz\f1\s-1"
.SH \f3NAME
des \- encrypt/decrypt using fast implementation of NBS DES
.SH \f3SYNOPSIS
.B des
-e \|\(bv \|-d [-n] [-k key \|\(bv \|-K hex_key] [-p pad_character], or
.br
.B des
-t [-v]
.SH \f3DESCRIPTION
.I Des\^
encrypts or decrypts according to the
.B -e 
(encrypt) and 
.B -d 
(decrypt) flags reading from standard input and writing to standard output.
The
.B -n 
flag disables the initial and inverse initial permutations, which yields
a substantial throughput gain.
The
.B -k
flag passes a string of 8 characters to be used as key.  The
.B -K
flag passes a 16 character hexidecimal key.  The DES algorithm
produces a 64 bit cipher product using a 56 bit key and 64 bit plaintext value.
.PP
If no key is passed 
.I des\^
uses the routine getpass("key: ") to 
demand an 8 character key from standard input.  All key inputs must be of
the correct length or
.I des\^ 
will  terminate.
.PP
Character string keys (
.B -k 
and
.B getpass()
) have each byte shifted left one bit, to leave bit[0] undefined.  Bit[0] is
used as a parity bit, and is otherwise uninvolved in DES keys.  Shifting
character string keys provides retention of all ascii defined bits and
results in a 56 bit key.  Hex key strings, such as from the 
.B -K
option or from the test vector, are not shifted.  It is the hex key provider's
responsibility to properly position 7 bits of key into the upper 7 bits of each
hex byte.
.PP
The 
.B -p
flag passes a hexidecimal value of the range 0x0 - 0xFF to be used in place
of the default pad character (0x20).
The pad character is used to fill out the last 8 byte block if the input
stream does not supply muliples of 8 bytes.
.SH \f3TESTMODE
The 
.B -t
and 
.B -v
flags are used to toggle 
.I test\^
and 
.I verbose\^
modes.  Testmode switches input format to test vectors used in DES algorithm
verification.  Each vector includes a 16 hexdigit key, a 16 hexdigit data 
value and a 16 hexdigit result value.  All output during testmode operation is 
made to standard error output.  A summary of tests is output irregardless of
the 
.I -v\^ 
flag.  Verbose mode outputs the test source and error locations.
.PP
Initial permutation, and inverse initial permutation are always executed during
test mode.
.SH \f3TEST VECTOR FORMAT
 An input line must contain less than 127 characters.  A line containing
a leading space is considered a vector.  A line without a leading
space is a comment.  The 
.I des\^
mode is set for vectors following a comment line that contains either
.B encrypt
or
.B decrypt
as the first 7 characters.
A line containing a vector is comprised
of a leading space and three 16 hexdigit values.
.PP
A trailing comment line in the vector file forces output of the error
total.
.SH \f3NORMAL OPERATION
.I Des\^
encrypts and decrypts with the same key:
.PP
.RS
des -e -k key < clear >cypher
.br
des -d -k key < cypher 
.RE
.PP
will output a stream identical to that contained in clear, with the exeception
of the possibility of up to 7 pad characters being appended to the decoded
stream. 
.PP
Files encrypted by
.I des\^
are compatible with the National Bureau of Standards Digital Encryption
Standard in an electronic code book (ECB) implementation with regard to
the 
.B -n
flag.
.PP
.I des\^
utilizes a faster implementation of the DES algorithm.
Performance increases derive from merging the  P permutation into the S Boxes
and structural optimization to reduce operations on bits to the minimum.
.PP
.I des\^
can provide interoperable secure data between different systems and 
implementations of DES (including chips) when using key input in hex strings.
.I Des\^ 
also has the capabilty of decrypting concatenated files, if
all used the same key schedule and key.
.SH \f3EXAMPLE
.IP
des -e -k abcdefgh < foo.c > fum
.PP
will use the string "abcdefgh" as key
to encrypt the contents of "foo.c", and place the encrypted
output in file "fum".  File "fum" at this point will be unreadable.
.SM \f3NOTE:\f1 
that the original file, "foo.c", remains in readable form.
To obtain readable print-out of the file "fum", it
could be decoded as follows:
.IP
des -d < fum
.PP
After the response:
.IP
key:
.PP
the user types in "abcdefgh".
.SH \f3IMPLEMENTATION
The des implementation has two subroutines 
.B des()
and
.B no_ip_des().
The routine des() calls the routine no_ip_des() after first performing
the initial permutation.  Upon return the inverse permutation is performed.
Both routines return void, and accept identical arguments, a pointer to
a block of data, and a mode flag indicating key schedule shift direction.
The basic data structure is a union between two unsigned longs (32 bit)
and a character array length 9.  (the extra byte is used in a crypt() 
implementation.)  As the interfaces to des() and no_ip_des() are identical,
no_ip_des() can be called directly, saving the processing time for bit
operations, and pushing performance.
.PP
The program destime has been included (SYSV times() calls) for measuring
performance.  On an IRIS 4D-25/G, 20 MHz MIPS R3000, FPU, cache, plenty
of RAM, and SCSI disk I/O the throughput has been measured at
33+ kbytes/sec with IP/IP-1, and 55+ kbytes/sec without IP/IP-1.  The
same values are measured, either with simple iteration or disk I/O.  The
standard size file for measurement is 40 kbytes.

.SH \f3BYTE ORDERING
Because the input block is a union between a character string, and two
longs, there are can be byte misordering.  While this will prevent the
test vectors from passing properly, it does not affect cryptographic 
security of the algorithm.  There are two possible solutions, 
reordering the input data, which is painful and ridiculous, and
modifying the initial and inverse initial permutations.
.PP
The source for the algorithm has two byte endian versions
available by compiler switch.  The two most common types, 
.B BIG_ENDIAN
and 
.B LITTLE_ENDIAN
are supported.
PDP-11 an other byte orders are not currently supported, but could
be easily added.
.SH \f3FILES
.tr *
.ta \w'des.test\ \ \ \ 'u
des.test	test vector file, derived from \f2NBS Special Pub 500-20\f1
.br
.sp
endian		Program for determining byte in long order.
.br
.sp
sbox		Program for generating sbox with P permutation
.br
*		in proper byte order.  E permutation is hand done.
.br
.sp
destime		Program for measuring execution time of the des algorithm.
.br
.tr
.DT
.SH \f3SEE ALSO
crypt(1),
makekey(1),
des(3)
.SH \f3BUGS
Encryption of large files is time consuming.
.I des\^
uses a new implementation
of the DES algorithm requiring the host machine have 32 bit longs.
des uses unions between an array of two longs and an array of nine characters.
Because of these unions, Des may be compiled for either Big-endian or 
Little-endian character string to long byte ordering.  Use of the new DES
implementation provides substantial throughput improvement over using the
DES implementation in libcrypt.
.PP
.I des\^
uses padding of the input to assemble the last block of data.  This can
result in up to 7 characters added to the decoded data.  If having the pad
character selectable is not flexible enough, a pipeline filter can be written
to protect and stuff a pad value in the plaintext domain, and strip pad
characters from the decoded output.
.br