doc/idea.doc

   1 The IDEA library.
   2 IDEA is a block cipher that operates on 64bit (8 byte) quantities.  It
   3 uses a 128bit (16 byte) key.  It can be used in all the modes that DES can
   4 be used.  This library implements the ecb, cbc, cfb64 and ofb64 modes.
   5
   6 For all calls that have an 'input' and 'output' variables, they can be the
   7 same.
   8
   9 This library requires the inclusion of 'idea.h'.
  10
  11 All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an
  12 argument.  An IDEA_KEY_SCHEDULE is an expanded form of the idea key.
  13 For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for
  14 decryption is different to the one used for encryption.
  15
  16 The define IDEA_ENCRYPT is passed to specify encryption for the functions
  17 that require an encryption/decryption flag. IDEA_DECRYPT is passed to
  18 specify decryption.  For some mode there is no encryption/decryption
  19 flag since this is determined by the IDEA_KEY_SCHEDULE.
  20
  21 So to encrypt you would do the following
  22 idea_set_encrypt_key(key,encrypt_ks);
  23 idea_ecb_encrypt(...,encrypt_ks);
  24 idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT);
  25
  26 To Decrypt
  27 idea_set_encrypt_key(key,encrypt_ks);
  28 idea_set_decrypt_key(encrypt_ks,decrypt_ks);
  29 idea_ecb_encrypt(...,decrypt_ks);
  30 idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT);
  31
  32 Please note that any of the encryption modes specified in my DES library
  33 could be used with IDEA.  I have only implemented ecb, cbc, cfb64 and
  34 ofb64 for the following reasons.
  35 - ecb is the basic IDEA encryption.
  36 - cbc is the normal 'chaining' form for block ciphers.
  37 - cfb64 can be used to encrypt single characters, therefore input and output
  38   do not need to be a multiple of 8.
  39 - ofb64 is similar to cfb64 but is more like a stream cipher, not as
  40   secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
  41 - If you want triple IDEA, thats 384 bits of key and you must be totally
  42   obsessed with security.  Still, if you want it, it is simple enough to
  43   copy the function from the DES library and change the des_encrypt to
  44   idea_encrypt; an exercise left for the paranoid reader :-).
  45
  46 The functions are as follows:
  47
  48 void idea_set_encrypt_key(
  49 unsigned char *key;
  50 IDEA_KEY_SCHEDULE *ks);
  51         idea_set_encrypt_key converts a 16 byte IDEA key into an
  52         IDEA_KEY_SCHEDULE.  The IDEA_KEY_SCHEDULE is an expanded form of
  53         the key which can be used to perform IDEA encryption.
  54         An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to
  55         perform actual encryption.  It can be regenerated from the IDEA key
  56         so it only needs to be kept when encryption is about
  57         to occur.  Don't save or pass around IDEA_KEY_SCHEDULE's since they
  58         are CPU architecture dependent, IDEA keys are not.
  59
  60 void idea_set_decrypt_key(
  61 IDEA_KEY_SCHEDULE *encrypt_ks,
  62 IDEA_KEY_SCHEDULE *decrypt_ks);
  63         This functions converts an encryption IDEA_KEY_SCHEDULE into a
  64         decryption IDEA_KEY_SCHEDULE.  For all decryption, this conversion
  65         of the key must be done.  In some modes of IDEA, an
  66         encryption/decryption flag is also required, this is because these
  67         functions involve block chaining and the way this is done changes
  68         depending on which of encryption of decryption is being done.
  69         Please note that there is no quick way to generate the decryption
  70         key schedule other than generating the encryption key schedule and
  71         then converting it.
  72
  73 void idea_encrypt(
  74 unsigned long *data,
  75 IDEA_KEY_SCHEDULE *ks);
  76         This is the IDEA encryption function that gets called by just about
  77         every other IDEA routine in the library.  You should not use this
  78         function except to implement 'modes' of IDEA.  I say this because the
  79         functions that call this routine do the conversion from 'char *' to
  80         long, and this needs to be done to make sure 'non-aligned' memory
  81         access do not occur.
  82         Data is a pointer to 2 unsigned long's and ks is the
  83         IDEA_KEY_SCHEDULE to use.  Encryption or decryption depends on the
  84         IDEA_KEY_SCHEDULE.
  85
  86 void idea_ecb_encrypt(
  87 unsigned char *input,
  88 unsigned char *output,
  89 IDEA_KEY_SCHEDULE *ks);
  90         This is the basic Electronic Code Book form of IDEA (in DES this
  91         mode is called Electronic Code Book so I'm going to use the term
  92         for idea as well :-).
  93         Input is encrypted into output using the key represented by
  94         ks.  Depending on the IDEA_KEY_SCHEDULE, encryption or
  95         decryption occurs.  Input is 8 bytes long and output is 8 bytes.
  96
  97 void idea_cbc_encrypt(
  98 unsigned char *input,
  99 unsigned char *output,
 100 long length,
 101 IDEA_KEY_SCHEDULE *ks,
 102 unsigned char *ivec,
 103 int enc);
 104         This routine implements IDEA in Cipher Block Chaining mode.
 105         Input, which should be a multiple of 8 bytes is encrypted
 106         (or decrypted) to output which will also be a multiple of 8 bytes.
 107         The number of bytes is in length (and from what I've said above,
 108         should be a multiple of 8).  If length is not a multiple of 8, bad
 109         things will probably happen.  ivec is the initialisation vector.
 110         This function updates iv after each call so that it can be passed to
 111         the next call to idea_cbc_encrypt().
 112
 113 void idea_cfb64_encrypt(
 114 unsigned char *in,
 115 unsigned char *out,
 116 long length,
 117 des_key_schedule ks,
 118 des_cblock *ivec,
 119 int *num,
 120 int enc);
 121         This is one of the more useful functions in this IDEA library, it
 122         implements CFB mode of IDEA with 64bit feedback.
 123         This allows you to encrypt an arbitrary number of bytes,
 124         you do not require 8 byte padding.  Each call to this
 125         routine will encrypt the input bytes to output and then update ivec
 126         and num.  Num contains 'how far' we are though ivec.
 127         Enc is used to indicate encryption or decryption.
 128         One very important thing to remember is that when decrypting, use
 129         the encryption form of the key.
 130         CFB64 mode operates by using the cipher to
 131         generate a stream of bytes which is used to encrypt the plain text.
 132         The cipher text is then encrypted to generate the next 64 bits to
 133         be xored (incrementally) with the next 64 bits of plain
 134         text.  As can be seen from this, to encrypt or decrypt,
 135         the same 'cipher stream' needs to be generated but the way the next
 136         block of data is gathered for encryption is different for
 137         encryption and decryption.  What this means is that to encrypt
 138         idea_set_encrypt_key(key,ks);
 139         idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT)
 140         do decrypt
 141         idea_set_encrypt_key(key,ks)
 142         idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT)
 143         Note: The same IDEA_KEY_SCHEDULE but different encryption flags.
 144         For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be
 145         used to generate the IDEA_KEY_SCHEDULE for decryption.
 146         The reason I'm stressing this point is that I just wasted 3 hours
 147         today trying to decrypt using this mode and the decryption form of
 148         the key :-(.
 149
 150 void idea_ofb64_encrypt(
 151 unsigned char *in,
 152 unsigned char *out,
 153 long length,
 154 des_key_schedule ks,
 155 des_cblock *ivec,
 156 int *num);
 157         This functions implements OFB mode of IDEA with 64bit feedback.
 158         This allows you to encrypt an arbitrary number of bytes,
 159         you do not require 8 byte padding.  Each call to this
 160         routine will encrypt the input bytes to output and then update ivec
 161         and num.  Num contains 'how far' we are though ivec.
 162         This is in effect a stream cipher, there is no encryption or
 163         decryption mode.  The same key and iv should be used to
 164         encrypt and decrypt.
 165
 166 For reading passwords, I suggest using des_read_pw_string() from my DES library.
 167 To generate a password from a text string, I suggest using MD5 (or MD2) to
 168 produce a 16 byte message digest that can then be passed directly to
 169 idea_set_encrypt_key().
 170
 171 =====
 172 For more information about the specific IDEA modes in this library
 173 (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
 174 documentation on my DES library.  What is said about DES is directly
 175 applicable for IDEA.
 176