381 lines
11 KiB
Groff
381 lines
11 KiB
Groff
.\" from: des_crypt.3,v 4.3 89/01/23 17:08:59 steiner Exp $
|
|
.\" $Id: des_crypt.3,v 1.1.1.1 1994/09/30 14:50:05 csgr Exp $
|
|
.\" Copyright 1989 by the Massachusetts Institute of Technology.
|
|
.\"
|
|
.\" For copying and distribution information,
|
|
.\" please see the file <Copyright.MIT>.
|
|
.\"
|
|
.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 <kerberosIV/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/kerberosIV/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.
|