NAME

EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_set_padding, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_key_length, EVP_CIPHER_key_length, EVP_CIPHER_CTX_iv_length, EVP_CIPHER_iv_length, EVP_CIPHER_CTX_set_iv, EVP_CIPHER_CTX_get_iv — configure EVP cipher contexts

SYNOPSIS

#include <openssl/evp.h>

int
EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);

int
EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);

int
EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);

int
EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);

int
EVP_CIPHER_key_length(const EVP_CIPHER *e);

int
EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);

int
EVP_CIPHER_iv_length(const EVP_CIPHER *e);

int
EVP_CIPHER_CTX_set_iv(EVP_CIPHER_CTX *ctx, const unsigned char *iv, size_t len);

int
EVP_CIPHER_CTX_get_iv(const EVP_CIPHER_CTX *ctx, unsigned char *iv, size_t len);

DESCRIPTION

EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined and set. Currently only the RC2 effective key length can be set.

EVP_CIPHER_CTX_set_padding() enables or disables padding. This function should be called after the context is set up for encryption or decryption with EVP_EncryptInit_ex(3), EVP_DecryptInit_ex(3), or EVP_CipherInit_ex(3). By default encryption operations are padded using standard block padding and the padding is checked and removed when decrypting. If the padding parameter is zero, then no padding is performed, the total amount of data encrypted or decrypted must then be a multiple of the block size or an error will occur.

EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx. If the cipher is a fixed length cipher, then attempting to set the key length to any value other than the fixed value is an error.

EVP_CIPHER_CTX_key_length() and EVP_CIPHER_key_length() return the key length of a cipher when passed an EVP_CIPHER_CTX or EVP_CIPHER structure. The constant EVP_MAX_KEY_LENGTH is the maximum key length for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a given cipher, the value of EVP_CIPHER_CTX_key_length() may be different for variable key length ciphers.

EVP_CIPHER_CTX_iv_length() and EVP_CIPHER_iv_length() return the IV length of a cipher when passed an EVP_CIPHER_CTX or EVP_CIPHER. They will return zero if the cipher does not use an IV. EVP_CIPHER_CTX_iv_length() can fail and return -1. The constant EVP_MAX_IV_LENGTH is the maximum IV length for all ciphers.

EVP_CIPHER_CTX_set_iv() and EVP_CIPHER_CTX_get_iv() set and retrieve the IV for an EVP_CIPHER_CTX, respectively. In both cases, the specified IV length must exactly equal the expected IV length for the context as returned by EVP_CIPHER_CTX_iv_length().

RETURN VALUES

EVP_CIPHER_CTX_ctrl() usually returns 1 for success, 0 for failure, or -1 if the type is not supported by the ctx, but there may be exceptions for some type arguments.

EVP_CIPHER_CTX_set_padding() always returns 1.

EVP_CIPHER_CTX_set_key_length(), EVP_CIPHER_CTX_set_iv(), and EVP_CIPHER_CTX_get_iv() return 1 for success or 0 for failure.

EVP_CIPHER_CTX_key_length() and EVP_CIPHER_key_length() return the key length.

EVP_CIPHER_CTX_iv_length() and EVP_CIPHER_iv_length() return the IV length or zero if the cipher does not use an IV. EVP_CIPHER_CTX_iv_length() can fail and return -1.

SEE ALSO

evp(3), EVP_CIPHER_nid(3), EVP_EncryptInit(3)

HISTORY

EVP_CIPHER_CTX_key_length(), EVP_CIPHER_key_length(), EVP_CIPHER_CTX_iv_length(), and EVP_CIPHER_iv_length() first appeared in SSLeay 0.6.5 and have been available since OpenBSD 2.4.

EVP_CIPHER_CTX_ctrl() and EVP_CIPHER_CTX_set_key_length() first appeared in OpenSSL 0.9.6 and have been available since OpenBSD 2.9.

EVP_CIPHER_CTX_set_padding() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.2.

EVP_CIPHER_CTX_set_iv() and EVP_CIPHER_CTX_get_iv() first appeared in LibreSSL 2.8.1 and have been available since OpenBSD 6.4.

BUGS

EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with default key lengths. If custom ciphers exceed these values, the results are unpredictable. This is because it has become standard practice to define a generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.