ssleay.txt

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,
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.

==== digest.doc ========================================================


The Message Digest subroutines.

These routines require "evp.h" to be included.

These functions are a higher level interface to the various message digest
routines found in this library.  As such, they allow the same code to be
used to digest via different algorithms with only a change in an initial
parameter.  They are basically just a front-end to the MD2, MD5, SHA
and SHA1
routines.

These routines all take a pointer to the following structure to specify
which message digest algorithm to use.
typedef struct evp_md_st
	{
	int type;
	int pkey_type;
	int md_size;
	void (*init)();
	void (*update)();
	void (*final)();

	int required_pkey_type; /*EVP_PKEY_xxx */
	int (*sign)();
	int (*verify)();
	} EVP_MD;

If additional message digest algorithms are to be supported, a structure of
this type needs to be declared and populated and then the Digest routines
can be used with that algorithm.  The type field is the object NID of the
digest type (read the section on Objects for an explanation).  The pkey_type
is the Object type to use when the a message digest is generated by there
routines and then is to be signed with the pkey algorithm.  Md_size is
the size of the message digest returned.  Init, update
and final are the relevant functions to perform the message digest function
by parts.  One reason for specifying the message digest to use via this
mechanism is that if you only use md5, only the md5 routines will
be included in you linked program.  If you passed an integer
that specified which message digest to use, the routine that mapped that
integer to a set of message digest functions would cause all the message
digests functions to be link into the code.  This setup also allows new
message digest functions to be added by the application.

The six message digests defined in this library are

EVP_MD *EVP_md2(void);	/* RSA sign/verify */
EVP_MD *EVP_md5(void);	/* RSA sign/verify */
EVP_MD *EVP_sha(void);	/* RSA sign/verify */
EVP_MD *EVP_sha1(void);	/* RSA sign/verify */
EVP_MD *EVP_dss(void);	/* DSA sign/verify */
EVP_MD *EVP_dss1(void);	/* DSA sign/verify */

All the message digest routines take a EVP_MD_CTX pointer as an argument.
The state of the message digest is kept in this structure.

typedef struct pem_md_ctx_st
	{
	EVP_MD *digest;
	union	{
		unsigned char base[4]; /* this is used in my library as a
					* 'pointer' to all union elements
					* structures. */
		MD2_CTX md2;
		MD5_CTX md5;
		SHA_CTX sha;
		} md;
	} EVP_MD_CTX;

The Digest functions are as follows.

void EVP_DigestInit(
EVP_MD_CTX *ctx,
EVP_MD *type);
	This function is used to initialise the EVP_MD_CTX.  The message
	digest that will associated with 'ctx' is specified by 'type'.

void EVP_DigestUpdate(
EVP_MD_CTX *ctx,
unsigned char *data,
unsigned int cnt);
	This function is used to pass more data to the message digest
	function.  'cnt' bytes are digested from 'data'.

void EVP_DigestFinal(
EVP_MD_CTX *ctx,
unsigned char *md,
unsigned int *len);
	This function finishes the digestion and puts the message digest
	into 'md'.  The length of the message digest is put into len;
	EVP_MAX_MD_SIZE is the size of the largest message digest that
	can be returned from this function.  Len can be NULL if the
	size of the digest is not required.
	

==== encode.doc ========================================================


void    EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
void    EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,
		int *outl,unsigned char *in,int inl);
void    EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl);
int     EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n);

void    EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
int     EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl,
		unsigned char *in, int inl);
int     EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned
		char *out, int *outl);
int     EVP_DecodeBlock(unsigned char *t, unsigned
		char *f, int n);


==== envelope.doc ========================================================

The following routines are use to create 'digital' envelopes.
By this I mean that they perform various 'higher' level cryptographic
functions.  Have a read of 'cipher.doc' and 'digest.doc' since those
routines are used by these functions.
cipher.doc contains documentation about the cipher part of the
envelope library and digest.doc contatins the description of the
message digests supported.

To 'sign' a document involves generating a message digest and then encrypting
the digest with an private key.

#define EVP_SignInit(a,b)		EVP_DigestInit(a,b)
#define EVP_SignUpdate(a,b,c)		EVP_DigestUpdate(a,b,c)
Due to the fact this operation is basically just an extended message
digest, the first 2 functions are macro calls to Digest generating
functions.

int     EVP_SignFinal(
EVP_MD_CTX *ctx,
unsigned char *md,
unsigned int *s,
EVP_PKEY *pkey);
	This finalisation function finishes the generation of the message
