libdes.doc
[plain text]
How to use the Kerberos encryption library.
Revised
1)
spm
The following include file is needed:
/projects/auth/include/des.h
---------------
2)
10/15/85
(VAX)
(PC8086)
The encryption library that should be linked to is:
/projects/auth/lib/libdes.a
|
/projects/auth/ibm/lib/libdes.a
environment)
(VAX)
(PC8086 cross-compilation
3)
For each key that may be simultaneously active,
allocate (either compile or malloc) a "Key_schedule" struct,
defined in "des.h"
4)
Create key schedules, as needed, prior to using the encryption
routines, via "des_set_key()".
5)
Setup the input and output areas. Make sure to note the restrictions
on lengths being multiples of eight bytes.
6)
Invoke the encryption/decryption routines, "ecb_encrypt()"
or "cbc_encrypt()"
7)
/*
To generate a cryptographic checksum, use "cbc_cksum()"
---------------------------------------------------------------*/
Routine Interfaces--
/*
----------------------------------------------------------------*/
int
des_set_key(k,schedule)
C_Block
*k;
Key_schedule
schedule;
Calculates a key schedule from (all) eight bytes of the input key, and
puts it into the indicated "Key_schedule" struct;
Make sure to pass valid eight bytes, no padding or other processing
it done.
The key schedule is then used in subsequent encryption/decryption
operations. Many key schedules may be created and cached for later
use.
The user is responsible to clear keys and schedules no longer needed
to prevent their disclosure.
|
|
Checks the parity of the key provided, to make sure it is odd per
FIPS spec. Returns 0 value for key ok, 1 for key_parity error.
/*
---------------------------------------------------------------*/
int
ecb_encrypt(input,output,schedule,encrypt)
C_Block
*input;
/* ptr to eight byte
input value */
C_Block
*output;
/* ptr to eight byte
output value */
int
encrypt;
/* 0 ==>
decrypt, else encrypt */
Key_schedule
schedule;
/* addr of key schedule */
This is the low level routine that encrypts or decrypts a single 8-byte
block in electronic code book mode. Always transforms the input
data into the output data.
If encrypt is non-zero, the input (cleartext) is encrypted into the
output (ciphertext) using the specified key_schedule, pre-set via
"des_set_key".
If encrypt is zero, the input (now ciphertext) is decrypted into
the output (now cleartext).
Input and output may be the same space.
Does not return any meaningful value.
with other compilers.
/*
Void is not used for compatibility
-------------------------------------------------------------*/
int
cbc_encrypt(input,output,length,schedule,ivec,encrypt)
C_Block
C_Block
int
length, in bytes */
Key_schedule
schedule */
C_Block
initialization
*input;
/* ptr to input data */
*output;
/* ptr to output data */
length;
/* desired
schedule;
/* addr of precomputed
*ivec;
/* pointer to 8 byte
* vector
*/
int
decrypt; else encrypt*/
encrypt
/* 0 ==>
If encrypt is non-zero, the routine cipher-block-chain encrypts
the INPUT (cleartext) into the OUTPUT (ciphertext) using the provided
key schedule and initialization vector. If the length 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 INPUT
(ciphertext) into the OUTPUT (cleartext) using the provided key
schedule
and
initialization vector. Decryption ALWAYS operates on integral
multiples of 8 bytes, so 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 cleartext was zero-padded due to cleartext lengths not
integral
multiples of 8.
No errors or meaningful value are returned.
compatibility with other compilers.
Void is not used for
/* cbc checksum (MAC) only routine ---------------------------------------*/
int
cbc_cksum(input,output,length,schedule,ivec)
C_Block
inputtext
*/
C_Block
*/
int
bytes
Key_schedule
C_Block
ivec
*input;
/* >= length bytes of
*output;
/* >= length bytes of outputtext
length;
/* in
*/
schedule;
/* precomputed key schedule
*ivec;
/* 8 bytes of
*/
*/
Produces a cryptographic checksum, 8 bytes, by cipher-block-chain
encrypting the input, discarding the ciphertext output, and only
retaining
the last ciphertext 8-byte block. Uses the provided key schedule and
ivec.
The input is effectively zero-padded to an integral multiple of
eight bytes, though the original input is not modified.
No meaningful value is returned.
with other compilers.
/*
int
Void is not used for compatibility
random_key ----------------------------------------*/
random_key(key)
C_Block *key;
The start for the random number generated is set from the current time
in microseconds, then the random number generator is invoked
to create an eight byte output key (not a schedule). The key
generated is set to odd parity per FIPS spec.
The caller must supply space for the output key, pointed to
by "*key", then after getting a new key, call the des_set_key()
routine when needed.
No meaningfull value is returned.
with other compilers.
Void is not used for compatibility
/* string_to_key --------------------------------------------*/
int
string_to_key(str,key)
register char
*str;
register C_Block
*key;
This routines converts an arbitrary length, null terminated string
to an 8 byte DES key, with each byte parity set to odd, per FIPS spec.
The algorithm is as follows:
|
|
|
|
|
|
|
|
|
|
Take the first 8 bytes and remove the parity (leaving 56 bits).
Do the same for the second 8 bytes, and the third, etc. Do this for
as many sets of 8 bytes as necessary, filling in the remainder of the
last set with nulls. Fold the second set back on the first (i.e. bit
0 over bit 55, and bit 55 over bit 0). Fold the third over the second
(bit 0 of the third set is now over bit 0 of the first set). Repeat
until you have done this to all sets. Xor the folded sets. Break the
result into 8 7 bit bytes, and generate odd parity for each byte. You
now have 64 bits. Note that DES takes a 64 bit key, and uses only the
non parity bits.
/* read_password -------------------------------------------*/
read_password(k,prompt,verify)
C_Block *k;
char *prompt;
int
verify;
This routine issues the supplied prompt, turns off echo, if possible, and
reads an input string. If verify is non-zero, it does it again, for use
in applications such as changing a password. If verify is non-zero, both
versions are compared, and the input is requested repeatedly until they
match. Then, the input string is mapped into a valid DES key, internally
using the string_to_key routine. The newly created key is copied to the
area pointed to by parameter "k".
No meaningful value is returned. If an error occurs trying to manipulate
the terminal echo, the routine forces the process to exit.
/* get_line ------------------------*/
long get_line(p,max)
char
*p;
long
max;
Reads input characters from standard input until either a newline appears or
else the max length is reached. The characters read are stuffed into
the string pointed to, which will always be null terminated. The newline
is not inserted in the string. The max parameter includes the byte needed
for the null terminator, so allocate and pass one more than the maximum
string length desired.