diff options
Diffstat (limited to 'doc/cipher.doc')
| -rw-r--r-- | doc/cipher.doc | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/doc/cipher.doc b/doc/cipher.doc new file mode 100644 index 0000000000..d49ba78c5c --- /dev/null +++ b/doc/cipher.doc @@ -0,0 +1,345 @@ +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<count; i++) M[0]=MD(M[0]); + + i=1 + while (data still needed for key and iv) + { + M[i]=MD(M[i-1] . data . salt); + for (i=1; i<count; i++) M[i]=MD(M[i]); + i++; + } + + If the salt is NULL, it is not used. + The digests are concatenated together. + M = M[0] . M[1] . M[2] ....... + + For key= 8, iv=8 => 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(). |