digest and then encrypts the digest (with the correct message digest 
object identifier) with the EVP_PKEY private key.  'ctx' is the message digest
context.  'md' will end up containing the encrypted message digest.  This
array needs to be EVP_PKEY_size(pkey) bytes long.  's' will actually
contain the exact length.  'pkey' of course is the private key.  It is
one of EVP_PKEY_RSA or EVP_PKEY_DSA type.
If there is an error, 0 is returned, otherwise 1.
		
Verify is used to check an signed message digest.

#define EVP_VerifyInit(a,b)		EVP_DigestInit(a,b)
#define EVP_VerifyUpdate(a,b,c)		EVP_DigestUpdate(a,b,c)
Since the first step is to generate a message digest, the first 2 functions
are macros.

int EVP_VerifyFinal(
EVP_MD_CTX *ctx,
unsigned char *md,
unsigned int s,
EVP_PKEY *pkey);
	This function finishes the generation of the message digest and then
compares it with the supplied encrypted message digest.  'md' contains the
's' bytes of encrypted message digest.  'pkey' is used to public key decrypt
the digest.  It is then compared with the message digest just generated.
If they match, 1 is returned else 0.

int	EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,
		int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk);
Must have at least one public key, error is 0.  I should also mention that
the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size.

#define EVP_SealUpdate(a,b,c,d,e)	EVP_EncryptUpdate(a,b,c,d,e)	
void	EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl);


int	EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,
		int ekl,unsigned char *iv,EVP_PKEY *priv);
0 on failure

#define EVP_OpenUpdate(a,b,c,d,e)	EVP_DecryptUpdate(a,b,c,d,e)

int	EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
Decrypt final return code


==== error.doc ========================================================

The error routines.

The 'error' system I've implemented is intended to server 2 purpose, to
record the reason why a command failed and to record where in the libraries
the failure occurred.  It is more or less setup to record a 'trace' of which
library components were being traversed when the error occurred.

When an error is recorded, it is done so a as single unsigned long which is
composed of three parts.  The top byte is the 'library' number, the middle
12 bytes is the function code, and the bottom 12 bits is the 'reason' code.

Each 'library', or should a say, 'section' of the SSLeay library has a
different unique 'library' error number.  Each function in the library has
a number that is unique for that library.  Each 'library' also has a number
for each 'error reason' that is only unique for that 'library'.

Due to the way these error routines record a 'error trace', there is an
array per thread that is used to store the error codes.
The various functions in this library are used to access
and manipulate this array.

void ERR_put_error(int lib, int func,int reason);
	This routine records an error in library 'lib', function 'func'
and reason 'reason'.  As errors get 'put' into the buffer, they wrap
around and overwrite old errors if too many are written.  It is assumed
that the last errors are the most important.

unsigned long ERR_get_error(void );
	This function returns the last error added to the error buffer.
In effect it is popping the value off the buffer so repeated calls will
continue to return values until there are no more errors to return in which
case 0 is returned.

unsigned long ERR_peek_error(void );
	This function returns the value of the last error added to the
error buffer but does not 'pop' it from the buffer.

void ERR_clear_error(void );
	This function clears the error buffer, discarding all unread
errors.

While the above described error system obviously produces lots of different
error number, a method for 'reporting' these errors in a human readable
form is required.  To achieve this, each library has the option of
'registering' error strings.

typedef struct ERR_string_data_st
	{
	unsigned long error;
	char *string;
	} ERR_STRING_DATA;

The 'ERR_STRING_DATA' contains an error code and the corresponding text
string.  To add new function error strings for a library, the
ERR_STRING_DATA needs to be 'registered' with the library.

void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err);
	This function 'registers' the array of ERR_STRING_DATA pointed to by
'err' as error text strings for the error library 'lib'.

void ERR_free_strings(void);
	This function free()s all the loaded error strings.

char *ERR_error_string(unsigned long error,char *buf);
	This function returns a text string that is a human readable
version of the error represented by 'error'.  Buff should be at least 120
bytes long and if it is NULL, the return value is a pointer to a static
variable that will contain the error string, otherwise 'buf' is returned.
If there is not a text string registered for a particular error, a text
string containing the error number is returned instead.

void ERR_print_errors(BIO *bp);
void ERR_print_errors_fp(FILE *fp);
	This function is a convenience routine that prints the error string
