Difference between revisions of "EVP"

From OpenSSLWiki
Jump to: navigation, search
(Working with EVP_PKEYs)
m (Added note on DSA changes for 1.1.0. Its probably a better fit elsewhere, but I'm not finding a good page at the moment (e.g., no DSA or DSS page).)
 
(8 intermediate revisions by 2 users not shown)
Line 23: Line 23:
 
* EVP_PKEY_CMAC: A CMAC key for generating a Message Authentication Code
 
* EVP_PKEY_CMAC: A CMAC key for generating a Message Authentication Code
  
Refer to the [http://www.openssl.org/docs/crypto/EVP_PKEY_new.html EVP_PKEY_new] manual page for information on creating an EVP_PKEY object, and the [http://www.openssl.org/docs/crypto/EVP_PKEY_set1_RSA.html EVP_PKEY_set1_RSA] page for information on how to initialise an EVP_PKEY.
+
'''''Note''''': DSA handling changed for SSL/TLS cipher suites in OpenSSL 1.1.0. For details, see [http://groups.google.com/forum/#!topic/mailing.openssl.users/1_TFpK6XzQ4 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.
 
Refer to [[EVP Key and Parameter Generation]] for information on generating new keys and associated parameters.
Line 59: Line 61:
 
The following cryptographic operations are possible. Refer to the relevant pages for further details
 
The following cryptographic operations are possible. Refer to the relevant pages for further details
 
* [[EVP Symmetric Encryption and Decryption|Symmetric Encryption and Decryption]]
 
* [[EVP Symmetric Encryption and Decryption|Symmetric Encryption and Decryption]]
* [[EVP Asymmetric Encryption and Decryption|Asymmetric Encryption and Decryption]]
+
* [[EVP Authenticated Encryption and Decryption|Authenticated Encryption and Decryption]]
* [[EVP Signing and Verifying|Signing and Verifying]]
+
* [[EVP Asymmetric Encryption and Decryption of an Envelope|Asymmetric Encryption and Decryption of an Envelope]]
 +
* [[EVP Signing and Verifying|Signing and Verifying (including Message Authentication Codes)]]
 
* [[EVP Message Digests|Message Digests]]
 
* [[EVP Message Digests|Message Digests]]
* [[EVP Message Authentication Codes|Message Authentication Codes]]
+
* [[EVP Key Agreement|Key Agreement]]
* [[EVP Key Derivation|Key Derivation]]
 
 
* [[EVP Key and Parameter Generation|Key and Parameter Generation]]
 
* [[EVP Key and Parameter Generation|Key and Parameter Generation]]
 +
 +
==See also==
 +
* [[Libcrypto API]]
 +
 +
[[Category:Crypto API]]
 +
[[Category:C level]]

Latest revision as of 10:28, 2 July 2016

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[edit]

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[edit]

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[edit]

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

See also[edit]