des.doc

加密算法源代码DES&RSA

The DES library.

Please note that this library was originally written to operate with
eBones, a version of Kerberos that had had encryption removed when it left
the USA and then put back in.  As such there are some routines that I will
advise not using but they are still in the library for historical reasons.
For all calls that have an 'input' and 'output' variables, they can be the
same.

This library requires the inclusion of 'des.h'.

All of the encryption functions take what is called a des_key_schedule as an 
argument.  A des_key_schedule is an expanded form of the des key.
A des_key is 8 bytes of odd parity, the type used to hold the key is a
des_cblock.  A des_cblock is an array of 8 bytes, often in this library
description I will refer to input bytes when the function specifies
des_cblock's as input or output, this just means that the variable should
be a multiple of 8 bytes.

The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to
specify decryption.  The functions and global variable are as follows:

int des_check_key;
	DES keys are supposed to be odd parity.  If this variable is set to
	a non-zero value, des_set_key() will check that the key has odd
	parity and is not one of the known weak DES keys.  By default this
	variable is turned off;
	
void des_set_odd_parity(
des_cblock *key );
	This function takes a DES key (8 bytes) and sets the parity to odd.
	
int des_is_weak_key(
des_cblock *key );
	This function returns a non-zero value if the DES key passed is a
	weak, DES key.  If it is a weak key, don't use it, try a different
	one.  If you are using 'random' keys, the chances of hitting a weak
	key are 1/2^52 so it is probably not worth checking for them.
	
int des_set_key(
des_cblock *key,
des_key_schedule schedule);
	Des_set_key converts an 8 byte DES key into a des_key_schedule.
	A des_key_schedule is an expanded form of the key which is used to
	perform actual encryption.  It can be regenerated from the DES key
	so it only needs to be kept when encryption or decryption is about
	to occur.  Don't save or pass around des_key_schedule's since they
	are CPU architecture dependent, DES keys are not.  If des_check_key
	is non zero, zero is returned if the key has the wrong parity or
	the key is a weak key, else 1 is returned.
	
int des_key_sched(
des_cblock *key,
des_key_schedule schedule);
	An alternative name for des_set_key().

int des_rw_mode;		/* defaults to DES_PCBC_MODE */
	This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default).
	This specifies the function to use in the enc_read() and enc_write()
	functions.

void des_encrypt(
unsigned long *data,
des_key_schedule ks,
int enc);
	This is the DES encryption function that gets called by just about
	every other DES routine in the library.  You should not use this
	function except to implement 'modes' of DES.  I say this because the
	functions that call this routine do the conversion from 'char *' to
	long, and this needs to be done to make sure 'non-aligned' memory
	access do not occur.  The characters are loaded 'little endian',
	have a look at my source code for more details on how I use this
	function.
	Data is a pointer to 2 unsigned long's and ks is the
	des_key_schedule to use.  enc, is non zero specifies encryption,
	zero if decryption.

void des_encrypt2(
unsigned long *data,
des_key_schedule ks,
int enc);
	This functions is the same as des_encrypt() except that the DES
	initial permutation (IP) and final permutation (FP) have been left
	out.  As for des_encrypt(), you should not use this function.
	It is used by the routines in my library that implement triple DES.
	IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same
	as des_encrypt() des_encrypt() des_encrypt() except faster :-).

void des_ecb_encrypt(
des_cblock *input,
des_cblock *output,
des_key_schedule ks,
int enc);
	This is the basic Electronic Code Book form of DES, the most basic
	form.  Input is encrypted into output using the key represented by
	ks.  If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise
	decryption occurs.  Input is 8 bytes long and output is 8 bytes.
	(the des_cblock structure is 8 chars).
	
void des_ecb3_encrypt(
des_cblock *input,
des_cblock *output,
des_key_schedule ks1,
des_key_schedule ks2,
des_key_schedule ks3,
int enc);
	This is the 3 key EDE mode of ECB DES.  What this means is that 
	the 8 bytes of input is encrypted with ks1, decrypted with ks2 and
	then encrypted again with ks3, before being put into output;
	C=E(ks3,D(ks2,E(ks1,M))).  There is a macro, des_ecb2_encrypt()
	that only takes 2 des_key_schedules that implements,
	C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1.
	