for each error until all errors have been accounted for.

char *ERR_lib_error_string(unsigned long e);
char *ERR_func_error_string(unsigned long e);
char *ERR_reason_error_string(unsigned long e);
The above three functions return the 3 different components strings for the
error 'e'.  ERR_error_string() uses these functions.

void ERR_load_ERR_strings(void );
	This function 'registers' the error strings for the 'ERR' module.

void ERR_load_crypto_strings(void );
	This function 'register' the error strings for just about every
library in the SSLeay package except for the SSL routines.  There is no
need to ever register any error text strings and you will probably save in
program size.  If on the other hand you do 'register' all errors, it is
quite easy to determine why a particular routine failed.

As a final footnote as to why the error system is designed as it is.
1) I did not want a single 'global' error code.
2) I wanted to know which subroutine a failure occurred in.
3) For Windows NT etc, it should be simple to replace the 'key' routines
   with code to pass error codes back to the application.
4) I wanted the option of meaningful error text strings.

Late breaking news - the changes to support threads.

Each 'thread' has an 'ERR_STATE' state associated with it.
ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling
thread/process.

ERR_remove_state(unsigned long pid); will 'free()' this state.  If pid == 0
the current 'thread/process' will have it's error state removed.
If you do not remove the error state of a thread, this could be considered a
form of memory leak, so just after 'reaping' a thread that has died,
call ERR_remove_state(pid).

Have a read of thread.doc for more details for what is required for
multi-threading support.  All the other error routines will
work correctly when using threads.


==== idea.doc ========================================================

The IDEA library.
IDEA is a block cipher that operates on 64bit (8 byte) quantities.  It
uses a 128bit (16 byte) key.  It can be used in all the modes that DES can
be used.  This library implements the ecb, cbc, cfb64 and ofb64 modes.

For all calls that have an 'input' and 'output' variables, they can be the
same.

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

All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an 
argument.  An IDEA_KEY_SCHEDULE is an expanded form of the idea key.
For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for
decryption is different to the one used for encryption.

The define IDEA_ENCRYPT is passed to specify encryption for the functions
that require an encryption/decryption flag. IDEA_DECRYPT is passed to
specify decryption.  For some mode there is no encryption/decryption
flag since this is determined by the IDEA_KEY_SCHEDULE.

So to encrypt you would do the following
idea_set_encrypt_key(key,encrypt_ks);
idea_ecb_encrypt(...,encrypt_ks);
idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT);

To Decrypt
idea_set_encrypt_key(key,encrypt_ks);
idea_set_decrypt_key(encrypt_ks,decrypt_ks);
idea_ecb_encrypt(...,decrypt_ks);
idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT);

Please note that any of the encryption modes specified in my DES library
could be used with IDEA.  I have only implemented ecb, cbc, cfb64 and
ofb64 for the following reasons.
- ecb is the basic IDEA encryption.
- cbc is the normal 'chaining' form for block ciphers.
- cfb64 can be used to encrypt single characters, therefore input and output
  do not need to be a multiple of 8.
- ofb64 is similar to cfb64 but is more like a stream cipher, not as
  secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
- If you want triple IDEA, thats 384 bits of key and you must be totally
  obsessed with security.  Still, if you want it, it is simple enough to
  copy the function from the DES library and change the des_encrypt to
  idea_encrypt; an exercise left for the paranoid reader :-).

The functions are as follows:

void idea_set_encrypt_key(
unsigned char *key;
IDEA_KEY_SCHEDULE *ks);
	idea_set_encrypt_key converts a 16 byte IDEA key into an
	IDEA_KEY_SCHEDULE.  The IDEA_KEY_SCHEDULE is an expanded form of
	the key which can be used to perform IDEA encryption.
	An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to
	perform actual encryption.  It can be regenerated from the IDEA key
	so it only needs to be kept when encryption is about
	to occur.  Don't save or pass around IDEA_KEY_SCHEDULE's since they
	are CPU architecture dependent, IDEA keys are not.
	
void idea_set_decrypt_key(
IDEA_KEY_SCHEDULE *encrypt_ks,
IDEA_KEY_SCHEDULE *decrypt_ks);
	This functions converts an encryption IDEA_KEY_SCHEDULE into a
	decryption IDEA_KEY_SCHEDULE.  For all decryption, this conversion
	of the key must be done.  In some modes of IDEA, an
	encryption/decryption flag is also required, this is because these
	functions involve block chaining and the way this is done changes
	depending on which of encryption of decryption is being done.
	Please note that there is no quick way to generate the decryption
	key schedule other than generating the encryption key schedule and
	then converting it.

