60643d379b
(Including all changes for FreeBSD - importing the original eBones distribution would be too complex at this stage, since I don't have access to Piero's CVS.) (If you want to include eBones in your system, don't forget to include MAKE_EBONES in /etc/make.conf.) (This stuff is now also suppable from braae.ru.ac.za.) Bones originally from MIT SIPB. Original port to FreeBSD 1.x by Piero Serini. Moved to FreeBSD 2.0 by Doug Rabson and Geoff Rehmet. Nice bug fixes from Doug Rabson.
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.2 1994/07/19 19:27:19 g89r4222 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 <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.
|