The Cipher subroutines. These routines require "evp.h" to be included. These functions are a higher level interface to the various cipher routines found in this library. As such, they allow the same code to be used to encrypt and decrypt via different ciphers with only a change in an initial parameter. These routines also provide buffering for block ciphers. These routines all take a pointer to the following structure to specify which cipher to use. If you wish to use a new cipher with these routines, you would probably be best off looking an how an existing cipher is implemented and copying it. At this point in time, I'm not going to go into many details. This structure should be considered opaque typedef struct pem_cipher_st { int type; int block_size; int key_len; int iv_len; void (*enc_init)(); /* init for encryption */ void (*dec_init)(); /* init for decryption */ void (*do_cipher)(); /* encrypt data */ } EVP_CIPHER; The type field is the object NID of the cipher type (read the section on Objects for an explanation of what a NID is). The cipher block_size is how many bytes need to be passed to the cipher at a time. Key_len is the length of the key the cipher requires and iv_len is the length of the initialisation vector required. enc_init is the function called to initialise the ciphers context for encryption and dec_init is the function to initialise for decryption (they need to be different, especially for the IDEA cipher). One reason for specifying the Cipher via a pointer to a structure is that if you only use des-cbc, only the des-cbc routines will be included when you link the program. If you passed an integer that specified which cipher to use, the routine that mapped that integer to a set of cipher functions would cause all the ciphers to be link into the code. This setup also allows new ciphers to be added by the application (with some restrictions). The thirteen ciphers currently defined in this library are EVP_CIPHER *EVP_des_ecb(); /* DES in ecb mode, iv=0, block=8, key= 8 */ EVP_CIPHER *EVP_des_ede(); /* DES in ecb ede mode, iv=0, block=8, key=16 */ EVP_CIPHER *EVP_des_ede3(); /* DES in ecb ede mode, iv=0, block=8, key=24 */ EVP_CIPHER *EVP_des_cfb(); /* DES in cfb mode, iv=8, block=1, key= 8 */ EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */ EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */ EVP_CIPHER *EVP_des_ofb(); /* DES in ofb mode, iv=8, block=1, key= 8 */ EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */ EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */ EVP_CIPHER *EVP_des_cbc(); /* DES in cbc mode, iv=8, block=8, key= 8 */ EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */ EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */ EVP_CIPHER *EVP_desx_cbc(); /* DES in desx cbc mode,iv=8, block=8, key=24 */ EVP_CIPHER *EVP_rc4(); /* RC4, iv=0, block=1, key=16 */ EVP_CIPHER *EVP_idea_ecb(); /* IDEA in ecb mode, iv=0, block=8, key=16 */ EVP_CIPHER *EVP_idea_cfb(); /* IDEA in cfb mode, iv=8, block=1, key=16 */ EVP_CIPHER *EVP_idea_ofb(); /* IDEA in ofb mode, iv=8, block=1, key=16 */ EVP_CIPHER *EVP_idea_cbc(); /* IDEA in cbc mode, iv=8, block=8, key=16 */ EVP_CIPHER *EVP_rc2_ecb(); /* RC2 in ecb mode, iv=0, block=8, key=16 */ EVP_CIPHER *EVP_rc2_cfb(); /* RC2 in cfb mode, iv=8, block=1, key=16 */ EVP_CIPHER *EVP_rc2_ofb(); /* RC2 in ofb mode, iv=8, block=1, key=16 */ EVP_CIPHER *EVP_rc2_cbc(); /* RC2 in cbc mode, iv=8, block=8, key=16 */ EVP_CIPHER *EVP_bf_ecb(); /* Blowfish in ecb mode,iv=0, block=8, key=16 */ EVP_CIPHER *EVP_bf_cfb(); /* Blowfish in cfb mode,iv=8, block=1, key=16 */ EVP_CIPHER *EVP_bf_ofb(); /* Blowfish in ofb mode,iv=8, block=1, key=16 */ EVP_CIPHER *EVP_bf_cbc(); /* Blowfish in cbc mode,iv=8, block=8, key=16 */ The meaning of the compound names is as follows. des The base cipher is DES. idea The base cipher is IDEA rc4 The base cipher is RC4-128 rc2 The base cipher is RC2-128 ecb Electronic Code Book form of the cipher. cbc Cipher Block Chaining form of the cipher. cfb 64 bit Cipher Feedback form of the cipher. ofb 64 bit Output Feedback form of the cipher. ede The cipher is used in Encrypt, Decrypt, Encrypt mode. The first and last keys are the same. ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode. All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument. The state of the cipher is kept in this structure. typedef struct EVP_CIPHER_Ctx_st { EVP_CIPHER *cipher; int encrypt; /* encrypt or decrypt */ int buf_len; /* number we have left */ unsigned char buf[8]; union { .... /* cipher specific stuff */ } c; } EVP_CIPHER_CTX; Cipher is a pointer the the EVP_CIPHER for the current context. The encrypt flag indicates encryption or decryption. buf_len is the number of bytes currently being held in buf. The 'c' union holds the cipher specify context. The following functions are to be used. int EVP_read_pw_string( char *buf, int len, char *prompt, int verify, This function is the same as des_read_pw_string() (des.doc). void EVP_set_pw_prompt(char *prompt); This function sets the 'default' prompt to use to use in EVP_read_pw_string when the prompt parameter is NULL. If the prompt parameter is NULL, this 'default prompt' feature is turned off. Be warned, this is a global variable so weird things will happen if it is used under Win16 and care must be taken with a multi-threaded version of the library. char *EVP_get_pw_prompt(); This returns a pointer to the default prompt string. NULL if it is not set. int EVP_BytesToKey( EVP_CIPHER *type, EVP_MD *md, unsigned char *salt, unsigned char *data, int datal, int count, unsigned char *key, unsigned char *iv); This function is used to generate a key and an initialisation vector for a specified cipher from a key string and a salt. Type specifies the cipher the 'key' is being generated for. Md is the message digest algorithm to use to generate the key and iv. The salt is an optional 8 byte object that is used to help seed the key generator. If the salt value is NULL, it is just not used. Datal is the number of bytes to use from 'data' in the key generation. This function returns the key size for the specified cipher, if data is NULL, this value is returns and no other computation is performed. Count is the number of times to loop around the key generator. I would suggest leaving it's value as 1. Key and iv are the structures to place the returning iv and key in. If they are NULL, no value is generated for that particular value. The algorithm used is as follows /* M[] is an array of message digests * MD() is the message digest function */ M[0]=MD(data . salt); for (i=1; i key=M[0.. 8], iv=M[ 9 .. 16]. For key=16, iv=0 => key=M[0..16]. For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24]. For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32]. This routine will produce DES-CBC keys and iv that are compatible with the PKCS-5 standard when md2 or md5 are used. If md5 is used, the salt is NULL and count is 1, this routine will produce the password to key mapping normally used with RC4. I have attempted to logically extend the PKCS-5 standard to generate keys and iv for ciphers that require more than 16 bytes, if anyone knows what the correct standard is, please inform me. When using sha or sha1, things are a bit different under this scheme, since sha produces a 20 byte digest. So for ciphers requiring 24 bits of data, 20 will come from the first MD and 4 will come from the second. I have considered having a separate function so this 'routine' can be used without the requirement of passing a EVP_CIPHER *, but I have decided to not bother. If you wish to use the function without official EVP_CIPHER structures, just declare a local one and set the key_len and iv_len fields to the length you desire. The following routines perform encryption and decryption 'by parts'. By this I mean that there are groups of 3 routines. An Init function that is used to specify a cipher and initialise data structures. An Update routine that does encryption/decryption, one 'chunk' at a time. And finally a 'Final' function that finishes the encryption/decryption process. All these functions take a EVP_CIPHER pointer to specify which cipher to encrypt/decrypt with. They also take a EVP_CIPHER_CTX object as an argument. This structure is used to hold the state information associated with the operation in progress. void EVP_EncryptInit( EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *key, unsigned char *iv); This function initialise a EVP_CIPHER_CTX for encryption using the cipher passed in the 'type' field. The cipher is initialised to use 'key' as the key and 'iv' for the initialisation vector (if one is required). If the type, key or iv is NULL, the value currently in the EVP_CIPHER_CTX is reused. So to perform several decrypt using the same cipher, key and iv, initialise with the cipher, key and iv the first time and then for subsequent calls, reuse 'ctx' but pass NULL for type, key and iv. You must make sure to pass a key that is large enough for a particular cipher. I would suggest using the EVP_BytesToKey() function. void EVP_EncryptUpdate( EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl, unsigned char *in, int inl); This function takes 'inl' bytes from 'in' and outputs bytes encrypted by the cipher 'ctx' was initialised with into 'out'. The number of bytes written to 'out' is put into outl. If a particular cipher encrypts in blocks, less or more bytes than input may be output. Currently the largest block size used by supported ciphers is 8 bytes, so 'out' should have room for 'inl+7' bytes. Normally EVP_EncryptInit() is called once, followed by lots and lots of calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal call. void EVP_EncryptFinal( EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); Because quite a large number of ciphers are block ciphers, there is often an incomplete block to write out at the end of the encryption. EVP_EncryptFinal() performs processing on this last block. The last block in encoded in such a way that it is possible to determine how many bytes in the last block are valid. For 8 byte block size ciphers, if only 5 bytes in the last block are valid, the last three bytes will be filled with the value 3. If only 2 were valid, the other 6 would be filled with sixes. If all 8 bytes are valid, a extra 8 bytes are appended to the cipher stream containing nothing but 8 eights. These last bytes are output into 'out' and the number of bytes written is put into 'outl' These last bytes are output into 'out' and the number of bytes written is put into 'outl'. This form of block cipher finalisation is compatible with PKCS-5. Please remember that even if you are using ciphers like RC4 that has no blocking and so the function will not write anything into 'out', it would still be a good idea to pass a variable for 'out' that can hold 8 bytes just in case the cipher is changed some time in the future. It should also be remembered that the EVP_CIPHER_CTX contains the password and so when one has finished encryption with a particular EVP_CIPHER_CTX, it is good practice to zero the structure (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)). void EVP_DecryptInit( EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *key, unsigned char *iv); This function is basically the same as EVP_EncryptInit() accept that is prepares the EVP_CIPHER_CTX for decryption. void EVP_DecryptUpdate( EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl, unsigned char *in, int inl); This function is basically the same as EVP_EncryptUpdate() except that it performs decryption. There is one fundamental difference though. 'out' can not be the same as 'in' for any ciphers with a block size greater than 1 if more than one call to EVP_DecryptUpdate() will be made. This is because this routine can hold a 'partial' block between calls. When a partial block is decrypted (due to more bytes being passed via this function, they will be written to 'out' overwriting the input bytes in 'in' that have not been read yet. From this it should also be noted that 'out' should be at least one 'block size' larger than 'inl'. This problem only occurs on the second and subsequent call to EVP_DecryptUpdate() when using a block cipher. int EVP_DecryptFinal( EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); This function is different to EVP_EncryptFinal in that it 'removes' any padding bytes appended when the data was encrypted. Due to the way in which 1 to 8 bytes may have been appended when encryption using a block cipher, 'out' can end up with 0 to 7 bytes being put into it. When decoding the padding bytes, it is possible to detect an incorrect decryption. If the decryption appears to be wrong, 0 is returned. If everything seems ok, 1 is returned. For ciphers with a block size of 1 (RC4), this function would normally not return any bytes and would always return 1. Just because this function returns 1 does not mean the decryption was correct. It would normally be wrong due to either the wrong key/iv or corruption of the cipher data fed to EVP_DecryptUpdate(). As for EVP_EncryptFinal, it is a good idea to zero the EVP_CIPHER_CTX after use since the structure contains the key used to decrypt the data. The following Cipher routines are convenience routines that call either EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX was setup to encrypt or decrypt. void EVP_CipherInit( EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *key, unsigned char *iv, int enc); This function take arguments that are the same as EVP_EncryptInit() and EVP_DecryptInit() except for the extra 'enc' flag. If 1, the EVP_CIPHER_CTX is setup for encryption, if 0, decryption. void EVP_CipherUpdate( EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl, unsigned char *in, int inl); Again this function calls either EVP_EncryptUpdate() or EVP_DecryptUpdate() depending on state in the 'ctx' structure. As noted for EVP_DecryptUpdate(), when this routine is used for decryption with block ciphers, 'out' should not be the same as 'in'. int EVP_CipherFinal( EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); This routine call EVP_EncryptFinal() or EVP_DecryptFinal() depending on the state information in 'ctx'. 1 is always returned if the mode is encryption, otherwise the return value is the return value of EVP_DecryptFinal().