des.doc

This a good VPN source

int *num,
int enc);
	Same as des_cfb64_encrypt() accept that the DES operation is
	triple DES.  As usual, there is a macro for
	des_ede2_cfb64_encrypt() which reuses ks1.

void des_ofb_encrypt(
unsigned char *in,
unsigned char *out,
int numbits,
long length,
des_key_schedule ks,
des_cblock *ivec);
	This is a implementation of Output Feed Back mode of DES.  It is
	the same as des_cfb_encrypt() in that numbits is the size of the
	units dealt with during input and output (in bits).
	
void des_ofb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks,
des_cblock *ivec,
int *num);
	The same as des_cfb64_encrypt() except that it is Output Feed Back
	mode.

void des_ede3_ofb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks1,
des_key_schedule ks2,
des_key_schedule ks3,
des_cblock *ivec,
int *num);
	Same as des_ofb64_encrypt() accept that the DES operation is
	triple DES.  As usual, there is a macro for
	des_ede2_ofb64_encrypt() which reuses ks1.

int des_read_pw_string(
char *buf,
int length,
char *prompt,
int verify);
	This routine is used to get a password from the terminal with echo
	turned off.  Buf is where the string will end up and length is the
	size of buf.  Prompt is a string presented to the 'user' and if
	verify is set, the key is asked for twice and unless the 2 copies
	match, an error is returned.  A return code of -1 indicates a
	system error, 1 failure due to use interaction, and 0 is success.

unsigned long des_cbc_cksum(
des_cblock *input,
des_cblock *output,
long length,
des_key_schedule ks,
des_cblock *ivec);
	This function produces an 8 byte checksum from input that it puts in
	output and returns the last 4 bytes as a long.  The checksum is
	generated via cbc mode of DES in which only the last 8 byes are
	kept.  I would recommend not using this function but instead using
	the EVP_Digest routines, or at least using MD5 or SHA.  This
	function is used by Kerberos v4 so that is why it stays in the
	library.
	
char *des_fcrypt(
const char *buf,
const char *salt
char *ret);
	This is my fast version of the unix crypt(3) function.  This version
	takes only a small amount of space relative to other fast
	crypt() implementations.  This is different to the normal crypt
	in that the third parameter is the buffer that the return value
	is written into.  It needs to be at least 14 bytes long.  This
	function is thread safe, unlike the normal crypt.

char *crypt(
const char *buf,
const char *salt);
	This function calls des_fcrypt() with a static array passed as the
	third parameter.  This emulates the normal non-thread safe semantics
	of crypt(3).

void des_string_to_key(
char *str,
des_cblock *key);
	This function takes str and converts it into a DES key.  I would
	recommend using MD5 instead and use the first 8 bytes of output.
	When I wrote the first version of these routines back in 1990, MD5
	did not exist but I feel these routines are still sound.  This
	routines is compatible with the one in MIT's libdes.
	
void des_string_to_2keys(
char *str,
des_cblock *key1,
des_cblock *key2);
	This function takes str and converts it into 2 DES keys.
	I would recommend using MD5 and using the 16 bytes as the 2 keys.
	I have nothing against these 2 'string_to_key' routines, it's just
	that if you say that your encryption key is generated by using the
	16 bytes of an MD5 hash, every-one knows how you generated your
	keys.

int des_read_password(
des_cblock *key,
char *prompt,
int verify);
	This routine combines des_read_pw_string() with des_string_to_key().

int des_read_2passwords(
des_cblock *key1,
des_cblock *key2,
char *prompt,
int verify);
	This routine combines des_read_pw_string() with des_string_to_2key().

void des_random_seed(
des_cblock key);
	This routine sets a starting point for des_random_key().
	
void des_random_key(
des_cblock ret);
	This function return a random key.  Make sure to 'seed' the random
	number generator (with des_random_seed()) before using this function.
	I personally now use a MD5 based random number system.

int des_enc_read(
int fd,
char *buf,
int len,
des_key_schedule ks,
des_cblock *iv);
	This function will write to a file descriptor the encrypted data
	from buf.  This data will be preceded by a 4 byte 'byte count' and
	will be padded out to 8 bytes.  The encryption is either CBC of
	PCBC depending on the value of des_rw_mode.  If it is DES_PCBC_MODE,
	pcbc is used, if DES_CBC_MODE, cbc is used.  The default is to use
	DES_PCBC_MODE.

int des_enc_write(
int fd,
char *buf,
int len,
des_key_schedule ks,
des_cblock *iv);
	This routines read stuff written by des_enc_read() and decrypts it.
	I have used these routines quite a lot but I don't believe they are
	suitable for non-blocking io.  If you are after a full
	authentication/encryption over networks, have a look at SSL instead.

