| blob | 085db2eb6e45dfbca5fe05c20fb0e532f0b23688 |
1 .\" $OpenBSD: evp.3,v 1.5 2018/04/18 01:12:11 schwarze 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: April 18 2018 $
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
63 The EVP library provides a high level interface to cryptographic
64 functions.
65 .Pp
66 .Xr EVP_SealInit 3
67 and
68 .Xr EVP_OpenInit 3
69 provide public key encryption and decryption to implement digital
70 "envelopes".
71 .Pp
72 The
73 .Xr EVP_DigestSignInit 3
74 and
75 .Xr EVP_DigestVerifyInit 3
76 functions implement digital signatures and Message Authentication Codes
77 (MACs).
78 Also see the older
79 .Xr EVP_SignInit 3
80 and
81 .Xr EVP_VerifyInit 3
82 functions.
83 .Pp
84 Symmetric encryption is available with the
85 .Xr EVP_EncryptInit 3
86 functions.
87 The
88 .Xr EVP_DigestInit 3
89 functions provide message digests.
90 .Pp
91 Authenticated encryption with additional data (AEAD) is available with
92 the
93 .Xr EVP_AEAD_CTX_init 3
94 functions.
95 .Pp
96 The
97 .Fn EVP_PKEY_*
98 functions provide a high level interface to asymmetric algorithms.
99 To create a new
100 .Vt EVP_PKEY ,
101 see
102 .Xr EVP_PKEY_new 3 .
103 .Vt EVP_PKEY Ns s
104 can be associated with a private key of a particular algorithm
105 by using the functions described in the
106 .Xr EVP_PKEY_set1_RSA 3
107 page, or new keys can be generated using
108 .Xr EVP_PKEY_keygen 3 .
109 .Vt EVP_PKEY Ns s
110 can be compared using
111 .Xr EVP_PKEY_cmp 3
112 or printed using
113 .Xr EVP_PKEY_print_private 3 .
114 .Pp
115 The
116 .Fn EVP_PKEY_*
117 functions support the full range of asymmetric algorithm operations:
118 .Bl -bullet
119 .It
120 For key agreement, see
121 .Xr EVP_PKEY_derive 3 .
122 .It
123 For signing and verifying, see
124 .Xr EVP_PKEY_sign 3 ,
125 .Xr EVP_PKEY_verify 3 ,
126 and
127 .Xr EVP_PKEY_verify_recover 3 .
128 However, note that these functions do not perform a digest of the
129 data to be signed.
130 Therefore normally you would use the
131 .Xr EVP_DigestSignInit 3
132 functions for this purpose.
133 .It
134 For encryption and decryption see
135 .Xr EVP_PKEY_encrypt 3
136 and
137 .Xr EVP_PKEY_decrypt 3 ,
138 respectively.
139 However, note that these functions perform encryption and decryption only.
140 As public key encryption is an expensive operation, normally you
141 would wrap an encrypted message in a digital envelope using the
142 .Xr EVP_SealInit 3
143 and
144 .Xr EVP_OpenInit 3
145 functions.
146 .El
147 .Pp
148 The
149 .Xr EVP_BytesToKey 3
150 function provides some limited support for password based encryption.
151 Careful selection of the parameters will provide a PKCS#5 PBKDF1
152 compatible implementation.
153 However, new applications should typically not use this (preferring, for
154 example, PBKDF2 from PCKS#5).
155 .Pp
156 Algorithms are loaded with
157 .Xr OpenSSL_add_all_algorithms 3 .
158 .Pp
159 All the symmetric algorithms (ciphers), digests and asymmetric
160 algorithms (public key algorithms) can be replaced by
161 .Vt ENGINE
162 modules providing alternative implementations; see
163 .Xr ENGINE_register_RSA 3
164 and the related manual pages for more information.
165 If
166 .Vt ENGINE
167 implementations of ciphers or digests are registered as defaults,
168 then the various EVP functions will automatically use those
169 implementations in preference to built in software implementations.
170 .Pp
171 Although low level algorithm specific functions exist for many
172 algorithms, their use is discouraged.
173 They cannot be used with an
174 .Vt ENGINE ,
175 and
176 .Vt ENGINE
177 versions of new algorithms cannot be accessed using the low level
178 functions.
179 Using them also makes code harder to adapt to new algorithms, some
180 options are not cleanly supported at the low level, and some
181 operations are more efficient using the high level interfaces.
182 .Sh SEE ALSO
183 .Xr ENGINE_register_RSA 3 ,
184 .Xr EVP_AEAD_CTX_init 3 ,
185 .Xr EVP_BytesToKey 3 ,
186 .Xr EVP_DigestInit 3 ,
187 .Xr EVP_DigestSignInit 3 ,
188 .Xr EVP_EncryptInit 3 ,
189 .Xr EVP_OpenInit 3 ,
190 .Xr EVP_PKEY_decrypt 3 ,
191 .Xr EVP_PKEY_derive 3 ,
192 .Xr EVP_PKEY_encrypt 3 ,
193 .Xr EVP_PKEY_keygen 3 ,
194 .Xr EVP_PKEY_new 3 ,
195 .Xr EVP_PKEY_print_private 3 ,
196 .Xr EVP_PKEY_set1_RSA 3 ,
197 .Xr EVP_PKEY_sign 3 ,
198 .Xr EVP_PKEY_verify 3 ,
199 .Xr EVP_PKEY_verify_recover 3 ,
200 .Xr EVP_SealInit 3 ,
201 .Xr EVP_SignInit 3 ,
202 .Xr EVP_VerifyInit 3 ,
203 .Xr OpenSSL_add_all_algorithms 3