libdes.doc

早期freebsd实现

	How to use the Kerberos encryption library.

			Revised		10/15/85	spm

1)	The following include file is needed:
	
	/projects/auth/include/des.h	(VAX)
	---------------					(PC8086)

2)	The encryption library that should be linked to is:
	
	/projects/auth/lib/libdes.a		(VAX)
|	/projects/auth/ibm/lib/libdes.a	(PC8086 cross-compilation environment)

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.  Void is not used for compatibility
with other compilers.

/*	--------------------------------------------------------------	*/

int	
	cbc_encrypt(input,output,length,schedule,ivec,encrypt)

		C_Block			*input;		/* ptr to input data */
		C_Block			*output;	/* ptr to output data */
		int				length;		/* desired length, in bytes */
		Key_schedule	schedule;		/* addr of precomputed schedule */
		C_Block			*ivec;		/* pointer to 8 byte initialization
									 * vector
									 */
		int				encrypt		/* 0 ==> decrypt; else encrypt*/


	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.  Void is not used for
	compatibility with other compilers.


/* cbc checksum (MAC) only routine  ---------------------------------------- */
int	
	cbc_cksum(input,output,length,schedule,ivec)

	C_Block		 	*input;		/* >= length bytes of inputtext	 */
	C_Block		 	*output;	/* >= length bytes of outputtext */
	int				length;		/* in bytes						*/
	Key_schedule	schedule;	/* precomputed key schedule	   */
	C_Block			*ivec;		/* 8 bytes of ivec			   */


	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.  Void is not used for compatibility
	with other compilers.


/*	random_key ----------------------------------------*/
int
	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.  Void is not used for compatibility
	with other compilers.


/* 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.