359 lines
15 KiB
Text
359 lines
15 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal, EVP_DecryptInit,
|
|
EVP_DecryptUpdate, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherUpdate,
|
|
EVP_CipherFinal, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl,
|
|
EVP_CIPHER_CTX_cleanup, EVP_get_cipherbyname, EVP_get_cipherbynid,
|
|
EVP_get_cipherbyobj, EVP_CIPHER_nid, EVP_CIPHER_block_size,
|
|
EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags,
|
|
EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_nid,
|
|
EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length,
|
|
EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type,
|
|
EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1,
|
|
EVP_CIPHER_asn1_to_param - EVP cipher routines
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/evp.h>
|
|
|
|
int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
unsigned char *key, unsigned char *iv);
|
|
int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
|
|
int *outl, unsigned char *in, int inl);
|
|
int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
|
|
int *outl);
|
|
|
|
int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
unsigned char *key, unsigned char *iv);
|
|
int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
|
|
int *outl, unsigned char *in, int inl);
|
|
int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
|
|
int *outl);
|
|
|
|
int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
|
|
unsigned char *key, unsigned char *iv, int enc);
|
|
int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
|
|
int *outl, unsigned char *in, int inl);
|
|
int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
|
|
int *outl);
|
|
|
|
int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
|
|
int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
|
|
int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);
|
|
|
|
const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
|
|
#define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
|
|
#define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a))
|
|
|
|
#define EVP_CIPHER_nid(e) ((e)->nid)
|
|
#define EVP_CIPHER_block_size(e) ((e)->block_size)
|
|
#define EVP_CIPHER_key_length(e) ((e)->key_len)
|
|
#define EVP_CIPHER_iv_length(e) ((e)->iv_len)
|
|
#define EVP_CIPHER_flags(e) ((e)->flags)
|
|
#define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE)
|
|
int EVP_CIPHER_type(const EVP_CIPHER *ctx);
|
|
|
|
#define EVP_CIPHER_CTX_cipher(e) ((e)->cipher)
|
|
#define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid)
|
|
#define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size)
|
|
#define EVP_CIPHER_CTX_key_length(e) ((e)->key_len)
|
|
#define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len)
|
|
#define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data)
|
|
#define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
|
|
#define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
|
|
#define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags)
|
|
#define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE)
|
|
|
|
int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
|
|
int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The EVP cipher routines are a high level interface to certain
|
|
symmetric ciphers.
|
|
|
|
EVP_EncryptInit() initializes a cipher context B<ctx> for encryption
|
|
with cipher B<type>. B<type> is normally supplied by a function such
|
|
as EVP_des_cbc() . B<key> is the symmetric key to use and B<iv> is the
|
|
IV to use (if necessary), the actual number of bytes used for the
|
|
key and IV depends on the cipher. It is possible to set all parameters
|
|
to NULL except B<type> in an initial call and supply the remaining
|
|
parameters in subsequent calls, all of which have B<type> set to NULL.
|
|
This is done when the default cipher parameters are not appropriate.
|
|
|
|
EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
|
|
writes the encrypted version to B<out>. This function can be called
|
|
multiple times to encrypt successive blocks of data. The amount
|
|
of data written depends on the block alignment of the encrypted data:
|
|
as a result the amount of data written may be anything from zero bytes
|
|
to (inl + cipher_block_size - 1) so B<outl> should contain sufficient
|
|
room. The actual number of bytes written is placed in B<outl>.
|
|
|
|
EVP_EncryptFinal() encrypts the "final" data, that is any data that
|
|
remains in a partial block. It uses L<standard block padding|/NOTES> (aka PKCS
|
|
padding). The encrypted final data is written to B<out> which should
|
|
have sufficient space for one cipher block. The number of bytes written
|
|
is placed in B<outl>. After this function is called the encryption operation
|
|
is finished and no further calls to EVP_EncryptUpdate() should be made.
|
|
|
|
EVP_DecryptInit(), EVP_DecryptUpdate() and EVP_DecryptFinal() are the
|
|
corresponding decryption operations. EVP_DecryptFinal() will return an
|
|
error code if the final block is not correctly formatted. The parameters
|
|
and restrictions are identical to the encryption operations except that
|
|
the decrypted data buffer B<out> passed to EVP_DecryptUpdate() should
|
|
have sufficient room for (B<inl> + cipher_block_size) bytes unless the
|
|
cipher block size is 1 in which case B<inl> bytes is sufficient.
|
|
|
|
EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal() are functions
|
|
that can be used for decryption or encryption. The operation performed
|
|
depends on the value of the B<enc> parameter. It should be set to 1 for
|
|
encryption, 0 for decryption and -1 to leave the value unchanged (the
|
|
actual value of 'enc' being supplied in a previous call).
|
|
|
|
EVP_CIPHER_CTX_cleanup() clears all information from a cipher context.
|
|
It should be called after all operations using a cipher are complete
|
|
so sensitive information does not remain in memory.
|
|
|
|
EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
|
|
return an EVP_CIPHER structure when passed a cipher name, a NID or an
|
|
ASN1_OBJECT structure.
|
|
|
|
EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when
|
|
passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID
|
|
value is an internal value which may not have a corresponding OBJECT
|
|
IDENTIFIER.
|
|
|
|
EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
|
|
length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
|
|
structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
|
|
for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
|
|
given cipher, the value of EVP_CIPHER_CTX_key_length() may be different
|
|
for variable key length ciphers.
|
|
|
|
EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
|
|
If the cipher is a fixed length cipher then attempting to set the key
|
|
length to any value other than the fixed value is an error.
|
|
|
|
EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
|
|
length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
|
|
It will return zero if the cipher does not use an IV. The constant
|
|
B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
|
|
|
|
EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
|
|
size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
|
|
structure. The constant B<EVP_MAX_IV_LENGTH> is also the maximum block
|
|
length for all ciphers.
|
|
|
|
EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed
|
|
cipher or context. This "type" is the actual NID of the cipher OBJECT
|
|
IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
|
|
128 bit RC2 have the same NID. If the cipher does not have an object
|
|
identifier or does not have ASN1 support this function will return
|
|
B<NID_undef>.
|
|
|
|
EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
|
|
an B<EVP_CIPHER_CTX> structure.
|
|
|
|
EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
|
|
EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
|
|
EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then
|
|
EVP_CIPH_STREAM_CIPHER is returned.
|
|
|
|
EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
|
|
on the passed cipher. This will typically include any parameters and an
|
|
IV. The cipher IV (if any) must be set when this call is made. This call
|
|
should be made before the cipher is actually "used" (before any
|
|
EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function
|
|
may fail if the cipher does not have any ASN1 support.
|
|
|
|
EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
|
|
AlgorithmIdentifier "parameter". The precise effect depends on the cipher
|
|
In the case of RC2, for example, it will set the IV and effective key length.
|
|
This function should be called after the base cipher type is set but before
|
|
the key is set. For example EVP_CipherInit() will be called with the IV and
|
|
key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
|
|
EVP_CipherInit() again with all parameters except the key set to NULL. It is
|
|
possible for this function to fail if the cipher does not have any ASN1 support
|
|
or the parameters cannot be set (for example the RC2 effective key length
|
|
is not supported.
|
|
|
|
EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
|
|
and set. Currently only the RC2 effective key length and the number of rounds of
|
|
RC5 can be set.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() return 1 for success
|
|
and 0 for failure.
|
|
|
|
EVP_DecryptInit() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
|
|
EVP_DecryptFinal() returns 0 if the decrypt failed or 1 for success.
|
|
|
|
EVP_CipherInit() and EVP_CipherUpdate() return 1 for success and 0 for failure.
|
|
EVP_CipherFinal() returns 1 for a decryption failure or 1 for success.
|
|
|
|
EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
|
|
|
|
EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
|
|
return an B<EVP_CIPHER> structure or NULL on error.
|
|
|
|
EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
|
|
|
|
EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
|
|
size.
|
|
|
|
EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
|
|
length.
|
|
|
|
EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
|
|
length or zero if the cipher does not use an IV.
|
|
|
|
EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's
|
|
OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
|
|
|
|
EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
|
|
|
|
EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for
|
|
success or zero for failure.
|
|
|
|
=head1 CIPHER LISTING
|
|
|
|
All algorithms have a fixed key length unless otherwise stated.
|
|
|
|
=over 4
|
|
|
|
=item EVP_enc_null()
|
|
|
|
Null cipher: does nothing.
|
|
|
|
=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)
|
|
|
|
DES in CBC, ECB, CFB and OFB modes respectively.
|
|
|
|
=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)
|
|
|
|
Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
|
|
|
|
=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void)
|
|
|
|
Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
|
|
|
|
=item EVP_desx_cbc(void)
|
|
|
|
DESX algorithm in CBC mode.
|
|
|
|
=item EVP_rc4(void)
|
|
|
|
RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.
|
|
|
|
=item EVP_rc4_40(void)
|
|
|
|
RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4()
|
|
and the EVP_CIPHER_CTX_set_key_length() function.
|
|
|
|
=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void)
|
|
|
|
IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
|
|
|
|
=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)
|
|
|
|
RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
|
|
length cipher with an additional parameter called "effective key bits" or "effective key length".
|
|
By default both are set to 128 bits.
|
|
|
|
=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)
|
|
|
|
RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits.
|
|
These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and
|
|
EVP_CIPHER_CTX_ctrl() to set the key length and effective key length.
|
|
|
|
=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);
|
|
|
|
Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
|
|
length cipher.
|
|
|
|
=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)
|
|
|
|
CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
|
|
length cipher.
|
|
|
|
=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)
|
|
|
|
RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length
|
|
cipher with an additional "number of rounds" parameter. By default the key length is set to 128
|
|
bits and 12 rounds.
|
|
|
|
=back
|
|
|
|
=head1 NOTES
|
|
|
|
Where possible the B<EVP> interface to symmetric ciphers should be used in
|
|
preference to the low level interfaces. This is because the code then becomes
|
|
transparent to the cipher used and much more flexible.
|
|
|
|
PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
|
|
length of the encrypted data a multiple of the block size. Padding is always
|
|
added so if the data is already a multiple of the block size B<n> will equal
|
|
the block size. For example if the block size is 8 and 11 bytes are to be
|
|
encrypted then 5 padding bytes of value 5 will be added.
|
|
|
|
When decrypting the final block is checked to see if it has the correct form.
|
|
|
|
Although the decryption operation can produce an error, it is not a strong
|
|
test that the input data or key is correct. A random block has better than
|
|
1 in 256 chance of being of the correct format and problems with the
|
|
input data earlier on will not produce a final decrypt error.
|
|
|
|
The functions EVP_EncryptInit(), EVP_EncryptUpdate(), EVP_EncryptFinal(),
|
|
EVP_DecryptInit(), EVP_DecryptUpdate(), EVP_CipherInit() and EVP_CipherUpdate()
|
|
and EVP_CIPHER_CTX_cleanup() did not return errors in OpenSSL version 0.9.5a or
|
|
earlier. Software only versions of encryption algorithms will never return
|
|
error codes for these functions, unless there is a programming error (for example
|
|
and attempt to set the key before the cipher is set in EVP_EncryptInit() ).
|
|
|
|
=head1 BUGS
|
|
|
|
For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is
|
|
a limitation of the current RC5 code rather than the EVP interface.
|
|
|
|
It should be possible to disable PKCS padding: currently it isn't.
|
|
|
|
EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
|
|
default key lengths. If custom ciphers exceed these values the results are
|
|
unpredictable. This is because it has become standard practice to define a
|
|
generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.
|
|
|
|
The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
|
|
for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Get the number of rounds used in RC5:
|
|
|
|
int nrounds;
|
|
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &i);
|
|
|
|
Get the RC2 effective key length:
|
|
|
|
int key_bits;
|
|
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &i);
|
|
|
|
Set the number of rounds used in RC5:
|
|
|
|
int nrounds;
|
|
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, i, NULL);
|
|
|
|
Set the number of rounds used in RC2:
|
|
|
|
int nrounds;
|
|
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, i, NULL);
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<evp(3)|evp(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
=cut
|