1.\" $OpenBSD: evp.3,v 1.15 2023/07/09 06:49:25 tb Exp $ 2.\" OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100 3.\" 4.\" This file was written by Ulf Moeller <ulf@openssl.org>, 5.\" Matt Caswell <matt@openssl.org>, Geoff Thorpe <geoff@openssl.org>, 6.\" and Dr. Stephen Henson <steve@openssl.org>. 7.\" Copyright (c) 2000, 2002, 2006, 2013, 2016 The OpenSSL Project. 8.\" All rights reserved. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in 19.\" the documentation and/or other materials provided with the 20.\" distribution. 21.\" 22.\" 3. All advertising materials mentioning features or use of this 23.\" software must display the following acknowledgment: 24.\" "This product includes software developed by the OpenSSL Project 25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 26.\" 27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 28.\" endorse or promote products derived from this software without 29.\" prior written permission. For written permission, please contact 30.\" openssl-core@openssl.org. 31.\" 32.\" 5. Products derived from this software may not be called "OpenSSL" 33.\" nor may "OpenSSL" appear in their names without prior written 34.\" permission of the OpenSSL Project. 35.\" 36.\" 6. Redistributions of any form whatsoever must retain the following 37.\" acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 52.\" OF THE POSSIBILITY OF SUCH DAMAGE. 53.\" 54.Dd $Mdocdate: July 9 2023 $ 55.Dt EVP 3 56.Os 57.Sh NAME 58.Nm evp 59.Nd high level cryptographic functions 60.Sh SYNOPSIS 61.In openssl/evp.h 62.Sh DESCRIPTION 63The EVP library provides a high level interface to cryptographic 64functions. 65.Pp 66.Xr EVP_SealInit 3 67and 68.Xr EVP_OpenInit 3 69provide public key encryption and decryption to implement digital 70"envelopes". 71.Pp 72The 73.Xr EVP_DigestSignInit 3 74and 75.Xr EVP_DigestVerifyInit 3 76functions implement digital signatures and Message Authentication Codes 77(MACs). 78Also see the older 79.Xr EVP_SignInit 3 80and 81.Xr EVP_VerifyInit 3 82functions. 83.Pp 84Symmetric encryption is available with the 85.Xr EVP_EncryptInit 3 86functions. 87The 88.Xr EVP_DigestInit 3 89functions provide message digests. 90.Pp 91Authenticated encryption with additional data (AEAD) is available with 92the 93.Xr EVP_AEAD_CTX_init 3 94functions. 95.Pp 96The 97.Fn EVP_PKEY_* 98functions provide a high level interface to asymmetric algorithms. 99To create a new 100.Vt EVP_PKEY , 101see 102.Xr EVP_PKEY_new 3 . 103.Vt EVP_PKEY Ns s 104can be associated with a private key of a particular algorithm 105by using the functions described in the 106.Xr EVP_PKEY_set1_RSA 3 107page, or new keys can be generated using 108.Xr EVP_PKEY_keygen 3 . 109.Vt EVP_PKEY Ns s 110can be compared using 111.Xr EVP_PKEY_cmp 3 112or printed using 113.Xr EVP_PKEY_print_private 3 . 114.Pp 115The 116.Fn EVP_PKEY_* 117functions support the full range of asymmetric algorithm operations: 118.Bl -bullet 119.It 120For key agreement, see 121.Xr EVP_PKEY_derive 3 . 122.It 123For signing and verifying, see 124.Xr EVP_PKEY_sign 3 , 125.Xr EVP_PKEY_verify 3 , 126and 127.Xr EVP_PKEY_verify_recover 3 . 128However, note that these functions do not perform a digest of the 129data to be signed. 130Therefore normally you would use the 131.Xr EVP_DigestSignInit 3 132functions for this purpose. 133.It 134For encryption and decryption see 135.Xr EVP_PKEY_encrypt 3 136and 137.Xr EVP_PKEY_decrypt 3 , 138respectively. 139However, note that these functions perform encryption and decryption only. 140As public key encryption is an expensive operation, normally you 141would wrap an encrypted message in a digital envelope using the 142.Xr EVP_SealInit 3 143and 144.Xr EVP_OpenInit 3 145functions. 146.El 147.Pp 148The 149.Xr EVP_BytesToKey 3 150function provides some limited support for password based encryption. 151Careful selection of the parameters will provide a PKCS#5 PBKDF1 152compatible implementation. 153However, new applications should typically not use this (preferring, for 154example, PBKDF2 from PCKS#5). 155.Pp 156The 157.Xr EVP_EncodeInit 3 158family of functions provides base64 encoding and decoding. 159.Pp 160All the symmetric algorithms (ciphers), digests and asymmetric 161algorithms (public key algorithms) can be replaced by 162.Vt ENGINE 163modules providing alternative implementations; see 164.Xr ENGINE_register_RSA 3 165and the related manual pages for more information. 166If 167.Vt ENGINE 168implementations of ciphers or digests are registered as defaults, 169then the various EVP functions will automatically use those 170implementations in preference to built in software implementations. 171.Pp 172Although low level algorithm specific functions exist for many 173algorithms, their use is discouraged. 174They cannot be used with an 175.Vt ENGINE , 176and 177.Vt ENGINE 178versions of new algorithms cannot be accessed using the low level 179functions. 180Using them also makes code harder to adapt to new algorithms, some 181options are not cleanly supported at the low level, and some 182operations are more efficient using the high level interfaces. 183.Sh SEE ALSO 184.Xr crypto 3 , 185.Xr ENGINE_register_RSA 3 , 186.Xr EVP_AEAD_CTX_init 3 , 187.Xr EVP_aes_128_cbc 3 , 188.Xr EVP_BytesToKey 3 , 189.Xr EVP_camellia_128_cbc 3 , 190.Xr EVP_des_cbc 3 , 191.Xr EVP_DigestInit 3 , 192.Xr EVP_DigestSignInit 3 , 193.Xr EVP_EncodeInit 3 , 194.Xr EVP_EncryptInit 3 , 195.Xr EVP_MD_meth_new 3 , 196.Xr EVP_OpenInit 3 , 197.Xr EVP_PKEY_decrypt 3 , 198.Xr EVP_PKEY_derive 3 , 199.Xr EVP_PKEY_encrypt 3 , 200.Xr EVP_PKEY_keygen 3 , 201.Xr EVP_PKEY_new 3 , 202.Xr EVP_PKEY_print_private 3 , 203.Xr EVP_PKEY_set1_RSA 3 , 204.Xr EVP_PKEY_sign 3 , 205.Xr EVP_PKEY_verify 3 , 206.Xr EVP_PKEY_verify_recover 3 , 207.Xr EVP_rc4 3 , 208.Xr EVP_SealInit 3 , 209.Xr EVP_SignInit 3 , 210.Xr EVP_sm3 3 , 211.Xr EVP_sm4_cbc 3 , 212.Xr EVP_VerifyInit 3 , 213.Xr EVP_whirlpool 3 214