diff options
Diffstat (limited to 'doc/cipher.doc')
| -rw-r--r-- | doc/cipher.doc | 345 |
1 files changed, 0 insertions, 345 deletions
diff --git a/doc/cipher.doc b/doc/cipher.doc deleted file mode 100644 index d49ba78c5c..0000000000 --- a/doc/cipher.doc +++ /dev/null @@ -1,345 +0,0 @@ -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(). |