void idea_encrypt(
unsigned long *data,
IDEA_KEY_SCHEDULE *ks);
	This is the IDEA encryption function that gets called by just about
	every other IDEA routine in the library.  You should not use this
	function except to implement 'modes' of IDEA.  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.
	Data is a pointer to 2 unsigned long's and ks is the
	IDEA_KEY_SCHEDULE to use.  Encryption or decryption depends on the
	IDEA_KEY_SCHEDULE.

void idea_ecb_encrypt(
unsigned char *input,
unsigned char *output,
IDEA_KEY_SCHEDULE *ks);
	This is the basic Electronic Code Book form of IDEA (in DES this
	mode is called Electronic Code Book so I'm going to use the term
	for idea as well :-).
	Input is encrypted into output using the key represented by
	ks.  Depending on the IDEA_KEY_SCHEDULE, encryption or
	decryption occurs.  Input is 8 bytes long and output is 8 bytes.
	
void idea_cbc_encrypt(
unsigned char *input,
unsigned char *output,
long length,
IDEA_KEY_SCHEDULE *ks,
unsigned char *ivec,
int enc);
	This routine implements IDEA 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, bad 
	things will probably happen.  ivec is the initialisation vector.
	This function updates iv after each call so that it can be passed to
	the next call to idea_cbc_encrypt().
	
void idea_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 IDEA library, it
	implements CFB mode of IDEA with 64bit feedback.
	This allows you to encrypt an arbitrary number of bytes,
	you do not require 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.
	Enc is used to indicate encryption or decryption.
	One very important thing to remember is that when decrypting, use
	the encryption form of the key.
	CFB64 mode operates by using the cipher to
	generate a stream of bytes which is used to encrypt the plain text.
	The cipher text is then encrypted to generate the next 64 bits to
	be xored (incrementally) with the next 64 bits of plain
	text.  As can be seen from this, to encrypt or decrypt,
	the same 'cipher stream' needs to be generated but the way the next
	block of data is gathered for encryption is different for
	encryption and decryption.  What this means is that to encrypt
	idea_set_encrypt_key(key,ks);
	idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT)
	do decrypt
	idea_set_encrypt_key(key,ks)
	idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT)
	Note: The same IDEA_KEY_SCHEDULE but different encryption flags.
	For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be
	used to generate the IDEA_KEY_SCHEDULE for decryption.
	The reason I'm stressing this point is that I just wasted 3 hours
	today trying to decrypt using this mode and the decryption form of
	the key :-(.
	
void idea_ofb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
des_key_schedule ks,
des_cblock *ivec,
int *num);
	This functions implements OFB mode of IDEA with 64bit feedback.
	This allows you to encrypt an arbitrary number of bytes,
	you do not require 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.
	This is in effect a stream cipher, there is no encryption or
	decryption mode.  The same key and iv should be used to
	encrypt and decrypt.
	
For reading passwords, I suggest using des_read_pw_string() from my DES library.
To generate a password from a text string, I suggest using MD5 (or MD2) to
produce a 16 byte message digest that can then be passed directly to
idea_set_encrypt_key().

=====
For more information about the specific IDEA modes in this library
(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
documentation on my DES library.  What is said about DES is directly
applicable for IDEA.


==== legal.doc ========================================================

From eay@mincom.com Thu Jun 27 00:25:45 1996
Received: by orb.mincom.oz.au id AA15821
  (5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000
Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST)
From: Eric Young <eay@mincom.oz.au>
X-Sender: eay@orb
To: Ken Toll <ktoll@ren.digitalage.com>
Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com
Subject: Re: Unidentified subject!
In-Reply-To: <9606261950.ZM28943@ren.digitalage.com>
Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb>
Mime-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Status: O
X-Status: 


This is a little off topic but since SSLeay is a free implementation of
the SSLv2 protocol, I feel it is worth responding on the topic of if it 
is actually legal for Americans to use free cryptographic software.

On Wed, 26 Jun 1996, Ken Toll wrote:
> Is the U.S the only country that SSLeay cannot be used commercially 
> (because of RSAref) or is that going to be an issue with every country 
> that a client/server application (non-web browser/server) is deployed 
> and sold?

>From what I understand, the software patents that apply to algorithms 
like RSA and DH only apply in the USA.  The IDEA algorithm I believe is 
patened in europe (USA?), but considing how little it is used by other SSL 
implementations, it quite easily be left out of the SSLeay build
(this can be done with a compile flag).

Actually if the RSA patent did apply outside the USA, it could be rather
interesting since RSA is not alowed to let RSA toolkits outside of the USA
[1], and since these are the only forms that they will alow the algorithm
to be used in, it would mean that non-one outside of the USA could produce
public key software which would be a very strong statment for
international patent law to make :-).  This logic is a little flawed but
it still points out some of the more interesting permutations of USA
patent law and ITAR restrictions. 

