Import of old SSLeay release: SSLeay 0.8.1b

1 files changed, 165 insertions, 0 deletions

diff --git a/doc/rc2.doc b/doc/rc2.doc
new file mode 100644
index 0000000000..efab015bd1
--- /dev/null
+++ b/doc/rc2.doc
@@ -0,0 +1,165 @@
+The RC2 library.
+
+RC2 is a block cipher that operates on 64bit (8 byte) quantities.  It
+uses variable size key, but 128bit (16 byte) key would normally be considered
+good.  It can be used in all the modes that DES can be used.  This
+library implements the ecb, cbc, cfb64, ofb64 modes.
+
+I have implemented this library from an article posted to sci.crypt on
+11-Feb-1996.  I personally don't know how far to trust the RC2 cipher.
+While it is capable of having a key of any size, not much reseach has
+publically been done on it at this point in time (Apr-1996)
+since the cipher has only been public for a few months :-)
+It is of a similar speed to DES and IDEA, so unless it is required for
+meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable
+to stick to IDEA, or for the paranoid, Tripple DES.
+
+Mind you, having said all that, I should mention that I just read alot and
+implement ciphers, I'm a 'babe in the woods' when it comes to evaluating
+ciphers :-).
+
+For all calls that have an 'input' and 'output' variables, they can be the
+same.
+
+This library requires the inclusion of 'rc2.h'.
+
+All of the encryption functions take what is called an RC2_KEY as an 
+argument.  An RC2_KEY is an expanded form of the RC2 key.
+For all modes of the RC2 algorithm, the RC2_KEY used for
+decryption is the same one that was used for encryption.
+
+The define RC2_ENCRYPT is passed to specify encryption for the functions
+that require an encryption/decryption flag. RC2_DECRYPT is passed to
+specify decryption.
+
+Please note that any of the encryption modes specified in my DES library
+could be used with RC2.  I have only implemented ecb, cbc, cfb64 and
+ofb64 for the following reasons.
+- ecb is the basic RC2 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 RC2, 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
+  RC2_encrypt; an exercise left for the paranoid reader :-).
+
+The functions are as follows:
+
+void RC2_set_key(
+RC2_KEY *ks;
+int len;
+unsigned char *key;
+int bits;
+        RC2_set_key converts an 'len' byte key into a RC2_KEY.
+        A 'ks' is an expanded form of the 'key' which is used to
+        perform actual encryption.  It can be regenerated from the RC2 key
+        so it only needs to be kept when encryption or decryption is about
+        to occur.  Don't save or pass around RC2_KEY's since they
+        are CPU architecture dependent, 'key's are not.  RC2 is an
+	interesting cipher in that it can be used with a variable length
+	key.  'len' is the length of 'key' to be used as the key.
+	A 'len' of 16 is recomended.  The 'bits' argument is an
+	interesting addition which I only found out about in Aug 96.
+	BSAFE uses this parameter to 'limit' the number of bits used
+	for the key.  To use the 'key' unmodified, set bits to 1024.
+	This is what old versions of my RC2 library did (SSLeay 0.6.3).
+	RSAs BSAFE library sets this parameter to be 128 if 128 bit
+	keys are being used.  So to be compatable with BSAFE, set it
+	to 128, if you don't want to reduce RC2's key length, leave it
+	at 1024.
+	
+void RC2_encrypt(
+unsigned long *data,
+RC2_KEY *key,
+int encrypt);
+	This is the RC2 encryption function that gets called by just about
+	every other RC2 routine in the library.  You should not use this
+	function except to implement 'modes' of RC2.  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 key is the
+	RC2_KEY to use.  Encryption or decryption is indicated by 'encrypt'.
+	which can have the values RC2_ENCRYPT or RC2_DECRYPT.
+
+void RC2_ecb_encrypt(
+unsigned char *in,
+unsigned char *out,
+RC2_KEY *key,
+int encrypt);
+	This is the basic Electronic Code Book form of RC2 (in DES this
+	mode is called Electronic Code Book so I'm going to use the term
+	for rc2 as well.
+	Input is encrypted into output using the key represented by
+	key.  Depending on the encrypt, encryption or
+	decryption occurs.  Input is 8 bytes long and output is 8 bytes.
+	
+void RC2_cbc_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+RC2_KEY *ks,
+unsigned char *ivec,
+int encrypt);
+	This routine implements RC2 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 RC2_cbc_encrypt().
+	
+void RC2_cfb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+RC2_KEY *schedule,
+unsigned char *ivec,
+int *num,
+int encrypt);
+	This is one of the more useful functions in this RC2 library, it
+	implements CFB mode of RC2 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.
+	'Encrypt' is used to indicate encryption or decryption.
+	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.
+	
+void RC2_ofb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+RC2_KEY *schedule,
+unsigned char *ivec,
+int *num);
+	This functions implements OFB mode of RC2 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.
+	
+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
+RC2_set_key().
+
+=====
+For more information about the specific RC2 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 RC2.
+