EVP_CIPHER_METH_NEW(3) | Library Functions Manual | EVP_CIPHER_METH_NEW(3)

# 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

library “libcrypto”
`#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

evp(3), EVP_EncryptInit(3)

# HISTORY

These functions first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 7.3.

June 8, 2025 | Debian