=head1 NAME
-EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate,
-EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate,
-EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate,
-EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length,
-EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit,
+EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free,
+EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex,
+EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex,
+EVP_CipherInit_ex, EVP_CipherUpdate, EVP_CipherFinal_ex,
+EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit,
EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal,
EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname,
EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid,
#include <openssl/evp.h>
- void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);
+ EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
+ int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
+ void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
ENGINE *impl, unsigned char *key, unsigned char *iv);
int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
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_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)
+ const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);
+ void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);
+ void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);
+ int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx);
+ void EVP_CIPHER_CTX_set_flags(const EVP_CIPHER_CTX *ctx, int flags);
+ void EVP_CIPHER_CTX_clear_flags(const EVP_CIPHER_CTX *ctx, int flags);
+ int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags);
+ int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx);
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);
The EVP cipher routines are a high level interface to certain
symmetric ciphers.
-EVP_CIPHER_CTX_init() initializes cipher contex B<ctx>.
+EVP_CIPHER_CTX_new() creates a cipher context.
+
+EVP_CIPHER_CTX_free() clears all information from a cipher context
+and free up any allocated memory associate with it, including B<ctx>
+itself. This function should be called after all operations using a
+cipher are complete so sensitive information does not remain in
+memory.
EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
-with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized
+with cipher B<type> from ENGINE B<impl>. B<ctx> must be created
before calling this function. B<type> is normally supplied
by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
default implementation is used. B<key> is the symmetric key to use
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
-and free up any allocated memory associate with it. It should be called
-after all operations using a cipher are complete so sensitive information
-does not remain in memory.
+EVP_CIPHER_CTX_reset() clears all information from a cipher context
+and free up any allocated memory associate with it, except the B<ctx>
+itself. This function should be called anytime B<ctx> is to be reused
+for another EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal()
+series of calls.
EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and
value is an internal value which may not have a corresponding OBJECT
IDENTIFIER.
-EVP_CIPHER_CTX_set_padding() enables or disables padding. By default
-encryption operations are padded using standard block padding and the
-padding is checked and removed when decrypting. If the B<pad> parameter
-is zero then no padding is performed, the total amount of data encrypted
-or decrypted must then be a multiple of the block size or an error will
-occur.
+EVP_CIPHER_CTX_set_padding() enables or disables padding. This
+function should be called after the context is set up for encryption
+or decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or
+EVP_CipherInit_ex(). By default encryption operations are padded using
+standard block padding and the padding is checked and removed when
+decrypting. If the B<pad> parameter is zero then no padding is
+performed, the total amount of data encrypted or decrypted must then
+be a multiple of the block size or an error will occur.
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>
=head1 RETURN VALUES
+EVP_CIPHER_CTX_new() returns a pointer to a newly created
+B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
+
EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
return 1 for success and 0 for failure.
EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
-EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
+EVP_CIPHER_CTX_reset() 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.
AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.
These ciphers require additional control operations to function correctly: see
-the L<GCM and OCB modes> section below for details.
+the L</GCM and OCB modes> section below for details.
=item EVP_aes_128_ocb(void), EVP_aes_192_ocb(void), EVP_aes_256_ocb(void)
Offest Codebook Mode (OCB) for 128, 192 and 256 bit keys respectively.
These ciphers require additional control operations to function correctly: see
-the L<GCM and OCB modes> section below for details.
+the L</GCM and OCB modes> section below for details.
=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm()
length is used. For OCB AES the default is 16 (i.e. 128 bits). This is also the
maximum tag length for OCB.
-See L<EXAMPLES> below for an example of the use of GCM mode.
+See L</EXAMPLES> below for an example of the use of GCM mode.
=head1 CCM Mode
Encrypt a string using IDEA:
int do_crypt(char *outfile)
- {
+ {
unsigned char outbuf[1024];
int outlen, tmplen;
/* Bogus key and IV: we'd normally set these from
EVP_CIPHER_CTX ctx;
FILE *out;
- EVP_CIPHER_CTX_init(&ctx);
- EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv);
+ ctx = EVP_CIPHER_CTX_new();
+ EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv);
- if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
+ if(!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext)))
{
/* Error */
return 0;
/* Buffer passed to EVP_EncryptFinal() must be after data just
* encrypted to avoid overwriting it.
*/
- if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen))
+ if(!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen))
{
/* Error */
return 0;
}
outlen += tmplen;
- EVP_CIPHER_CTX_cleanup(&ctx);
+ EVP_CIPHER_CTX_free(ctx);
/* Need binary mode for fopen because encrypted data is
* binary data. Also cannot use strlen() on it because
* it wont be null terminated and may contain embedded
/* Allow enough space in output buffer for additional block */
unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
int inlen, outlen;
- EVP_CIPHER_CTX ctx;
+ EVP_CIPHER_CTX *ctx;
/* Bogus key and IV: we'd normally set these from
* another source.
*/
unsigned char iv[] = "1234567887654321";
/* Don't set key or IV right away; we want to check lengths */
- EVP_CIPHER_CTX_init(&ctx);
+ ctx = EVP_CIPHER_CTX_new();
EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
do_encrypt);
- OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16);
- OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16);
+ OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16);
+ OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16);
/* Now we can set key and IV */
- EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
+ EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt);
for(;;)
{
inlen = fread(inbuf, 1, 1024, in);
if(inlen <= 0) break;
- if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen))
+ if(!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen))
{
/* Error */
- EVP_CIPHER_CTX_cleanup(&ctx);
+ EVP_CIPHER_CTX_free(ctx);
return 0;
}
fwrite(outbuf, 1, outlen, out);
}
- if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen))
+ if(!EVP_CipherFinal_ex(ctx, outbuf, &outlen))
{
/* Error */
- EVP_CIPHER_CTX_cleanup(&ctx);
+ EVP_CIPHER_CTX_free(ctx);
return 0;
}
fwrite(outbuf, 1, outlen, out);
- EVP_CIPHER_CTX_cleanup(&ctx);
+ EVP_CIPHER_CTX_free(ctx);
return 1;
}
=head1 HISTORY
-EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(),
-EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(),
-EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in
-OpenSSL 0.9.7.
+Support for OCB mode was added in OpenSSL 1.1.0
-IDEA appeared in OpenSSL 0.9.7 but was often disabled due to
-patent concerns; the last patents expired in 2012.
+B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0. As a result,
+EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
+disappeared. EVP_CIPHER_CTX_init() remains as an alias for
+EVP_CIPHER_CTX_reset().
-Support for OCB mode was added in OpenSSL 1.1.0
=cut
projects / openssl.git / blobdiff