EVP

From OpenSSLWiki
Revision as of 23:03, 28 February 2013 by Matt (talk | contribs) (Removed link to separate MAC codes page (merged with signing/verifying))

Jump to: navigation, search

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

Refer to the EVP_PKEY_new manual page for information on creating an EVP_PKEY object, and the EVP_PKEY_set1_RSA 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