diff options
Diffstat (limited to 'doc/rc2.doc')
| -rw-r--r-- | doc/rc2.doc | 165 |
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. + |