NAME¶

EVP_CIPHER_CTX_set_flags, EVP_CIPHER_CTX_clear_flags, EVP_CIPHER_CTX_test_flags, EVP_CIPHER_CTX_rand_key, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data — unusual EVP cipher context configuration

SYNOPSIS¶

#include <openssl/evp.h>

void
EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags);

void
EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags);

int
EVP_CIPHER_CTX_test_flags(EVP_CIPHER_CTX *ctx, int flags);

int
EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key);

int
EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);

int
EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);

void *
EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);

void
EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);

DESCRIPTION¶

EVP_CIPHER_CTX_set_flags() enables the given flags in ctx. EVP_CIPHER_CTX_clear_flags() disables the given flags in ctx. EVP_CIPHER_CTX_test_flags() checks whether any of the given flags are currently set in ctx, returning the subset of the flags that are set, or 0 if none of them are set. Currently, the only supported cipher context flag is EVP_CIPHER_CTX_FLAG_WRAP_ALLOW; see EVP_aes_128_wrap(3) for details.

EVP_CIPHER_CTX_rand_key() generates a random key of the appropriate length based on the cipher context. The EVP_CIPHER can provide its own random key generation routine to support keys of a specific form. The key argument must point to a buffer at least as big as the value returned by EVP_CIPHER_CTX_key_length(3).

EVP_CIPHER_param_to_asn1() sets the ASN.1 AlgorithmIdentifier parameter based on the passed cipher. This will typically include any parameters and an IV. The cipher IV (if any) must be set when this call is made. This call should be made before the cipher is actually "used" (before any EVP_EncryptUpdate(3) or EVP_DecryptUpdate(3) calls, for example). This function may fail if the cipher does not have any ASN.1 support.

EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN.1 AlgorithmIdentifier parameter. The precise effect depends on the cipher. In the case of RC2, for example, it will set the IV and effective key length. This function should be called after the base cipher type is set but before the key is set. For example EVP_CipherInit(3) will be called with the IV and key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally EVP_CipherInit(3) again with all parameters except the key set to NULL. It is possible for this function to fail if the cipher does not have any ASN.1 support or the parameters cannot be set (for example the RC2 effective key length is not supported).

RETURN VALUES¶

EVP_CIPHER_CTX_rand_key() return 1 for success or 0 for failure.

EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater than zero for success and zero or a negative number for failure.

SEE ALSO¶

evp(3), EVP_CIPHER_CTX_ctrl(3), EVP_CIPHER_CTX_get_cipher_data(3), EVP_CIPHER_nid(3), EVP_EncryptInit(3)

HISTORY¶

EVP_CIPHER_CTX_set_app_data() and EVP_CIPHER_CTX_get_app_data() first appeared in SSLeay 0.8.0. EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() first appeared in SSLeay 0.9.0. These functions have been available since OpenBSD 2.4.

EVP_CIPHER_CTX_rand_key() first appeared in OpenSSL 0.9.8 and has been available since OpenBSD 4.5.

BUGS¶

The ASN.1 code is incomplete (and sometimes inaccurate). It has only been tested for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.