The Cipher subroutines.
These routines require "envelope.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();
key= 8 */
EVP_CIPHER *EVP_des_ede();
key=16 */
/* DES in ecb mode,
iv=0, block=8,
/* DES in ecb ede mode, iv=0, block=8,
EVP_CIPHER
key=24 */
EVP_CIPHER
key= 8 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=24 */
EVP_CIPHER
key= 8 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=24 */
EVP_CIPHER
key= 8 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=24 */
EVP_CIPHER
key=24 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=16 */
EVP_CIPHER
key=16 */
*EVP_des_ede3();
/* DES in ecb ede mode, iv=0, block=8,
*EVP_des_cfb();
/* DES in cfb mode,
iv=8, block=1,
*EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1,
*EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1,
*EVP_des_ofb();
/* DES in ofb mode,
iv=8, block=1,
*EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1,
*EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1,
*EVP_des_cbc();
/* DES in cbc mode,
iv=8, block=8,
*EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8,
*EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8,
*EVP_desx_cbc();
/* DES in desx cbc mode,iv=8, block=8,
*EVP_rc4();
/* RC4,
iv=0, block=1,
*EVP_idea_ecb();
/* IDEA in ecb mode,
iv=0, block=8,
*EVP_idea_cfb();
/* IDEA in cfb mode,
iv=8, block=1,
*EVP_idea_ofb();
/* IDEA in ofb mode,
iv=8, block=1,
*EVP_idea_cbc();
/* IDEA in cbc mode,
iv=8, block=8,
*EVP_rc2_ecb();
/* RC2 in ecb mode,
iv=0, block=8,
*EVP_rc2_cfb();
/* RC2 in cfb mode,
iv=8, block=1,
*EVP_rc2_ofb();
/* RC2 in ofb mode,
iv=8, block=1,
*EVP_rc2_cbc();
/* RC2 in cbc mode,
iv=8, block=8,
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.
and last keys are the same.
ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode.
The first
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.
if it is not set.
NULL
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
For
For
For
key= 8,
key=16,
key=16,
key=24,
iv=8
iv=0
iv=8
iv=8
=>
=>
=>
=>
key=M[0.. 8], iv=M[ 9 .. 16].
key=M[0..16].
key=M[0..16], iv=M[17 .. 24].
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().