.\" $Id: des_crypt.3,v 1.2 1996/06/12 21:29:09 bg Exp $
.\" Copyright 1989 by the Massachusetts Institute of Technology.
.\"
.\" For copying and distribution information,
.\" please see the file <mit-copyright.h>.
.\"
.TH DES_CRYPT 3  "Kerberos Version 4.0" "MIT Project Athena"
.SH NAME
des_read_password, des_string_to_key, des_random_key, des_set_key,
des_ecb_encrypt, des_cbc_encrypt, des_pcbc_encrypt, des_cbc_cksum,
des_quad_cksum, \- (new) DES encryption
.SH SYNOPSIS
.nf
.nj
.ft B
#include <des.h>
.PP
.ft B
.B int des_read_password(key,prompt,verify)
des_cblock *key;
char *prompt;
int verify;
.PP
.ft B
int des_string_to_key(str,key)
char *str;
des_cblock key;
.PP
.ft B
int des_random_key(key)
des_cblock *key;
.PP
.ft B
int des_set_key(key,schedule)
des_cblock *key;
des_key_schedule schedule;
.PP
.ft B
int des_ecb_encrypt(input,output,schedule,encrypt)
des_cblock *input;
des_cblock *output;
des_key_schedule schedule;
int encrypt;
.PP
.ft B
int des_cbc_encrypt(input,output,length,schedule,ivec,encrypt)
des_cblock *input;
des_cblock *output;
long length;
des_key_schedule schedule;
des_cblock *ivec;
int encrypt;
.PP
.ft B
int des_pcbc_encrypt(input,output,length,schedule,ivec,encrypt)
des_cblock *input;
des_cblock *output;
long length;
des_key_schedule schedule;
des_cblock *ivec;
int encrypt;
.PP
.ft B
unsigned long des_cbc_cksum(input,output,length,schedule,ivec)
des_cblock *input;
des_cblock *output;
long length;
des_key_schedule schedule;
des_cblock *ivec;
.PP
.ft B
unsigned long quad_cksum(input,output,length,out_count,seed)
des_cblock *input;
des_cblock *output;
long length;
int out_count;
des_cblock *seed;
.PP
.fi
.SH DESCRIPTION
This library supports various DES encryption related operations. It differs
from the
.I crypt, setkey, and encrypt
library routines in that it provides
a true DES encryption, without modifying the algorithm,
and executes much faster.
.PP
For each key that may be simultaneously active, create a
.B des_key_schedule
struct,
defined in "des.h". Next, create key schedules (from the 8-byte keys) as
needed, via
.I des_set_key,
prior to using the encryption or checksum routines. Then
setup the input and output areas.  Make sure to note the restrictions
on lengths being multiples of eight bytes. Finally, invoke the
encryption/decryption routines,
.I des_ecb_encrypt
or
.I des_cbc_encrypt
or
.I des_pcbc_encrypt,
or, to generate a cryptographic checksum, use
.I quad_cksum
(fast) or
.I des_cbc_cksum
(slow).
.PP
A
.I des_cblock
struct is an 8 byte block used as the fundamental unit for DES data and
keys, and is defined as:
.PP
.B	typedef	unsigned char des_cblock[8];
.PP
and a
.I des_key_schedule,
is defined as:
.PP
.B	typedef	struct des_ks_struct {des_cblock _;}  des_key_schedule[16];
.PP
.I des_read_password
writes the string specified by
.I prompt
to the standard
output, turns off echo (if possible)
and reads an input string from standard input until terminated with a newline.
If
.I verify
is non-zero, it prompts and reads input again, for use
in applications such as changing a password; both
versions are compared, and the input is requested repeatedly until they
match.  Then
.I des_read_password
converts the input string into a valid DES key, internally
using the
.I des_string_to_key
routine.  The newly created key is copied to the
area pointed to by the
.I key
argument.
.I des_read_password
returns a zero if no errors occurred, or a -1
indicating that an error
occurred trying to manipulate the terminal echo.
.PP
.PP
.I des_string_to_key
converts an arbitrary length null-terminated string
to an 8 byte DES key, with odd byte parity, per FIPS specification.
A one-way function is used to convert the string to a key, making it
very difficult to reconstruct the string from the key.
The
.I str
argument is a pointer to the string, and
.I key
should
point to a
.I des_cblock
supplied by the caller to receive the generated key.
No meaningful value is returned. Void is not used for compatibility with
other compilers.
.PP
.PP
.I des_random_key
generates a random DES encryption key (eight bytes), set to odd parity per
FIPS
specifications.
This routine uses the current time, process id, and a counter
as a seed for the random number generator.
The caller must	supply space for the output key, pointed to
by argument
.I key,
then after calling
.I des_random_key
should
call the
.I des_set_key
routine when needed.
No meaningful value is returned.  Void is not used for compatibility
with other compilers.
.PP
.PP
.I des_set_key
calculates a key schedule from all eight bytes of the input key, pointed
to by the
.I key
argument, and outputs the schedule into the
.I des_key_schedule
indicated by the
.I schedule
argument. Make sure to pass a valid eight byte
key; no padding is done.  The key schedule may then be used in subsequent
encryption/decryption/checksum operations.  Many key schedules may be
cached for later use.  The user is responsible to clear keys and schedules
as soon as no longer needed, to prevent their disclosure.
The routine also checks the key
parity, and returns a zero if the key parity is correct (odd), a -1
indicating a key parity error, or a -2 indicating use of an illegal
weak key. If an error is returned, the key schedule was not created.
.PP
.PP
.I des_ecb_encrypt
is the basic DES encryption routine that encrypts or decrypts a single 8-byte
block in
.B electronic code book
mode.  It always transforms the input data, pointed to by
.I input,
into the output data, pointed to by the
.I output
argument.
.PP
If the
.I encrypt
argument is non-zero, the
.I input
(cleartext) is encrypted into the
.I output
(ciphertext) using the key_schedule specified by the
.I schedule
argument, previously set via
.I des_set_key
.PP
If encrypt is zero, the
.I input
(now ciphertext) is decrypted into the
.I output
(now cleartext).
.PP
Input and output may overlap.
.PP
No meaningful value is returned.  Void is not used for compatibility
with other compilers.
.PP
.PP
.I des_cbc_encrypt
encrypts/decrypts using the
.B cipher-block-chaining mode of DES.
If the
.I encrypt
argument is non-zero, the routine cipher-block-chain encrypts
the cleartext data pointed to by the
.I input
argument into the ciphertext pointed to by the
.I output
argument, using the key schedule provided by the
.I schedule
argument, and initialization vector provided by the
.I ivec
argument.
If the
.I length
argument is not an integral
multiple of eight bytes, the last block is copied to a temp and zero
filled (highest addresses).  The output is ALWAYS an integral multiple
of eight bytes.
.PP
If
.I encrypt
is zero, the routine cipher-block chain decrypts the (now) ciphertext
data pointed to by the
.I input
argument into (now) cleartext pointed to by the
.I output
argument using the key schedule provided by the
.I schedule
argument, and initialization vector provided by the
.I ivec
argument. Decryption ALWAYS operates on integral
multiples of 8 bytes, so it will round the
.I length
provided up to the
appropriate multiple. Consequently, it will always produce the rounded-up
number of bytes of output cleartext. The application must determine if
the output cleartext was zero-padded due to original cleartext lengths that
were not integral multiples of 8.
.PP
No errors or meaningful values are returned.  Void is not used for
compatibility with other compilers.
.PP
A characteristic of cbc mode is that changing a single bit of the
cleartext, then encrypting using cbc mode,
affects ALL the subsequent ciphertext.  This makes cryptanalysis
much more difficult. However, modifying a single bit of the ciphertext,
then decrypting, only affects the resulting cleartext from
the modified block and the succeeding block.  Therefore,
.I des_pcbc_encrypt
is STRONGLY recommended for applications where
indefinite propagation of errors is required in order to detect modifications.
.PP
.PP
.I des_pcbc_encrypt
encrypts/decrypts using a modified block chaining mode. Its calling
sequence is identical to
.I des_cbc_encrypt.
It differs in its error propagation characteristics.
.PP
.I des_pcbc_encrypt
is highly recommended for most encryption purposes, in that
modification of a single bit of the ciphertext will affect ALL the
subsequent (decrypted) cleartext. Similarly, modifying a single bit of
the cleartext will affect ALL the subsequent (encrypted) ciphertext.
"PCBC" mode, on encryption, "xors" both the
cleartext of block N and the ciphertext resulting from block N with the
cleartext for block N+1 prior to encrypting block N+1.
.PP
.I des_cbc_cksum
produces an 8 byte cryptographic checksum by cipher-block-chain
encrypting the cleartext data pointed to by the
.I input
argument. All of the ciphertext output is discarded, except the
last 8-byte ciphertext block, which is written into the area pointed to by
the
.I output
argument.
It uses the key schedule,
provided by the
.I schedule
argument and initialization vector provided by the
.I ivec
argument.
If the
.I length
argument is not an integral
multiple of eight bytes, the last cleartext block is copied to a temp and zero
filled (highest addresses).  The output is ALWAYS eight bytes.
.PP
The routine also returns an unsigned long, which is the last (highest address)
half of the 8 byte checksum computed.
.PP
.PP
.I quad_cksum
produces a checksum by chaining quadratic operations on the cleartext data
pointed to by the
.I input
argument. The
.I length
argument specifies the length of the
input -- only exactly that many bytes are included for the checksum,
without any padding.
.PP
The algorithm may be iterated over the same input data, if the
.I out_count
argument is 2, 3 or 4, and the optional
.I output
argument is a non-null pointer .
The default is one iteration, and it will not run
more than 4 times. Multiple iterations run slower, but provide
a longer checksum if desired. The
.I seed
argument provides an 8-byte seed for the first iteration. If multiple iterations are
requested, the results of one iteration are automatically used as
the seed for the next iteration.
.PP
It returns both an unsigned long checksum value, and
if the
.I output
argument is not a null pointer, up to 16 bytes of
the computed checksum are written into the output.
.PP
.PP
.SH FILES
/usr/include/des.h
.br
/usr/lib/libdes.a
.SH "SEE ALSO"
.SH DIAGNOSTICS
.SH BUGS
This software has not yet been compiled or tested on machines other than the
VAX and the IBM PC.
.SH AUTHORS
Steve Miller, MIT Project Athena/Digital Equipment Corporation
.SH RESTRICTIONS
COPYRIGHT 1985,1986 Massachusetts Institute of Technology
.PP
This software may not be exported outside of the US without a special
license from the US Dept of Commerce. It may be replaced by any secret
key block cipher with block length and key length of 8 bytes, as long
as the interface is the same as described here.