Inside the USA there is also the unresolved issue of RC4/RC2 which were
made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2).  I have
copies of the origional postings if people are interested.  RSA I believe 
claim that they were 'trade-secrets' and that some-one broke an NDA in 
revealing them.  Other claim they reverse engineered the algorithms from 
compiled binaries.  If the algorithms were reverse engineered, I believe 
RSA had no legal leg to stand on.  If an NDA was broken, I don't know.
Regardless, RSA, I believe, is willing to go to court over the issue so 
licencing is probably the best idea, or at least talk to them.
If there are people who actually know more about this, pease let me know, I 
don't want to vilify or spread miss-information if I can help it.

If you are not producing a web browser, it is easy to build SSLeay with
RC2/RC4 removed. Since RC4 is the defacto standard cipher in 
all web software (and it is damn fast) it is more or less required for 
www use. For non www use of SSL, especially for an application where 
interoperability with other vendors is not critical just leave it out.

Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but 
they should be ok.  Considing that Triple DES can encrypt at rates of
410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite 
reasonable performance.  Single DES clocks in at 1160k/s and 2467k/s
respectivly is actually quite fast for those not so paranoid (56 bit key).[1]

> Is it possible to get a certificate for commercial use outside of the U.S.?
yes.

Thawte Consulting issues certificates (they are the people who sell the
	Sioux httpd server and are based in South Africa)
Verisign will issue certificates for Sioux (sold from South Africa), so this
	proves that they will issue certificate for OS use if they are
	happy with the quality of the software.

(The above mentioned companies just the ones that I know for sure are issuing
 certificates outside the USA).

There is always the point that if you are using SSL for an intra net, 
SSLeay provides programs that can be used so you can issue your own 
certificates.  They need polishing but at least it is a good starting point.

I am not doing anything outside Australian law by implementing these
algorithms (to the best of my knowedge).  It is another example of how 
the world legal system does not cope with the internet very well.

I may start making shared libraries available (I have now got DLL's for 
Windows).  This will mean that distributions into the usa could be 
shipped with a version with a reduced cipher set and the versions outside 
could use the DLL/shared library with all the ciphers (and without RSAref).

This could be completly hidden from the application, so this would not 
even require a re-linking.

This is the reverse of what people were talking about doing to get around 
USA export regulations :-)

eric

[1]:	The RSAref2.0 tookit is available on at least 3 ftp sites in Europe
	and one in South Africa.

[2]:	Since I always get questions when I post benchmark numbers :-),
	DES performace figures are in 1000's of bytes per second in cbc 
	mode using an 8192 byte buffer.  The pentium 100 was running Windows NT 
	3.51 DLLs and the 686/200 was running NextStep.
	I quote pentium 100 benchmarks because it is basically the
	'entry level' computer that most people buy for personal use.
	Windows 95 is the OS shipping on those boxes, so I'll give
	NT numbers (the same Win32 runtime environment).  The 686
	numbers are present as an indication of where we will be in a
	few years.
--
Eric Young                  | BOOL is tri-state according to Bill Gates.
AARNet: eay@mincom.oz.au    | RTFM Win32 GetMessage().



==== lhash.doc ========================================================

The LHASH library.

I wrote this library in 1991 and have since forgotten why I called it lhash.
It implements a hash table from an article I read at the
time from 'Communications of the ACM'.  What makes this hash
table different is that as the table fills, the hash table is
increased (or decreased) in size via realloc().
When a 'resize' is done, instead of all hashes being redistributed over
twice as many 'buckets', one bucket is split.  So when an 'expand' is done,
there is only a minimal cost to redistribute some values.  Subsequent
inserts will cause more single 'bucket' redistributions but there will
never be a sudden large cost due to redistributing all the 'buckets'.

