1.\" $OpenBSD: evp.3,v 1.36 2024/12/06 14:27:49 schwarze Exp $ 2.\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +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: December 6 2024 $ 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. 65The abbreviation 66.Dq EVP 67is intended to mean 68.Dq EnVeloPe 69in the sense of 70.Dq wrapper library . 71It is not related to the technical meaning of the term 72.Dq envelope 73in contexts like 74.Xr CMS_encrypt 3 , 75.Xr EVP_SealInit 3 , 76.Xr PKCS7_encrypt 3 , 77or 78.Xr SMIME_write_ASN1 3 . 79.Pp 80.Xr EVP_SealInit 3 81and 82.Xr EVP_OpenInit 3 83provide public key encryption and decryption to implement digital 84"envelopes". 85.Pp 86The 87.Xr EVP_DigestSignInit 3 88and 89.Xr EVP_DigestVerifyInit 3 90functions implement digital signatures and Message Authentication Codes 91(MACs). 92Also see the older 93.Xr EVP_SignInit 3 94and 95.Xr EVP_VerifyInit 3 96functions. 97.Pp 98Symmetric encryption is available with the 99.Xr EVP_EncryptInit 3 100functions. 101The 102.Xr EVP_DigestInit 3 103functions provide message digests. 104.Pp 105Authenticated encryption with additional data (AEAD) is available with 106the 107.Xr EVP_AEAD_CTX_init 3 108functions. 109.Pp 110The 111.Fn EVP_PKEY_* 112functions provide a high-level interface to asymmetric algorithms. 113To create a new 114.Vt EVP_PKEY , 115see 116.Xr EVP_PKEY_new 3 . 117.Vt EVP_PKEY Ns s 118can be associated with a private key of a particular algorithm 119by using the functions described in the 120.Xr EVP_PKEY_set1_RSA 3 121page, or new keys can be generated using 122.Xr EVP_PKEY_keygen 3 . 123.Vt EVP_PKEY Ns s 124can be compared using 125.Xr EVP_PKEY_cmp 3 126or printed using 127.Xr EVP_PKEY_print_private 3 . 128.Pp 129The 130.Fn EVP_PKEY_* 131functions support the full range of asymmetric algorithm operations: 132.Bl -bullet 133.It 134For key agreement, see 135.Xr EVP_PKEY_derive 3 . 136.It 137For signing and verifying, see 138.Xr EVP_PKEY_sign 3 , 139.Xr EVP_PKEY_verify 3 , 140and 141.Xr EVP_PKEY_verify_recover 3 . 142However, note that these functions do not perform a digest of the 143data to be signed. 144Therefore, normally you would use the 145.Xr EVP_DigestSignInit 3 146functions for this purpose. 147.It 148For encryption and decryption see 149.Xr EVP_PKEY_encrypt 3 150and 151.Xr EVP_PKEY_decrypt 3 , 152respectively. 153However, note that these functions perform encryption and decryption only. 154As public key encryption is an expensive operation, normally you 155would wrap an encrypted message in a digital envelope using the 156.Xr EVP_SealInit 3 157and 158.Xr EVP_OpenInit 3 159functions. 160.El 161.Pp 162The 163.Xr EVP_BytesToKey 3 164function provides some limited support for password based encryption. 165Careful selection of the parameters will provide a PKCS#5 PBKDF1 166compatible implementation. 167However, new applications should typically not use this (preferring, for 168example, PBKDF2 from PCKS#5). 169.Pp 170The 171.Xr EVP_EncodeInit 3 172family of functions provides base64 encoding and decoding. 173.Sh SEE ALSO 174.Xr ASN1_item_digest 3 , 175.Xr ASN1_item_sign 3 , 176.Xr BIO_f_cipher 3 , 177.Xr BIO_f_md 3 , 178.Xr CMAC_Init 3 , 179.Xr CMS_encrypt 3 , 180.Xr CMS_sign 3 , 181.Xr crypto 3 , 182.Xr d2i_PKCS8PrivateKey_bio 3 , 183.Xr d2i_PrivateKey 3 , 184.Xr EVP_AEAD_CTX_init 3 , 185.Xr EVP_aes_128_cbc 3 , 186.Xr EVP_BytesToKey 3 , 187.Xr EVP_camellia_128_cbc 3 , 188.Xr EVP_chacha20 3 , 189.Xr EVP_CIPHER_CTX_ctrl 3 , 190.Xr EVP_CIPHER_CTX_get_cipher_data 3 , 191.Xr EVP_CIPHER_CTX_init 3 , 192.Xr EVP_CIPHER_CTX_set_flags 3 , 193.Xr EVP_CIPHER_do_all 3 , 194.Xr EVP_CIPHER_meth_new 3 , 195.Xr EVP_CIPHER_nid 3 , 196.Xr EVP_des_cbc 3 , 197.Xr EVP_DigestInit 3 , 198.Xr EVP_DigestSignInit 3 , 199.Xr EVP_DigestVerifyInit 3 , 200.Xr EVP_EncodeInit 3 , 201.Xr EVP_EncryptInit 3 , 202.Xr EVP_MD_CTX_ctrl 3 , 203.Xr EVP_MD_nid 3 , 204.Xr EVP_OpenInit 3 , 205.Xr EVP_PKCS82PKEY 3 , 206.Xr EVP_PKEY_asn1_get_count 3 , 207.Xr EVP_PKEY_cmp 3 , 208.Xr EVP_PKEY_CTX_ctrl 3 , 209.Xr EVP_PKEY_CTX_get_operation 3 , 210.Xr EVP_PKEY_CTX_new 3 , 211.Xr EVP_PKEY_CTX_set_hkdf_md 3 , 212.Xr EVP_PKEY_decrypt 3 , 213.Xr EVP_PKEY_derive 3 , 214.Xr EVP_PKEY_encrypt 3 , 215.Xr EVP_PKEY_get_default_digest_nid 3 , 216.Xr EVP_PKEY_keygen 3 , 217.Xr EVP_PKEY_new 3 , 218.Xr EVP_PKEY_print_private 3 , 219.Xr EVP_PKEY_set1_RSA 3 , 220.Xr EVP_PKEY_sign 3 , 221.Xr EVP_PKEY_size 3 , 222.Xr EVP_PKEY_verify 3 , 223.Xr EVP_PKEY_verify_recover 3 , 224.Xr EVP_rc4 3 , 225.Xr EVP_SealInit 3 , 226.Xr EVP_sha1 3 , 227.Xr EVP_sha3_224 3 , 228.Xr EVP_SignInit 3 , 229.Xr EVP_sm3 3 , 230.Xr EVP_sm4_cbc 3 , 231.Xr EVP_VerifyInit 3 , 232.Xr HMAC 3 , 233.Xr OCSP_basic_sign 3 , 234.Xr OCSP_request_sign 3 , 235.Xr PEM_get_EVP_CIPHER_INFO 3 , 236.Xr PEM_read_bio_PrivateKey 3 , 237.Xr PKCS12_create 3 , 238.Xr PKCS5_PBKDF2_HMAC 3 , 239.Xr PKCS7_encrypt 3 , 240.Xr PKCS7_sign 3 , 241.Xr RSA_pkey_ctx_ctrl 3 , 242.Xr SSL_CTX_set_tlsext_ticket_key_cb 3 , 243.Xr X509_ALGOR_set0 3 , 244.Xr X509_check_private_key 3 , 245.Xr X509_digest 3 , 246.Xr X509_get_pubkey 3 , 247.Xr X509_PUBKEY_set 3 , 248.Xr X509_sign 3 , 249.Xr X509_to_X509_REQ 3 250