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
—
Routines to build up EVP_CIPHER
methods
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));
DESCRIPTION
The EVP_CIPHER type is a structure holding function pointers for a symmetric cipher implementation.
EVP_CIPHER_meth_new
()
allocates a new EVP_CIPHER structure. The cipher's NID
(see EVP_CIPHER_nid(3)) is set to cipher_type, the
block size and key length are set to block_size and
key_len, respectively.
EVP_CIPHER_meth_dup
()
creates a copy of cipher.
EVP_CIPHER_meth_free
()
frees an EVP_CIPHER structure.
EVP_CIPHER_meth_set_iv_length
()
sets the length of the initialization vector. This is only needed when the
implemented cipher mode requires it.
EVP_CIPHER_meth_set_flags
()
overwrites the flags to describe optional behaviours in
cipher with flags. At most one
of the following cipher modes can be set:
EVP_CIPH_STREAM_CIPHER
,
EVP_CIPH_ECB_MODE
,
EVP_CIPH_CBC_MODE
,
EVP_CIPH_CFB_MODE
,
EVP_CIPH_OFB_MODE
,
EVP_CIPH_CTR_MODE
,
EVP_CIPH_GCM_MODE
,
EVP_CIPH_CCM_MODE
,
EVP_CIPH_XTS_MODE
, and
EVP_CIPH_WRAP_MODE
.
Zero or more of the following flags can be OR'ed into the flags argument:
EVP_CIPH_VARIABLE_LENGTH
- This cipher has a variable key length, and the function EVP_CIPHER_CTX_set_key_length(3) can be used with it.
EVP_CIPH_CUSTOM_IV
- Instruct EVP_CipherInit_ex(3) and similar initialization functions to leave storing and initialising the IV entirely to the implementation. If this flag is set, the implementation is typically expected to do that in its init function.
EVP_CIPH_ALWAYS_CALL_INIT
- Instruct EVP_CipherInit_ex(3) and similar initialization functions to call
the implementation's init function even if the
key argument is
NULL
. EVP_CIPH_CTRL_INIT
- Instruct EVP_CipherInit_ex(3) and similar initialization functions to call
the implementation's ctrl function with a command
type of
EVP_CTRL_INIT
early during the setup. EVP_CIPH_NO_PADDING
- Instruct EVP_CipherFinal_ex(3) and similar finalization functions to not use standard block padding but instead report an error if the total amount of data to be encrypted or decrypted is not a multiple of the block size.
EVP_CIPH_RAND_KEY
- Instruct EVP_CIPHER_CTX_rand_key(3) to not generate a random key using
arc4random_buf(3)
but instead leave that to the implementation by calling the
ctrl function with a command
type of
EVP_CTRL_RAND_KEY
and the pointer to the key memory storage in ptr. EVP_CIPH_CUSTOM_COPY
- Instruct EVP_CIPHER_CTX_copy(3) to call the implementation's
ctrl function with a command
type of
EVP_CTRL_COPY
and the destination EVP_CIPHER_CTX *out in the ptr argument immediately before returning successfully. The intended use is for further things to deal with after the implementation specific data block has been copied. The implementation-specific data block is reached with EVP_CIPHER_CTX_get_cipher_data(3). EVP_CIPH_FLAG_DEFAULT_ASN1
- Instruct EVP_CIPHER_param_to_asn1(3) to use ASN1_TYPE_set_octetstring(3) if no set_asn1_parameters function is installed, and instruct EVP_CIPHER_asn1_to_param(3) to use ASN1_TYPE_get_octetstring(3) if no get_asn1_parameters function is installed.
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 instead of bytes for this implementation. This is only useful for CFB1 ciphers.
EVP_CIPH_FLAG_CUSTOM_CIPHER
- Instruct EVP_CipherUpdate(3), EVP_CipherFinal_ex(3), and similar encryption, decryption, and finalization functions that the implementation's do_cipher function takes care of everything, including padding, buffering and finalization.
EVP_CIPH_FLAG_AEAD_CIPHER
- This indicates that this is an AEAD cipher implementation.
EVP_CIPHER_meth_set_impl_ctx_size
()
sets the size of the EVP_CIPHER's implementation context so that it can be
automatically allocated.
EVP_CIPHER_meth_set_init
()
sets the init function for
cipher. The cipher init function is called by
EVP_CipherInit(3),
EVP_CipherInit_ex(3), EVP_EncryptInit(3),
EVP_EncryptInit_ex(3), EVP_DecryptInit(3), and
EVP_DecryptInit_ex(3).
EVP_CIPHER_meth_set_do_cipher
()
sets the cipher function for cipher. The cipher
function is called by EVP_CipherUpdate(3), EVP_EncryptUpdate(3),
EVP_DecryptUpdate(3), EVP_CipherFinal(3),
EVP_EncryptFinal(3), EVP_EncryptFinal_ex(3),
EVP_DecryptFinal(3) and
EVP_DecryptFinal_ex(3).
EVP_CIPHER_meth_set_cleanup
()
sets the function for cipher to do extra cleanup
before the method's private data structure is cleaned out and freed. Note
that the cleanup function is passed a
EVP_CIPHER_CTX
*, the private data structure is then available with
EVP_CIPHER_CTX_get_cipher_data(3). This cleanup function is called by
EVP_CIPHER_CTX_reset(3) and
EVP_CIPHER_CTX_free(3).
EVP_CIPHER_meth_set_set_asn1_params
()
sets the function for cipher to set the
AlgorithmIdentifier "parameter" based on the passed cipher. This
function is called by EVP_CIPHER_param_to_asn1(3).
EVP_CIPHER_meth_set_get_asn1_params
()
sets the function for cipher that sets the cipher
parameters based on an ASN.1 AlgorithmIdentifier "parameter". Both
these functions are needed when there is a need for custom data (more or
other than the cipher IV). They are called by
EVP_CIPHER_param_to_asn1(3) and
EVP_CIPHER_asn1_to_param(3) respectively if defined.
EVP_CIPHER_meth_set_ctrl
()
sets the control function for cipher.
RETURN VALUES
EVP_CIPHER_meth_new
() and
EVP_CIPHER_meth_dup
() return a pointer to a newly
created EVP_CIPHER, or NULL on failure.
All EVP_CIPHER_meth_set_*
() functions
return 1.
SEE ALSO
HISTORY
These functions first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 7.3.