void des_cbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule ks,
des_cblock *ivec,
int enc);
	This routine implements DES in Cipher Block Chaining mode.
	Input, which should be a multiple of 8 bytes is encrypted
	(or decrypted) to output which will also be a multiple of 8 bytes.
	The number of bytes is in length (and from what I've said above,
	should be a multiple of 8).  If length is not a multiple of 8, I'm
	not being held responsible :-).  ivec is the initialisation vector.
	This function does not modify this variable.  To correctly implement
	cbc mode, you need to do one of 2 things; copy the last 8 bytes of
	cipher text for use as the next ivec in your application,
	or use des_ncbc_encrypt(). 
	Only this routine has this problem with updating the ivec, all
	other routines that are implementing cbc mode update ivec.
	
void des_ncbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule sk,
des_cblock *ivec,
int enc);
	For historical reasons, des_cbc_encrypt() did not update the
	ivec with the value requires so that subsequent calls to
	des_cbc_encrypt() would 'chain'.  This was needed so that the same
	'length' values would not need to be used when decrypting.
	des_ncbc_encrypt() does the right thing.  It is the same as
	des_cbc_encrypt accept that ivec is updates with the correct value
	to pass in subsequent calls to des_ncbc_encrypt().  I advise using
	des_ncbc_encrypt() instead of des_cbc_encrypt();

void des_xcbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule sk,
des_cblock *ivec,
des_cblock *inw,
des_cblock *outw,
int enc);
	This is RSA's DESX mode of DES.  It uses inw and outw to
	'whiten' the encryption.  inw and outw are secret (unlike the iv)
	and are as such, part of the key.  So the key is sort of 24 bytes.
	This is much better than cbc des.
	
void des_3cbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule sk1,
des_key_schedule sk2,
des_cblock *ivec1,
des_cblock *ivec2,
int enc);
	This function is flawed, do not use it.  I have left it in the
	library because it is used in my des(1) program and will function
	correctly when used by des(1).  If I removed the function, people
	could end up unable to decrypt files.
	This routine implements outer triple cbc encryption using 2 ks and
	2 ivec's.  Use des_ede2_cbc_encrypt() instead.
	
void des_ede3_cbc_encrypt(
des_cblock *input,
des_cblock *output, 
long length,
des_key_schedule ks1,
des_key_schedule ks2, 
des_key_schedule ks3, 
des_cblock *ivec,
int enc);
	This function implements inner triple CBC DES encryption with 3
	keys.  What this means is that each 'DES' operation
	inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))).
	Again, this is cbc mode so an ivec is requires.
	This mode is used by SSL.
	There is also a des_ede2_cbc_encrypt() that only uses 2
	des_key_schedule's, the first being reused for the final
	encryption.  C=E(ks1,D(ks2,E(ks1,M))).  This form of triple DES
	is used by the RSAref library.
	
void des_pcbc_encrypt(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule ks,
des_cblock *ivec,
int enc);
	This is Propagating Cipher Block Chaining mode of DES.  It is used
	by Kerberos v4.  It's parameters are the same as des_ncbc_encrypt().
	
void des_cfb_encrypt(
unsigned char *in,
unsigned char *out,
int numbits,
long length,
des_key_schedule ks,
des_cblock *ivec,
int enc);
	Cipher Feedback Back mode of DES.  This implementation 'feeds back'
	in numbit blocks.  The input (and output) is in multiples of numbits
	bits.  numbits should to be a multiple of 8 bits.  Length is the
	number of bytes input.  If numbits is not a multiple of 8 bits,
	the extra bits in the bytes will be considered padding.  So if
	numbits is 12, for each 2 input bytes, the 4 high bits of the
	second byte will be ignored.  So to encode 72 bits when using
	a numbits of 12 take 12 bytes.  To encode 72 bits when using
	numbits of 9 will take 16 bytes.  To encode 80 bits when using
	numbits of 16 will take 10 bytes. etc, etc.  This padding will
	apply to both input and output.

	
void des_cfb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks,
des_cblock *ivec,
int *num,
int enc);
	This is one of the more useful functions in this DES library, it
	implements CFB mode of DES with 64bit feedback.  Why is this
	useful you ask?  Because this routine will allow you to encrypt an
	arbitrary number of bytes, no 8 byte padding.  Each call to this
	routine will encrypt the input bytes to output and then update ivec
	and num.  num contains 'how far' we are though ivec.  If this does
	not make much sense, read more about cfb mode of DES :-).
	
void des_ede3_cfb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks1,
des_key_schedule ks2,
des_key_schedule ks3,
des_cblock *ivec,