doc/rc2.doc

   1 The RC2 library.
   2
   3 RC2 is a block cipher that operates on 64bit (8 byte) quantities.  It
   4 uses variable size key, but 128bit (16 byte) key would normally be considered
   5 good.  It can be used in all the modes that DES can be used.  This
   6 library implements the ecb, cbc, cfb64, ofb64 modes.
   7
   8 I have implemented this library from an article posted to sci.crypt on
   9 11-Feb-1996.  I personally don't know how far to trust the RC2 cipher.
  10 While it is capable of having a key of any size, not much reseach has
  11 publically been done on it at this point in time (Apr-1996)
  12 since the cipher has only been public for a few months :-)
  13 It is of a similar speed to DES and IDEA, so unless it is required for
  14 meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable
  15 to stick to IDEA, or for the paranoid, Tripple DES.
  16
  17 Mind you, having said all that, I should mention that I just read alot and
  18 implement ciphers, I'm a 'babe in the woods' when it comes to evaluating
  19 ciphers :-).
  20
  21 For all calls that have an 'input' and 'output' variables, they can be the
  22 same.
  23
  24 This library requires the inclusion of 'rc2.h'.
  25
  26 All of the encryption functions take what is called an RC2_KEY as an
  27 argument.  An RC2_KEY is an expanded form of the RC2 key.
  28 For all modes of the RC2 algorithm, the RC2_KEY used for
  29 decryption is the same one that was used for encryption.
  30
  31 The define RC2_ENCRYPT is passed to specify encryption for the functions
  32 that require an encryption/decryption flag. RC2_DECRYPT is passed to
  33 specify decryption.
  34
  35 Please note that any of the encryption modes specified in my DES library
  36 could be used with RC2.  I have only implemented ecb, cbc, cfb64 and
  37 ofb64 for the following reasons.
  38 - ecb is the basic RC2 encryption.
  39 - cbc is the normal 'chaining' form for block ciphers.
  40 - cfb64 can be used to encrypt single characters, therefore input and output
  41   do not need to be a multiple of 8.
  42 - ofb64 is similar to cfb64 but is more like a stream cipher, not as
  43   secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
  44 - If you want triple RC2, thats 384 bits of key and you must be totally
  45   obsessed with security.  Still, if you want it, it is simple enough to
  46   copy the function from the DES library and change the des_encrypt to
  47   RC2_encrypt; an exercise left for the paranoid reader :-).
  48
  49 The functions are as follows:
  50
  51 void RC2_set_key(
  52 RC2_KEY *ks;
  53 int len;
  54 unsigned char *key;
  55 int bits;
  56         RC2_set_key converts an 'len' byte key into a RC2_KEY.
  57         A 'ks' is an expanded form of the 'key' which is used to
  58         perform actual encryption.  It can be regenerated from the RC2 key
  59         so it only needs to be kept when encryption or decryption is about
  60         to occur.  Don't save or pass around RC2_KEY's since they
  61         are CPU architecture dependent, 'key's are not.  RC2 is an
  62         interesting cipher in that it can be used with a variable length
  63         key.  'len' is the length of 'key' to be used as the key.
  64         A 'len' of 16 is recomended.  The 'bits' argument is an
  65         interesting addition which I only found out about in Aug 96.
  66         BSAFE uses this parameter to 'limit' the number of bits used
  67         for the key.  To use the 'key' unmodified, set bits to 1024.
  68         This is what old versions of my RC2 library did (SSLeay 0.6.3).
  69         RSAs BSAFE library sets this parameter to be 128 if 128 bit
  70         keys are being used.  So to be compatable with BSAFE, set it
  71         to 128, if you don't want to reduce RC2's key length, leave it
  72         at 1024.
  73
  74 void RC2_encrypt(
  75 unsigned long *data,
  76 RC2_KEY *key,
  77 int encrypt);
  78         This is the RC2 encryption function that gets called by just about
  79         every other RC2 routine in the library.  You should not use this
  80         function except to implement 'modes' of RC2.  I say this because the
  81         functions that call this routine do the conversion from 'char *' to
  82         long, and this needs to be done to make sure 'non-aligned' memory
  83         access do not occur.
  84         Data is a pointer to 2 unsigned long's and key is the
  85         RC2_KEY to use.  Encryption or decryption is indicated by 'encrypt'.
  86         which can have the values RC2_ENCRYPT or RC2_DECRYPT.
  87
  88 void RC2_ecb_encrypt(
  89 unsigned char *in,
  90 unsigned char *out,
  91 RC2_KEY *key,
  92 int encrypt);
  93         This is the basic Electronic Code Book form of RC2 (in DES this
  94         mode is called Electronic Code Book so I'm going to use the term
  95         for rc2 as well.
  96         Input is encrypted into output using the key represented by
  97         key.  Depending on the encrypt, encryption or
  98         decryption occurs.  Input is 8 bytes long and output is 8 bytes.
  99
 100 void RC2_cbc_encrypt(
 101 unsigned char *in,
 102 unsigned char *out,
 103 long length,
 104 RC2_KEY *ks,
 105 unsigned char *ivec,
 106 int encrypt);
 107         This routine implements RC2 in Cipher Block Chaining mode.
 108         Input, which should be a multiple of 8 bytes is encrypted
 109         (or decrypted) to output which will also be a multiple of 8 bytes.
 110         The number of bytes is in length (and from what I've said above,
 111         should be a multiple of 8).  If length is not a multiple of 8, bad
 112         things will probably happen.  ivec is the initialisation vector.
 113         This function updates iv after each call so that it can be passed to
 114         the next call to RC2_cbc_encrypt().
 115
 116 void RC2_cfb64_encrypt(
 117 unsigned char *in,
 118 unsigned char *out,
 119 long length,
 120 RC2_KEY *schedule,
 121 unsigned char *ivec,
 122 int *num,
 123 int encrypt);
 124         This is one of the more useful functions in this RC2 library, it
 125         implements CFB mode of RC2 with 64bit feedback.
 126         This allows you to encrypt an arbitrary number of bytes,
 127         you do not require 8 byte padding.  Each call to this
 128         routine will encrypt the input bytes to output and then update ivec
 129         and num.  Num contains 'how far' we are though ivec.
 130         'Encrypt' is used to indicate encryption or decryption.
 131         CFB64 mode operates by using the cipher to generate a stream
 132         of bytes which is used to encrypt the plain text.
 133         The cipher text is then encrypted to generate the next 64 bits to
 134         be xored (incrementally) with the next 64 bits of plain
 135         text.  As can be seen from this, to encrypt or decrypt,
 136         the same 'cipher stream' needs to be generated but the way the next
 137         block of data is gathered for encryption is different for
 138         encryption and decryption.
 139
 140 void RC2_ofb64_encrypt(
 141 unsigned char *in,
 142 unsigned char *out,
 143 long length,
 144 RC2_KEY *schedule,
 145 unsigned char *ivec,
 146 int *num);
 147         This functions implements OFB mode of RC2 with 64bit feedback.
 148         This allows you to encrypt an arbitrary number of bytes,
 149         you do not require 8 byte padding.  Each call to this
 150         routine will encrypt the input bytes to output and then update ivec
 151         and num.  Num contains 'how far' we are though ivec.
 152         This is in effect a stream cipher, there is no encryption or
 153         decryption mode.
 154
 155 For reading passwords, I suggest using des_read_pw_string() from my DES library.
 156 To generate a password from a text string, I suggest using MD5 (or MD2) to
 157 produce a 16 byte message digest that can then be passed directly to
 158 RC2_set_key().
 159
 160 =====
 161 For more information about the specific RC2 modes in this library
 162 (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
 163 documentation on my DES library.  What is said about DES is directly
 164 applicable for RC2.
 165