The state for a particular hash table is kept in the LHASH structure.
The LHASH structure also records statistics about most aspects of accessing
the hash table.  This is mostly a legacy of my writing this library for
the reasons of implementing what looked like a nice algorithm rather than
for a particular software product.

Internal stuff you probably don't want to know about.
The decision to increase or decrease the hash table size is made depending
on the 'load' of the hash table.  The load is the number of items in the
hash table divided by the size of the hash table.  The default values are
as follows.  If (hash->up_load < load) => expand.
if (hash->down_load > load) =>  contract.  The 'up_load' has a default value of
1 and 'down_load' has a default value of 2.  These numbers can be modified
by the application by just playing with the 'up_load' and 'down_load'
variables.  The 'load' is kept in a form which is multiplied by 256.  So
hash->up_load=8*256; will cause a load of 8 to be set.

If you are interested in performance the field to watch is
num_comp_calls.  The hash library keeps track of the 'hash' value for
each item so when a lookup is done, the 'hashes' are compared, if
there is a match, then a full compare is done, and
hash->num_comp_calls is incremented.  If num_comp_calls is not equal
to num_delete plus num_retrieve it means that your hash function is
generating hashes that are the same for different values.  It is
probably worth changing your hash function if this is the case because
even if your hash table has 10 items in a 'bucked', it can be searched
with 10 'unsigned long' compares and 10 linked list traverses.  This
will be much less expensive that 10 calls to you compare function.

LHASH *lh_new(
unsigned long (*hash)(),
int (*cmp)());
	This function is used to create a new LHASH structure.  It is passed
	function pointers that are used to store and retrieve values passed
	into the hash table.  The 'hash'
	function is a hashing function that will return a hashed value of
	it's passed structure.  'cmp' is passed 2 parameters, it returns 0
	is they are equal, otherwise, non zero.
	If there are any problems (usually malloc failures), NULL is
	returned, otherwise a new LHASH structure is returned.  The
	hash value is normally truncated to a power of 2, so make sure
	that your hash function returns well mixed low order bits.
	
void lh_free(
LHASH *lh);
	This function free()s a LHASH structure.  If there is malloced
	data in the hash table, it will not be freed.  Consider using the
	lh_doall function to deallocate any remaining entries in the hash
	table.
	
char *lh_insert(
LHASH *lh,
char *data);
	This function inserts the data pointed to by data into the lh hash
	table.  If there is already and entry in the hash table entry, the
	value being replaced is returned.  A NULL is returned if the new
	entry does not clash with an entry already in the table (the normal
	case) or on a malloc() failure (perhaps I should change this....).
	The 'char *data' is exactly what is passed to the hash and
	comparison functions specified in lh_new().
	
char *lh_delete(
LHASH *lh,
char *data);
	This routine deletes an entry from the hash table.  The value being
	deleted is returned.  NULL is returned if there is no such value in
	the hash table.

char *lh_retrieve(
LHASH *lh,
char *data);
	If 'data' is in the hash table it is returned, else NULL is
	returned.  The way these routines would normally be uses is that a
	dummy structure would have key fields populated and then
	ret=lh_retrieve(hash,&dummy);.  Ret would now be a pointer to a fully
	populated structure.

void lh_doall(
LHASH *lh,
void (*func)(char *a));
	This function will, for every entry in the hash table, call function
	'func' with the data item as parameters.
	This function can be quite useful when used as follows.
	void cleanup(STUFF *a)
		{ STUFF_free(a); }
	lh_doall(hash,cleanup);
	lh_free(hash);
	This can be used to free all the entries, lh_free() then
	cleans up the 'buckets' that point to nothing.  Be careful
	when doing this.  If you delete entries from the hash table,
	in the call back function, the table may decrease in size,
	moving item that you are
	currently on down lower in the hash table.  This could cause
	some entries to be skipped.  The best solution to this problem
	is to set lh->down_load=0 before you start.  This will stop
	the hash table ever being decreased in size.

void lh_doall_arg(
LHASH *lh;
void(*func)(char *a,char *arg));
char *arg;
	This function is the same as lh_doall except that the function
	called will be passed 'arg' as the second argument.
	
unsigned long lh_strhash(
char *c);
	This function is a demo string hashing function.  Since the LHASH
	routines would normally be passed structures, this routine would
	not normally be passed to lh_new(), rather it would be used in the
	function passed to lh_new().

The next three routines print out various statistics about the state of the