EVP

The EVP functions provide a high level interface to OpenSSL cryptographic functions.

They provide the following features:

• A single consistent interface regardless of the underlying algorithm or mode
• Support for an extensive range of algorithms
• Encryption/Decryption using both symmetric and asymmetric algorithms
• Sign/Verify
• Key derivation
• Secure Hash functions
• Message Authentication Codes
• Support for external crypto engines

Working with EVP_PKEYs

EVP_PKEY objects are used to store a public key and (optionally) a private key, along with an associated algorithm and parameters. They are also capable of storing symmetric MAC keys.

The following EVP_PKEY types are supported:

• EVP_PKEY_EC: Elliptic Curve keys (for ECDSA and ECDH) - Supports sign/verify operations, and Key derivation
• EVP_PKEY_RSA: RSA - Supports sign/verify and encrypt/decrypt
• EVP_PKEY_DH: Diffie Hellman - for key derivation
• EVP_PKEY_DSA: DSA keys for sign/verify
• EVP_PKEY_HMAC: An HMAC key for generating a Message Authentication Code
• EVP_PKEY_CMAC: A CMAC key for generating a Message Authentication Code

Note: DSA handling changed for SSL/TLS cipher suites in OpenSSL 1.1.0. For details, see DSA with OpenSSL-1.1 on the mailing list.

Refer to the Manual:EVP_PKEY_new(3) manual page for information on creating an EVP_PKEY object, and the Manual:EVP_PKEY_set1_RSA(3) page for information on how to initialise an EVP_PKEY.

Refer to EVP Key and Parameter Generation for information on generating new keys and associated parameters.

Working with Algorithms and Modes

Ciphers and Message Digest algorithms are identified by a unique EVP_CIPHER and EVP_MD object respectively. You are not expected to create these yourself, but instead use one of the built in functions to return one for the particular algorithm that you wish to use. Refer to the evp.h header file for the complete list of ciphers and message digests.

An extract from evp.h listing some EVP_CIPHER functions is shown below:

const EVP_CIPHER *EVP_aes_128_ctr(void);
const EVP_CIPHER *EVP_aes_128_ccm(void);
const EVP_CIPHER *EVP_aes_128_gcm(void);
const EVP_CIPHER *EVP_aes_128_xts(void);
const EVP_CIPHER *EVP_aes_192_ecb(void);
const EVP_CIPHER *EVP_aes_192_cbc(void);

These ciphers are all variants of the AES (Advanced Encryption Standard) algorithm. There are two different key lengths shown - for 128 bit keys and 192 bit keys respectively. There are also a variety of different encryption modes shown, i.e. CTR, CCM, GCM, XTS, ECB and CBC. Not all algorithms support all modes, so you should check in evp.h for the particular combination that you want.

The following (edited) extract from evp.h shows some sample message digest functions:

const EVP_MD *EVP_md2(void);
const EVP_MD *EVP_md4(void);
const EVP_MD *EVP_md5(void);
const EVP_MD *EVP_sha1(void);
const EVP_MD *EVP_sha224(void);
const EVP_MD *EVP_sha256(void);
const EVP_MD *EVP_sha384(void);
const EVP_MD *EVP_sha512(void);

The objects returned from these functions are built-in and do not need to be "freed" after use.

Cryptographic Operations

The following cryptographic operations are possible. Refer to the relevant pages for further details

• Symmetric Encryption and Decryption
• Authenticated Encryption and Decryption
• Asymmetric Encryption and Decryption of an Envelope
• Signing and Verifying (including Message Authentication Codes)
• Message Digests
• Key Agreement
• Key and Parameter Generation

See also

• Libcrypto API