unsigned long des_quad_cksum(
des_cblock *input,
des_cblock *output,
long length,
int out_count,
des_cblock *seed);
	This is a function from Kerberos v4 that is not anything to do with
	DES but was needed.  It is a cksum that is quicker to generate than
	des_cbc_cksum();  I personally would use MD5 routines now.
=====
Modes of DES
Quite a bit of the following information has been taken from
	AS 2805.5.2
	Australian Standard
	Electronic funds transfer - Requirements for interfaces,
	Part 5.2: Modes of operation for an n-bit block cipher algorithm
	Appendix A

There are several different modes in which DES can be used, they are
as follows.

Electronic Codebook Mode (ECB) (des_ecb_encrypt())
- 64 bits are enciphered at a time.
- The order of the blocks can be rearranged without detection.
- The same plaintext block always produces the same ciphertext block
  (for the same key) making it vulnerable to a 'dictionary attack'.
- An error will only affect one ciphertext block.

Cipher Block Chaining Mode (CBC) (des_cbc_encrypt())
- a multiple of 64 bits are enciphered at a time.
- The CBC mode produces the same ciphertext whenever the same
  plaintext is encrypted using the same key and starting variable.
- The chaining operation makes the ciphertext blocks dependent on the
  current and all preceding plaintext blocks and therefore blocks can not
  be rearranged.
- The use of different starting variables prevents the same plaintext
  enciphering to the same ciphertext.
- An error will affect the current and the following ciphertext blocks.

Cipher Feedback Mode (CFB) (des_cfb_encrypt())
- a number of bits (j) <= 64 are enciphered at a time.
- The CFB mode produces the same ciphertext whenever the same
  plaintext is encrypted using the same key and starting variable.
- The chaining operation makes the ciphertext variables dependent on the
  current and all preceding variables and therefore j-bit variables are
  chained together and can not be rearranged.
- The use of different starting variables prevents the same plaintext
  enciphering to the same ciphertext.
- The strength of the CFB mode depends on the size of k (maximal if
  j == k).  In my implementation this is always the case.
- Selection of a small value for j will require more cycles through
  the encipherment algorithm per unit of plaintext and thus cause
  greater processing overheads.
- Only multiples of j bits can be enciphered.
- An error will affect the current and the following ciphertext variables.

Output Feedback Mode (OFB) (des_ofb_encrypt())
- a number of bits (j) <= 64 are enciphered at a time.
- The OFB mode produces the same ciphertext whenever the same
  plaintext enciphered using the same key and starting variable.  More
  over, in the OFB mode the same key stream is produced when the same
  key and start variable are used.  Consequently, for security reasons
  a specific start variable should be used only once for a given key.
- The absence of chaining makes the OFB more vulnerable to specific attacks.
- The use of different start variables values prevents the same
  plaintext enciphering to the same ciphertext, by producing different
  key streams.
- Selection of a small value for j will require more cycles through
  the encipherment algorithm per unit of plaintext and thus cause
  greater processing overheads.
- Only multiples of j bits can be enciphered.
- OFB mode of operation does not extend ciphertext errors in the
  resultant plaintext output.  Every bit error in the ciphertext causes
  only one bit to be in error in the deciphered plaintext.
- OFB mode is not self-synchronising.  If the two operation of
  encipherment and decipherment get out of synchronism, the system needs
  to be re-initialised.
- Each re-initialisation should use a value of the start variable
 different from the start variable values used before with the same
 key.  The reason for this is that an identical bit stream would be
 produced each time from the same parameters.  This would be
 susceptible to a ' known plaintext' attack.

Triple ECB Mode (des_ecb3_encrypt())
- Encrypt with key1, decrypt with key2 and encrypt with key3 again.
- As for ECB encryption but increases the key length to 168 bits.
  There are theoretic attacks that can be used that make the effective
  key length 112 bits, but this attack also requires 2^56 blocks of
  memory, not very likely, even for the NSA.
- If both keys are the same it is equivalent to encrypting once with
  just one key.
- If the first and last key are the same, the key length is 112 bits.
  There are attacks that could reduce the key space to 55 bit's but it
  requires 2^56 blocks of memory.
- If all 3 keys are the same, this is effectively the same as normal
  ecb mode.

Triple CBC Mode (des_ede3_cbc_encrypt())
- Encrypt with key1, decrypt with key2 and then encrypt with key3.
- As for CBC encryption but increases the key length to 168 bits with
  the same restrictions as for triple ecb mode.