Initial revision
git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@171 ec53bebd-3082-4978-b11e-865c3cabbd6b
This commit is contained in:
Unknown User d91-jda
381
lib/des/des_crypt.3
Normal file
381
lib/des/des_crypt.3
Normal file
@@ -0,0 +1,381 @@
|
||||
.\" $Source$
|
||||
.\" $Author$
|
||||
.\" $Header$
|
||||
.\" 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.
|
||||
Reference in New Issue
Block a user