EVP_CIPHER_CTX_INIT(3) | Library Functions Manual | EVP_CIPHER_CTX_INIT(3)

# NAME

`EVP_CIPHER_CTX_init`, `EVP_CIPHER_CTX_cleanup`, `EVP_Cipher` — obsolete EVP cipher functions

# SYNOPSIS

library “libcrypto”
`#include <openssl/evp.h>`

int
`EVP_CIPHER_CTX_init`(EVP_CIPHER_CTX *ctx);

int
`EVP_CIPHER_CTX_cleanup`(EVP_CIPHER_CTX *ctx);

int
`EVP_Cipher`(EVP_CIPHER_CTX *ctx, unsigned char *out, const unsigned char *in, unsigned int in_len);

# DESCRIPTION

`EVP_CIPHER_CTX_init`() is a deprecated function that could be used to clear a cipher context on the stack before EVP_CIPHER_CTX was made opaque. Calling it on a cipher context just returned from EVP_CIPHER_CTX_new(3) has no effect. Calling it on a cipher context that was already used may leak memory with older versions of the library. Instead, use EVP_CIPHER_CTX_reset(3) or EVP_CIPHER_CTX_free(3).

`EVP_CIPHER_CTX_cleanup`() is a deprecated alias for EVP_CIPHER_CTX_reset(3). It clears all information from ctx and frees all allocated memory associated with it, except the ctx object itself.

`EVP_Cipher`() exposes implementation details of the functions EVP_CipherUpdate(3) and EVP_CipherFinal(3) that should never have become part of the public API.

If the flag `EVP_CIPH_FLAG_CUSTOM_CIPHER` is set for the cipher used by ctx, behaviour depends on in. If that argument is `NULL` and in_len is 0, behaviour is similar to EVP_CipherFinal(3); if in_len is not 0, behaviour is undefined. If in is not `NULL`, behaviour is similar to EVP_CipherUpdate(3). In both cases, the exceptions to the similarity are that arguments and return values differ.

If the flag `EVP_CIPH_FLAG_CUSTOM_CIPHER` is not set for the cipher used by ctx, it encrypts or decrypts aligned blocks of data whose lengths match the cipher block size. It requires that the previous encryption or decryption operation using the same ctx, if there was any, ended exactly on a block boundary and that in_len is an integer multiple of the cipher block size. If either of these conditions is violated, `EVP_Cipher`() silently produces incorrect results. For that reason, using the function EVP_CipherUpdate(3) instead is strongly recommended. The latter can safely handle partial blocks, and even if in_len actually is a multiple of the cipher block size for all calls, the overhead incurred by using EVP_CipherUpdate(3) is minimal.

# RETURN VALUES

`EVP_CIPHER_CTX_init`() always returns 1.

`EVP_CIPHER_CTX_cleanup`() returns 1 for success or 0 for failure.

With `EVP_CIPH_FLAG_CUSTOM_CIPHER`, `EVP_Cipher`() returns the number of bytes written to out for success or -1 for failure. Without `EVP_CIPH_FLAG_CUSTOM_CIPHER`, it returns 1 for success or 0 for failure.

# SEE ALSO

evp(3), EVP_EncryptInit(3)

# HISTORY

`EVP_Cipher`() first appeared in SSLeay 0.6.5. `EVP_CIPHER_CTX_cleanup`() first appeared in SSLeay 0.8.0. `EVP_CIPHER_CTX_init`() first appeared in SSLeay 0.9.0. All these functions have been available since OpenBSD 2.4.

# CAVEATS

Checking the return value of `EVP_Cipher`() requires unusual caution: zero signals success if `EVP_CIPH_FLAG_CUSTOM_CIPHER` is set or failure otherwise.

June 8, 2025 | Debian