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

evp(3), EVP_EncryptInit(3)

HISTORY

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