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. The available flags are:

EVP_CIPH_VARIABLE_LENGTH

This cipher is of variable length.

EVP_CIPH_CUSTOM_IV

Storing and initialising the IV is left entirely to the implementation.

EVP_CIPH_ALWAYS_CALL_INIT

Set this if the implementation's init() function should be called even if key is NULL.

EVP_CIPH_CTRL_INIT

Set this to have the implementation's ctrl() function called with command code EVP_CTRL_INIT early in its setup.

EVP_CIPH_CUSTOM_KEY_LENGTH

Checking and setting the key length after creating the EVP_CIPHER is left to the implementation. Whenever someone uses EVP_CIPHER_CTX_set_key_length(3) on a EVP_CIPHER with this flag set, the implementation's ctrl() function will be called with the control code EVP_CTRL_SET_KEY_LENGTH and the key length in arg.

EVP_CIPH_NO_PADDING

Don't use standard block padding.

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 EVP_CTRL_RAND_KEY and the pointer to the key memory storage in ptr.

EVP_CIPH_CUSTOM_COPY

Set this to have the implementation's ctrl() function called with command code EVP_CTRL_COPY at the end of EVP_CIPHER_CTX_copy(3). The intended use is for further things to deal with after the implementation specific data block has been copied. The destination EVP_CIPHER_CTX object is passed to the control with the ptr parameter. The implementation-specific data block is reached with EVP_CIPHER_CTX_get_cipher_data(3).

EVP_CIPH_FLAG_DEFAULT_ASN1

Use the default EVP routines to pass IV to and from ASN.1.

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

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.

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 cipher 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), 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_EncryptInit(3)

HISTORY

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