DES_CRYPT(3)DES_CRYPT(3)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
SYNOPSIS
#include <kerberosIV/des.h>
int des_read_password(key,prompt,verify)
des_cblock *key;
char *prompt;
int verify;
int des_string_to_key(str,key)
char *str;
des_cblock key;
int des_random_key(key)
des_cblock *key;
int des_set_key(key,schedule)
des_cblock *key;
des_key_schedule schedule;
int des_ecb_encrypt(input,output,schedule,encrypt)
des_cblock *input;
des_cblock *output;
des_key_schedule schedule;
int encrypt;
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;
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;
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;
unsigned long quad_cksum(input,output,length,out_count,seed)
des_cblock *input;
des_cblock *output;
long length;
int out_count;
des_cblock *seed;
DESCRIPTION
This library supports various DES encryption related operations. It
differs from the crypt, setkey, and encrypt library routines in that it
provides a true DES encryption, without modifying the algorithm, and
executes much faster.
For each key that may be simultaneously active, create a des_key_sched‐
ule struct, defined in "des.h". Next, create key schedules (from the
8-byte keys) as needed, via 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, des_ecb_encrypt or
des_cbc_encrypt or des_pcbc_encrypt, or, to generate a cryptographic
checksum, use quad_cksum (fast) or des_cbc_cksum (slow).
A des_cblock struct is an 8 byte block used as the fundamental unit for
DES data and keys, and is defined as:
typedef unsigned char des_cblock[8];
and a des_key_schedule, is defined as:
typedef struct des_ks_struct {des_cblock _;} des_key_schedule[16];
des_read_password writes the string specified by prompt to the standard
output, turns off echo (if possible) and reads an input string from
standard input until terminated with a newline. If 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 des_read_password converts
the input string into a valid DES key, internally using the
des_string_to_key routine. The newly created key is copied to the area
pointed to by the key argument. des_read_password returns a zero if no
errors occurred, or a -1 indicating that an error occurred trying to
manipulate the terminal echo.
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 str argument is
a pointer to the string, and key should point to a 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.
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 genera‐
tor. The caller must supply space for the output key, pointed to
by argument key, then after calling des_random_key should call the
des_set_key routine when needed. No meaningful value is returned.
Void is not used for compatibility with other compilers.
des_set_key calculates a key schedule from all eight bytes of the input
key, pointed to by the key argument, and outputs the schedule into the
des_key_schedule indicated by the 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.
des_ecb_encrypt is the basic DES encryption routine that encrypts or
decrypts a single 8-byte block in electronic code book mode. It always
transforms the input data, pointed to by input, into the output data,
pointed to by the output argument.
If the encrypt argument is non-zero, the input (cleartext) is encrypted
into the output (ciphertext) using the key_schedule specified by the
schedule argument, previously set via des_set_key
If encrypt is zero, the input (now ciphertext) is decrypted into the
output (now cleartext).
Input and output may overlap.
No meaningful value is returned. Void is not used for compatibility
with other compilers.
des_cbc_encrypt encrypts/decrypts using the cipher-block-chaining mode
of DES. If the encrypt argument is non-zero, the routine cipher-block-
chain encrypts the cleartext data pointed to by the input argument into
the ciphertext pointed to by the output argument, using the key sched‐
ule provided by the schedule argument, and initialization vector pro‐
vided by the ivec argument. If the 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.
If encrypt is zero, the routine cipher-block chain decrypts the (now)
ciphertext data pointed to by the input argument into (now) cleartext
pointed to by the output argument using the key schedule provided by
the schedule argument, and initialization vector provided by the ivec
argument. Decryption ALWAYS operates on integral multiples of 8 bytes,
so it will round the 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 cleart‐
ext was zero-padded due to original cleartext lengths that were not
integral multiples of 8.
No errors or meaningful values are returned. Void is not used for com‐
patibility with other compilers.
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, des_pcbc_encrypt is STRONGLY recommended for appli‐
cations where indefinite propagation of errors is required in order to
detect modifications.
des_pcbc_encrypt encrypts/decrypts using a modified block chaining
mode. Its calling sequence is identical to des_cbc_encrypt. It differs
in its error propagation characteristics.
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.
des_cbc_cksum produces an 8 byte cryptographic checksum by cipher-
block-chain encrypting the cleartext data pointed to by the input argu‐
ment. All of the ciphertext output is discarded, except the last 8-byte
ciphertext block, which is written into the area pointed to by the out‐
put argument. It uses the key schedule, provided by the schedule argu‐
ment and initialization vector provided by the ivec argument. If the
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.
The routine also returns an unsigned long, which is the last (highest
address) half of the 8 byte checksum computed.
quad_cksum produces a checksum by chaining quadratic operations on the
cleartext data pointed to by the input argument. The length argument
specifies the length of the input -- only exactly that many bytes are
included for the checksum, without any padding.
The algorithm may be iterated over the same input data, if the
out_count argument is 2, 3 or 4, and the optional 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 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 itera‐
tion.
It returns both an unsigned long checksum value, and if the output
argument is not a null pointer, up to 16 bytes of the computed checksum
are written into the output.
FILES
/usr/include/kerberosIV/des.h
/usr/lib/libdes.a
SEE ALSODIAGNOSTICSBUGS
This software has not yet been compiled or tested on machines other
than the VAX and the IBM PC.
AUTHORS
Steve Miller, MIT Project Athena/Digital Equipment Corporation
RESTRICTIONS
COPYRIGHT 1985,1986 Massachusetts Institute of Technology
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.
MIT Project Athena Kerberos Version 4.0 DES_CRYPT(3)