NAME

EVP_CIPHER_CTX_init, EVP_CIPHER_CTX_cleanup, EVP_Cipher — obsolete EVP cipher functions

SYNOPSIS

#include <openssl/evp.h>

void
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 leaks memory. 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_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.