doc/cipher.doc

   1 The Cipher subroutines.
   2
   3 These routines require "evp.h" to be included.
   4
   5 These functions are a higher level interface to the various cipher
   6 routines found in this library.  As such, they allow the same code to be
   7 used to encrypt and decrypt via different ciphers with only a change
   8 in an initial parameter.  These routines also provide buffering for block
   9 ciphers.
  10
  11 These routines all take a pointer to the following structure to specify
  12 which cipher to use.  If you wish to use a new cipher with these routines,
  13 you would probably be best off looking an how an existing cipher is
  14 implemented and copying it.  At this point in time, I'm not going to go
  15 into many details.  This structure should be considered opaque
  16
  17 typedef struct pem_cipher_st
  18         {
  19         int type;
  20         int block_size;
  21         int key_len;
  22         int iv_len;
  23         void (*enc_init)();     /* init for encryption */
  24         void (*dec_init)();     /* init for decryption */
  25         void (*do_cipher)();    /* encrypt data */
  26         } EVP_CIPHER;
  27
  28 The type field is the object NID of the cipher type
  29 (read the section on Objects for an explanation of what a NID is).
  30 The cipher block_size is how many bytes need to be passed
  31 to the cipher at a time.  Key_len is the
  32 length of the key the cipher requires and iv_len is the length of the
  33 initialisation vector required.  enc_init is the function
  34 called to initialise the ciphers context for encryption and dec_init is the
  35 function to initialise for decryption (they need to be different, especially
  36 for the IDEA cipher).
  37
  38 One reason for specifying the Cipher via a pointer to a structure
  39 is that if you only use des-cbc, only the des-cbc routines will
  40 be included when you link the program.  If you passed an integer
  41 that specified which cipher to use, the routine that mapped that
  42 integer to a set of cipher functions would cause all the ciphers
  43 to be link into the code.  This setup also allows new ciphers
  44 to be added by the application (with some restrictions).
  45
  46 The thirteen ciphers currently defined in this library are
  47
  48 EVP_CIPHER *EVP_des_ecb();     /* DES in ecb mode,     iv=0, block=8, key= 8 */
  49 EVP_CIPHER *EVP_des_ede();     /* DES in ecb ede mode, iv=0, block=8, key=16 */
  50 EVP_CIPHER *EVP_des_ede3();    /* DES in ecb ede mode, iv=0, block=8, key=24 */
  51 EVP_CIPHER *EVP_des_cfb();     /* DES in cfb mode,     iv=8, block=1, key= 8 */
  52 EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */
  53 EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */
  54 EVP_CIPHER *EVP_des_ofb();     /* DES in ofb mode,     iv=8, block=1, key= 8 */
  55 EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */
  56 EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */
  57 EVP_CIPHER *EVP_des_cbc();     /* DES in cbc mode,     iv=8, block=8, key= 8 */
  58 EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */
  59 EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */
  60 EVP_CIPHER *EVP_desx_cbc();    /* DES in desx cbc mode,iv=8, block=8, key=24 */
  61 EVP_CIPHER *EVP_rc4();         /* RC4,                 iv=0, block=1, key=16 */
  62 EVP_CIPHER *EVP_idea_ecb();    /* IDEA in ecb mode,    iv=0, block=8, key=16 */
  63 EVP_CIPHER *EVP_idea_cfb();    /* IDEA in cfb mode,    iv=8, block=1, key=16 */
  64 EVP_CIPHER *EVP_idea_ofb();    /* IDEA in ofb mode,    iv=8, block=1, key=16 */
  65 EVP_CIPHER *EVP_idea_cbc();    /* IDEA in cbc mode,    iv=8, block=8, key=16 */
  66 EVP_CIPHER *EVP_rc2_ecb();     /* RC2 in ecb mode,     iv=0, block=8, key=16 */
  67 EVP_CIPHER *EVP_rc2_cfb();     /* RC2 in cfb mode,     iv=8, block=1, key=16 */
  68 EVP_CIPHER *EVP_rc2_ofb();     /* RC2 in ofb mode,     iv=8, block=1, key=16 */
  69 EVP_CIPHER *EVP_rc2_cbc();     /* RC2 in cbc mode,     iv=8, block=8, key=16 */
  70 EVP_CIPHER *EVP_bf_ecb();      /* Blowfish in ecb mode,iv=0, block=8, key=16 */
  71 EVP_CIPHER *EVP_bf_cfb();      /* Blowfish in cfb mode,iv=8, block=1, key=16 */
  72 EVP_CIPHER *EVP_bf_ofb();      /* Blowfish in ofb mode,iv=8, block=1, key=16 */
  73 EVP_CIPHER *EVP_bf_cbc();      /* Blowfish in cbc mode,iv=8, block=8, key=16 */
  74
  75 The meaning of the compound names is as follows.
  76 des     The base cipher is DES.
  77 idea    The base cipher is IDEA
  78 rc4     The base cipher is RC4-128
  79 rc2     The base cipher is RC2-128
  80 ecb     Electronic Code Book form of the cipher.
  81 cbc     Cipher Block Chaining form of the cipher.
  82 cfb     64 bit Cipher Feedback form of the cipher.
  83 ofb     64 bit Output Feedback form of the cipher.
  84 ede     The cipher is used in Encrypt, Decrypt, Encrypt mode.  The first
  85         and last keys are the same.
  86 ede3    The cipher is used in Encrypt, Decrypt, Encrypt mode.
  87
  88 All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument.
  89 The state of the cipher is kept in this structure.
  90
  91 typedef struct EVP_CIPHER_Ctx_st
  92         {
  93         EVP_CIPHER *cipher;
  94         int encrypt;            /* encrypt or decrypt */
  95         int buf_len;            /* number we have left */
  96         unsigned char buf[8];
  97         union   {
  98                 .... /* cipher specific stuff */
  99                 } c;
 100         } EVP_CIPHER_CTX;
 101
 102 Cipher is a pointer the the EVP_CIPHER for the current context.  The encrypt
 103 flag indicates encryption or decryption.  buf_len is the number of bytes
 104 currently being held in buf.
 105 The 'c' union holds the cipher specify context.
 106
 107 The following functions are to be used.
 108
 109 int EVP_read_pw_string(
 110 char *buf,
 111 int len,
 112 char *prompt,
 113 int verify,
 114         This function is the same as des_read_pw_string() (des.doc).
 115
 116 void EVP_set_pw_prompt(char *prompt);
 117         This function sets the 'default' prompt to use to use in
 118         EVP_read_pw_string when the prompt parameter is NULL.  If the
 119         prompt parameter is NULL, this 'default prompt' feature is turned
 120         off.  Be warned, this is a global variable so weird things
 121         will happen if it is used under Win16 and care must be taken
 122         with a multi-threaded version of the library.
 123
 124 char *EVP_get_pw_prompt();
 125         This returns a pointer to the default prompt string.  NULL
 126         if it is not set.
 127
 128 int EVP_BytesToKey(
 129 EVP_CIPHER *type,
 130 EVP_MD *md,
 131 unsigned char *salt,
 132 unsigned char *data,
 133 int datal,
 134 int count,
 135 unsigned char *key,
 136 unsigned char *iv);
 137         This function is used to generate a key and an initialisation vector
 138         for a specified cipher from a key string and a salt.  Type
 139         specifies the cipher the 'key' is being generated for.  Md is the
 140         message digest algorithm to use to generate the key and iv.  The salt
 141         is an optional 8 byte object that is used to help seed the key
 142         generator.
 143         If the salt value is NULL, it is just not used.  Datal is the
 144         number of bytes to use from 'data' in the key generation.
 145         This function returns the key size for the specified cipher, if
 146         data is NULL, this value is returns and no other
 147         computation is performed.  Count is
 148         the number of times to loop around the key generator.  I would
 149         suggest leaving it's value as 1.  Key and iv are the structures to
 150         place the returning iv and key in.  If they are NULL, no value is
 151         generated for that particular value.
 152         The algorithm used is as follows
 153
 154         /* M[] is an array of message digests
 155          * MD() is the message digest function */
 156         M[0]=MD(data . salt);
 157         for (i=1; i<count; i++) M[0]=MD(M[0]);
 158
 159         i=1
 160         while (data still needed for key and iv)
 161                 {
 162                 M[i]=MD(M[i-1] . data . salt);
 163                 for (i=1; i<count; i++) M[i]=MD(M[i]);
 164                 i++;
 165                 }
 166
 167         If the salt is NULL, it is not used.
 168         The digests are concatenated together.
 169         M = M[0] . M[1] . M[2] .......
 170
 171         For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16].
 172         For key=16, iv=0 => key=M[0..16].
 173         For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24].
 174         For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32].
 175
 176         This routine will produce DES-CBC keys and iv that are compatible
 177         with the PKCS-5 standard when md2 or md5 are used.  If md5 is
 178         used, the salt is NULL and count is 1, this routine will produce
 179         the password to key mapping normally used with RC4.
 180         I have attempted to logically extend the PKCS-5 standard to
 181         generate keys and iv for ciphers that require more than 16 bytes,
 182         if anyone knows what the correct standard is, please inform me.
 183         When using sha or sha1, things are a bit different under this scheme,
 184         since sha produces a 20 byte digest.  So for ciphers requiring
 185         24 bits of data, 20 will come from the first MD and 4 will
 186         come from the second.
 187
 188         I have considered having a separate function so this 'routine'
 189         can be used without the requirement of passing a EVP_CIPHER *,
 190         but I have decided to not bother.  If you wish to use the
 191         function without official EVP_CIPHER structures, just declare
 192         a local one and set the key_len and iv_len fields to the
 193         length you desire.
 194
 195 The following routines perform encryption and decryption 'by parts'.  By
 196 this I mean that there are groups of 3 routines.  An Init function that is
 197 used to specify a cipher and initialise data structures.  An Update routine
 198 that does encryption/decryption, one 'chunk' at a time.  And finally a
 199 'Final' function that finishes the encryption/decryption process.
 200 All these functions take a EVP_CIPHER pointer to specify which cipher to
 201 encrypt/decrypt with.  They also take a EVP_CIPHER_CTX object as an
 202 argument.  This structure is used to hold the state information associated
 203 with the operation in progress.
 204
 205 void EVP_EncryptInit(
 206 EVP_CIPHER_CTX *ctx,
 207 EVP_CIPHER *type,
 208 unsigned char *key,
 209 unsigned char *iv);
 210         This function initialise a EVP_CIPHER_CTX for encryption using the
 211         cipher passed in the 'type' field.  The cipher is initialised to use
 212         'key' as the key and 'iv' for the initialisation vector (if one is
 213         required).  If the type, key or iv is NULL, the value currently in the
 214         EVP_CIPHER_CTX is reused.  So to perform several decrypt
 215         using the same cipher, key and iv, initialise with the cipher,
 216         key and iv the first time and then for subsequent calls,
 217         reuse 'ctx' but pass NULL for type, key and iv.  You must make sure
 218         to pass a key that is large enough for a particular cipher.  I
 219         would suggest using the EVP_BytesToKey() function.
 220
 221 void EVP_EncryptUpdate(
 222 EVP_CIPHER_CTX *ctx,
 223 unsigned char *out,
 224 int *outl,
 225 unsigned char *in,
 226 int inl);
 227         This function takes 'inl' bytes from 'in' and outputs bytes
 228         encrypted by the cipher 'ctx' was initialised with into 'out'.  The
 229         number of bytes written to 'out' is put into outl.  If a particular
 230         cipher encrypts in blocks, less or more bytes than input may be
 231         output.  Currently the largest block size used by supported ciphers
 232         is 8 bytes, so 'out' should have room for 'inl+7' bytes.  Normally
 233         EVP_EncryptInit() is called once, followed by lots and lots of
 234         calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal
 235         call.
 236
 237 void EVP_EncryptFinal(
 238 EVP_CIPHER_CTX *ctx,
 239 unsigned char *out,
 240 int *outl);
 241         Because quite a large number of ciphers are block ciphers, there is
 242         often an incomplete block to write out at the end of the
 243         encryption.  EVP_EncryptFinal() performs processing on this last
 244         block.  The last block in encoded in such a way that it is possible
 245         to determine how many bytes in the last block are valid.  For 8 byte
 246         block size ciphers, if only 5 bytes in the last block are valid, the
 247         last three bytes will be filled with the value 3.  If only 2 were
 248         valid, the other 6 would be filled with sixes.  If all 8 bytes are
 249         valid, a extra 8 bytes are appended to the cipher stream containing
 250         nothing but 8 eights.  These last bytes are output into 'out' and
 251         the number of bytes written is put into 'outl'  These last bytes
 252         are output into 'out' and the number of bytes written is put into
 253         'outl'.  This form of block cipher finalisation is compatible with
 254         PKCS-5.  Please remember that even if you are using ciphers like
 255         RC4 that has no blocking and so the function will not write
 256         anything into 'out', it would still be a good idea to pass a
 257         variable for 'out' that can hold 8 bytes just in case the cipher is
 258         changed some time in the future.  It should also be remembered
 259         that the EVP_CIPHER_CTX contains the password and so when one has
 260         finished encryption with a particular EVP_CIPHER_CTX, it is good
 261         practice to zero the structure
 262         (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)).
 263
 264 void EVP_DecryptInit(
 265 EVP_CIPHER_CTX *ctx,
 266 EVP_CIPHER *type,
 267 unsigned char *key,
 268 unsigned char *iv);
 269         This function is basically the same as EVP_EncryptInit() accept that
 270         is prepares the EVP_CIPHER_CTX for decryption.
 271
 272 void EVP_DecryptUpdate(
 273 EVP_CIPHER_CTX *ctx,
 274 unsigned char *out,
 275 int *outl,
 276 unsigned char *in,
 277 int inl);
 278         This function is basically the same as EVP_EncryptUpdate()
 279         except that it performs decryption.  There is one
 280         fundamental difference though.  'out' can not be the same as
 281         'in' for any ciphers with a block size greater than 1 if more
 282         than one call to EVP_DecryptUpdate() will be made.  This
 283         is because this routine can hold a 'partial' block between
 284         calls.  When a partial block is decrypted (due to more bytes
 285         being passed via this function, they will be written to 'out'
 286         overwriting the input bytes in 'in' that have not been read
 287         yet.  From this it should also be noted that 'out' should
 288         be at least one 'block size' larger than 'inl'.  This problem
 289         only occurs on the second and subsequent call to
 290         EVP_DecryptUpdate() when using a block cipher.
 291
 292 int EVP_DecryptFinal(
 293 EVP_CIPHER_CTX *ctx,
 294 unsigned char *out,
 295 int *outl);
 296         This function is different to EVP_EncryptFinal in that it 'removes'
 297         any padding bytes appended when the data was encrypted.  Due to the
 298         way in which 1 to 8 bytes may have been appended when encryption
 299         using a block cipher, 'out' can end up with 0 to 7 bytes being put
 300         into it.  When decoding the padding bytes, it is possible to detect
 301         an incorrect decryption.  If the decryption appears to be wrong, 0
 302         is returned.  If everything seems ok, 1 is returned.  For ciphers
 303         with a block size of 1 (RC4), this function would normally not
 304         return any bytes and would always return 1.  Just because this
 305         function returns 1 does not mean the decryption was correct. It
 306         would normally be wrong due to either the wrong key/iv or
 307         corruption of the cipher data fed to EVP_DecryptUpdate().
 308         As for EVP_EncryptFinal, it is a good idea to zero the
 309         EVP_CIPHER_CTX after use since the structure contains the key used
 310         to decrypt the data.
 311
 312 The following Cipher routines are convenience routines that call either
 313 EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX
 314 was setup to encrypt or decrypt.
 315
 316 void EVP_CipherInit(
 317 EVP_CIPHER_CTX *ctx,
 318 EVP_CIPHER *type,
 319 unsigned char *key,
 320 unsigned char *iv,
 321 int enc);
 322         This function take arguments that are the same as EVP_EncryptInit()
 323         and EVP_DecryptInit() except for the extra 'enc' flag.  If 1, the
 324         EVP_CIPHER_CTX is setup for encryption, if 0, decryption.
 325
 326 void EVP_CipherUpdate(
 327 EVP_CIPHER_CTX *ctx,
 328 unsigned char *out,
 329 int *outl,
 330 unsigned char *in,
 331 int inl);
 332         Again this function calls either EVP_EncryptUpdate() or
 333         EVP_DecryptUpdate() depending on state in the 'ctx' structure.
 334         As noted for EVP_DecryptUpdate(), when this routine is used
 335         for decryption with block ciphers, 'out' should not be the
 336         same as 'in'.
 337
 338 int EVP_CipherFinal(
 339 EVP_CIPHER_CTX *ctx,
 340 unsigned char *outm,
 341 int *outl);
 342         This routine call EVP_EncryptFinal() or EVP_DecryptFinal()
 343         depending on the state information in 'ctx'.  1 is always returned
 344         if the mode is encryption, otherwise the return value is the return
 345         value of EVP_DecryptFinal().