--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free,
+EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags,
+EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init,
+EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup,
+EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params,
+EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init,
+EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup,
+EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params,
+EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len);
+ EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher);
+ void EVP_CIPHER_meth_free(EVP_CIPHER *cipher);
+
+ int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len);
+ int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags);
+ int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size);
+ int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher,
+ int (*init) (EVP_CIPHER_CTX *ctx,
+ const unsigned char *key,
+ const unsigned char *iv,
+ int enc));
+ int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher,
+ int (*do_cipher) (EVP_CIPHER_CTX *ctx,
+ unsigned char *out,
+ const unsigned char *in,
+ size_t inl));
+ int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher,
+ int (*cleanup) (EVP_CIPHER_CTX *));
+ int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher,
+ int (*set_asn1_parameters) (EVP_CIPHER_CTX *,
+ ASN1_TYPE *));
+ int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher,
+ int (*get_asn1_parameters) (EVP_CIPHER_CTX *,
+ ASN1_TYPE *));
+ int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher,
+ int (*ctrl) (EVP_CIPHER_CTX *, int type,
+ int arg, void *ptr));
+
+ int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
+ const unsigned char *key,
+ const unsigned char *iv,
+ int enc);
+ int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
+ unsigned char *out,
+ const unsigned char *in,
+ size_t inl);
+ int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *);
+ int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
+ ASN1_TYPE *);
+ int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
+ ASN1_TYPE *);
+ int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
+ int type, int arg,
+ void *ptr);
+
+=head1 DESCRIPTION
+
+The B<EVP_CIPHER> type is a structure for symmetric cipher method
+implementation.
+
+EVP_CIPHER_meth_new() creates a new B<EVP_CIPHER> structure.
+
+EVP_CIPHER_meth_dup() creates a copy of B<cipher>.
+
+EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure.
+
+EVP_CIPHER_meth_iv_length() sets the length of the IV.
+This is only needed when the implemented cipher mode requires it.
+
+EVP_CIPHER_meth_set_flags() sets the flags to describe optional
+behaviours in the particular B<cipher>.
+With the exception of cipher modes, of which only one may be present,
+several flags can be or'd together.
+The available flags are:
+
+=over 4
+
+=over 4
+
+=item The cipher modes:
+
+=over 4
+
+=item EVP_CIPH_STREAM_CIPHER
+
+=item EVP_CIPH_ECB_MODE
+
+=item EVP_CIPH_CBC_MODE
+
+=item EVP_CIPH_CFB_MODE
+
+=item EVP_CIPH_OFB_MODE
+
+=item EVP_CIPH_CTR_MODE
+
+=item EVP_CIPH_GCM_MODE
+
+=item EVP_CIPH_CCM_MODE
+
+=item EVP_CIPH_XTS_MODE
+
+=item EVP_CIPH_WRAP_MODE
+
+=item EVP_CIPH_OCB_MODE
+
+=back
+
+=item EVP_CIPH_VARIABLE_LENGTH
+
+This cipher is of variable length.
+
+=item EVP_CIPH_CUSTOM_IV
+
+Storing and initialising the IV is left entirely to the
+implementation.
+
+=item EVP_CIPH_ALWAYS_CALL_INIT
+
+Set this if the implementation's init() function should be called even
+if B<key> is B<NULL>.
+
+=item EVP_CIPH_CTRL_INIT
+
+Set this to have the implementation's ctrl() function called with
+command code B<EVP_CTRL_INIT> early in its setup.
+
+=item EVP_CIPH_CUSTOM_KEY_LENGTH
+
+Checking and setting the key length after creating the B<EVP_CIPHER>
+is left to the implementation.
+Whenever someone uses EVP_CIPHER_CTX_set_key_length() on a
+B<EVP_CIPHER> with this flag set, the implementation's ctrl() function
+will be called with the control code B<EVP_CTRL_SET_KEY_LENGTH> and
+the key length in B<arg>.
+
+=item EVP_CIPH_NO_PADDING
+
+Don't use standard block padding.
+
+=item EVP_CIPH_RAND_KEY
+
+Making a key with random content is left to the implementation.
+This is done by calling the implementation's ctrl() function with the
+control code B<EVP_CTRL_RAND_KEY> and the pointer to the key memory
+storage in B<ptr>.
+
+=item EVP_CIPH_CUSTOM_COPY
+
+Set this to have the implementation's ctrl() function called with
+command code B<EVP_CTRL_COPY> at the end of EVP_CIPHER_CTX_copy().
+The intended use is for further things to deal with after the
+implementation specific data block has been copied.
+The destination B<EVP_CIPHER_CTX> is passed to the control with the
+B<ptr> parameter.
+The implementation specific data block is reached with
+EVP_CIPHER_CTX_cipher_data().
+
+=item EVP_CIPH_FLAG_DEFAULT_ASN1
+
+Use the default EVP routines to pass IV to and from ASN.1.
+
+=item EVP_CIPH_FLAG_LENGTH_BITS
+
+Signals that the length of the input buffer for encryption /
+decryption is to be understood as the number of bits bits instead of
+bytes for this implementation.
+This is only useful for CFB1 ciphers.
+
+=begin comment
+The FIPS flags seem to be unused, so I'm hiding them until I get an
+explanation or they get removed. /RL
+
+=item EVP_CIPH_FLAG_FIPS
+
+=item EVP_CIPH_FLAG_NON_FIPS_ALLOW
+
+=end comment
+
+=item EVP_CIPH_FLAG_CUSTOM_CIPHER
+
+This indicates that the implementation takes care of everything,
+including padding, buffering and finalization.
+The EVP routines will simply give them control and do nothing more.
+
+=item EVP_CIPH_FLAG_AEAD_CIPHER
+
+This indicates that this is a AEAD cipher implementation.
+
+=item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK
+
+=begin comment
+
+I could use some help explaining this one!
+
+=end comment
+
+=back
+
+=back
+
+EVP_CIPHER_meth_set_init() sets the cipher init function for
+B<cipher>.
+The cipher init function is called by EVP_CipherInit(),
+EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(),
+EVP_DecryptInit(), EVP_DecryptInit_ex().
+
+EVP_CIPHER_meth_set_do_cipher() sets the cipher function for
+B<cipher>.
+The cipher function is called by EVP_CipherUpdate(),
+EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(),
+EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and
+EVP_DecryptFinal_ex().
+
+EVP_CIPHER_meth_set_cleanup() sets the function for B<cipher> to do
+extra cleanup before the method's privata data structure is cleaned
+out and freed.
+Note that the cleanup function is passed a B<EVP_CIPHER_CTX *>, the
+private data structure is then available with
+EVP_CIPHER_CTX_cipher_data().
+This cleanup function is called by EVP_CIPHER_CTX_reset() and
+EVP_CIPHER_CTX_free().
+
+EVP_CIPHER_meth_set_ctrl() sets the control function for B<cipher>.
+
+
+EVP_CIPHER_meth_get_input_blocksize(), EVP_CIPHER_meth_get_result_size(),
+EVP_CIPHER_meth_get_app_datasize(), EVP_CIPHER_meth_get_flags(),
+EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_update(),
+EVP_CIPHER_meth_get_final(), EVP_CIPHER_meth_get_copy(),
+EVP_CIPHER_meth_get_cleanup() and EVP_CIPHER_meth_get_ctrl() are all used
+to retrieve the method data given with the EVP_CIPHER_meth_set_*()
+functions above.
+
+=head1 SEE ALSO
+
+L<EVP_EncryptInit>
+
+=head1 HISTORY
+
+The B<EVP_CIPHER> structure was openly available in OpenSSL before version
+1.1.
+The functions described here were added in OpenSSL version 1.1.
+
+=cut
=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
=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.
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;
}
Support for OCB mode was added in OpenSSL 1.1.0
+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().
+
=cut
projects / oweals / openssl.git / commitdiff