]>
Commit | Line | Data |
---|---|---|
b7140b06 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | migration_guide - OpenSSL migration guide | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | See the individual manual pages for details. | |
10 | ||
11 | =head1 DESCRIPTION | |
12 | ||
13 | This guide details the changes required to migrate to new versions of OpenSSL. | |
174d166b | 14 | Currently this covers OpenSSL 3.0 & 3.1. For earlier versions refer to |
b7140b06 SL |
15 | L<https://github.com/openssl/openssl/blob/master/CHANGES.md>. |
16 | For an overview of some of the key concepts introduced in OpenSSL 3.0 see | |
17 | L<crypto(7)>. | |
18 | ||
174d166b V |
19 | =head1 OPENSSL 3.1 |
20 | ||
21 | =head2 Main Changes from OpenSSL 3.0 | |
22 | ||
23 | There are no changes requiring additional migration measures since OpenSSL 3.0. | |
24 | ||
04916913 | 25 | =head1 OPENSSL 3.0 |
b7140b06 SL |
26 | |
27 | =head2 Main Changes from OpenSSL 1.1.1 | |
28 | ||
29 | =head3 Major Release | |
30 | ||
31 | OpenSSL 3.0 is a major release and consequently any application that currently | |
32 | uses an older version of OpenSSL will at the very least need to be recompiled in | |
33 | order to work with the new version. It is the intention that the large majority | |
34 | of applications will work unchanged with OpenSSL 3.0 if those applications | |
35 | previously worked with OpenSSL 1.1.1. However this is not guaranteed and some | |
36 | changes may be required in some cases. Changes may also be required if | |
37 | applications need to take advantage of some of the new features available in | |
38 | OpenSSL 3.0 such as the availability of the FIPS module. | |
39 | ||
40 | =head3 License Change | |
41 | ||
42 | In previous versions, OpenSSL was licensed under the L<dual OpenSSL and SSLeay | |
43 | licenses|https://www.openssl.org/source/license-openssl-ssleay.txt> | |
44 | (both licenses apply). From OpenSSL 3.0 this is replaced by the | |
45 | L<Apache License v2|https://www.openssl.org/source/apache-license-2.0.txt>. | |
46 | ||
47 | =head3 Providers and FIPS support | |
48 | ||
49 | One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider | |
50 | concept. Providers collect together and make available algorithm implementations. | |
51 | With OpenSSL 3.0 it is possible to specify, either programmatically or via a | |
52 | config file, which providers you want to use for any given application. | |
53 | OpenSSL 3.0 comes with 5 different providers as standard. Over time third | |
54 | parties may distribute additional providers that can be plugged into OpenSSL. | |
55 | All algorithm implementations available via providers are accessed through the | |
04916913 | 56 | "high level" APIs (for example those functions prefixed with C<EVP>). They cannot |
b7140b06 | 57 | be accessed using the L</Low Level APIs>. |
04916913 | 58 | |
b7140b06 SL |
59 | One of the standard providers available is the FIPS provider. This makes |
60 | available FIPS validated cryptographic algorithms. | |
61 | The FIPS provider is disabled by default and needs to be enabled explicitly | |
04916913 | 62 | at configuration time using the C<enable-fips> option. If it is enabled, |
b7140b06 SL |
63 | the FIPS provider gets built and installed in addition to the other standard |
64 | providers. No separate installation procedure is necessary. | |
04916913 | 65 | There is however a dedicated C<install_fips> make target, which serves the |
b7140b06 SL |
66 | special purpose of installing only the FIPS provider into an existing |
67 | OpenSSL installation. | |
68 | ||
13757e12 DB |
69 | Not all algorithms may be available for the application at a particular moment. |
70 | If the application code uses any digest or cipher algorithm via the EVP interface, | |
71 | the application should verify the result of the L<EVP_EncryptInit(3)>, | |
72 | L<EVP_EncryptInit_ex(3)>, and L<EVP_DigestInit(3)> functions. In case when | |
73 | the requested algorithm is not available, these functions will fail. | |
74 | ||
b7140b06 SL |
75 | See also L</Legacy Algorithms> for information on the legacy provider. |
76 | ||
77 | See also L</Completing the installation of the FIPS Module> and | |
78 | L</Using the FIPS Module in applications>. | |
79 | ||
80 | =head3 Low Level APIs | |
81 | ||
82 | OpenSSL has historically provided two sets of APIs for invoking cryptographic | |
04916913 | 83 | algorithms: the "high level" APIs (such as the C<EVP> APIs) and the "low level" |
b7140b06 SL |
84 | APIs. The high level APIs are typically designed to work across all algorithm |
85 | types. The "low level" APIs are targeted at a specific algorithm implementation. | |
86 | For example, the EVP APIs provide the functions L<EVP_EncryptInit_ex(3)>, | |
87 | L<EVP_EncryptUpdate(3)> and L<EVP_EncryptFinal(3)> to perform symmetric | |
88 | encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc. | |
89 | On the other hand, to do AES encryption using the low level APIs you would have | |
90 | to call AES specific functions such as L<AES_set_encrypt_key(3)>, | |
91 | L<AES_encrypt(3)>, and so on. The functions for 3DES are different. | |
92 | Use of the low level APIs has been informally discouraged by the OpenSSL | |
93 | development team for a long time. However in OpenSSL 3.0 this is made more | |
94 | formal. All such low level APIs have been deprecated. You may still use them in | |
95 | your applications, but you may start to see deprecation warnings during | |
96 | compilation (dependent on compiler support for this). Deprecated APIs may be | |
97 | removed from future versions of OpenSSL so you are strongly encouraged to update | |
98 | your code to use the high level APIs instead. | |
99 | ||
100 | This is described in more detail in L</Deprecation of Low Level Functions> | |
101 | ||
102 | =head3 Legacy Algorithms | |
103 | ||
104 | Some cryptographic algorithms such as B<MD2> and B<DES> that were available via | |
105 | the EVP APIs are now considered legacy and their use is strongly discouraged. | |
106 | These legacy EVP algorithms are still available in OpenSSL 3.0 but not by | |
107 | default. If you want to use them then you must load the legacy provider. | |
108 | This can be as simple as a config file change, or can be done programmatically. | |
109 | See L<OSSL_PROVIDER-legacy(7)> for a complete list of algorithms. | |
110 | Applications using the EVP APIs to access these algorithms should instead use | |
111 | more modern algorithms. If that is not possible then these applications | |
112 | should ensure that the legacy provider has been loaded. This can be achieved | |
113 | either programmatically or via configuration. See L<crypto(7)> man page for | |
114 | more information about providers. | |
115 | ||
116 | =head3 Engines and "METHOD" APIs | |
117 | ||
118 | The refactoring to support Providers conflicts internally with the APIs used to | |
119 | support engines, including the ENGINE API and any function that creates or | |
120 | modifies custom "METHODS" (for example L<EVP_MD_meth_new(3)>, | |
121 | L<EVP_CIPHER_meth_new(3)>, L<EVP_PKEY_meth_new(3)>, L<RSA_meth_new(3)>, | |
122 | L<EC_KEY_METHOD_new(3)>, etc.). These functions are being deprecated in | |
123 | OpenSSL 3.0, and users of these APIs should know that their use can likely | |
124 | bypass provider selection and configuration, with unintended consequences. | |
125 | This is particularly relevant for applications written to use the OpenSSL 3.0 | |
126 | FIPS module, as detailed below. Authors and maintainers of external engines are | |
127 | strongly encouraged to refactor their code transforming engines into providers | |
57cd10dd | 128 | using the new Provider API and avoiding deprecated methods. |
b7140b06 | 129 | |
29a27cb2 DB |
130 | =head3 Support of legacy engines |
131 | ||
132 | If openssl is not built without engine support or deprecated API support, engines | |
133 | will still work. However, their applicability will be limited. | |
134 | ||
135 | New algorithms provided via engines will still work. | |
136 | ||
137 | Engine-backed keys can be loaded via custom B<OSSL_STORE> implementation. | |
138 | In this case the B<EVP_PKEY> objects created via L<ENGINE_load_private_key(3)> | |
e304aa87 | 139 | will be considered legacy and will continue to work. |
29a27cb2 DB |
140 | |
141 | To ensure the future compatibility, the engines should be turned to providers. | |
142 | To prefer the provider-based hardware offload, you can specify the default | |
143 | properties to prefer your provider. | |
144 | ||
b7140b06 SL |
145 | =head3 Versioning Scheme |
146 | ||
147 | The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new | |
148 | versioning scheme has this format: | |
149 | ||
150 | MAJOR.MINOR.PATCH | |
151 | ||
152 | For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter | |
153 | at the end of the release version number. This will no longer be used and | |
154 | instead the patch level is indicated by the final number in the version. A | |
155 | change in the second (MINOR) number indicates that new features may have been | |
156 | added. OpenSSL versions with the same major number are API and ABI compatible. | |
57cd10dd | 157 | If the major number changes then API and ABI compatibility is not guaranteed. |
b7140b06 | 158 | |
04916913 RL |
159 | For more information, see L<OpenSSL_version(3)>. |
160 | ||
b7140b06 SL |
161 | =head3 Other major new features |
162 | ||
163 | =head4 Certificate Management Protocol (CMP, RFC 4210) | |
164 | ||
165 | This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712) | |
166 | See L<openssl-cmp(1)> and L<OSSL_CMP_exec_certreq(3)> as starting points. | |
167 | ||
168 | =head4 HTTP(S) client | |
169 | ||
170 | A proper HTTP(S) client that supports GET and POST, redirection, plain and | |
171 | ASN.1-encoded contents, proxies, and timeouts. | |
172 | ||
173 | =head4 Key Derivation Function API (EVP_KDF) | |
174 | ||
175 | This simplifies the process of adding new KDF and PRF implementations. | |
176 | ||
177 | Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object | |
178 | which was not a logical mapping. | |
179 | Existing applications that use KDF algorithms using EVP_PKEY | |
180 | (scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge | |
181 | internally. | |
182 | All new applications should use the new L<EVP_KDF(3)> interface. | |
183 | See also L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> and | |
184 | L<OSSL_PROVIDER-FIPS(7)/Key Derivation Function (KDF)>. | |
185 | ||
186 | =head4 Message Authentication Code API (EVP_MAC) | |
187 | ||
188 | This simplifies the process of adding MAC implementations. | |
189 | ||
190 | This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued | |
191 | use of MACs through raw private keys in functionality such as | |
192 | L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>. | |
193 | ||
194 | All new applications should use the new L<EVP_MAC(3)> interface. | |
195 | See also L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)> | |
196 | and L<OSSL_PROVIDER-FIPS(7)/Message Authentication Code (MAC)>. | |
197 | ||
198 | =head4 Support for Linux Kernel TLS | |
199 | ||
04916913 RL |
200 | In order to use KTLS, support for it must be compiled in using the |
201 | C<enable-ktls> configuration option. It must also be enabled at run time using | |
202 | the B<SSL_OP_ENABLE_KTLS> option. | |
b7140b06 SL |
203 | |
204 | =head4 New Algorithms | |
205 | ||
206 | =over 4 | |
207 | ||
2fc02378 | 208 | =item * |
04916913 RL |
209 | |
210 | KDF algorithms "SINGLE STEP" and "SSH" | |
b7140b06 SL |
211 | |
212 | See L<EVP_KDF-SS(7)> and L<EVP_KDF-SSHKDF(7)> | |
213 | ||
2fc02378 | 214 | =item * |
04916913 RL |
215 | |
216 | MAC Algorithms "GMAC" and "KMAC" | |
b7140b06 SL |
217 | |
218 | See L<EVP_MAC-GMAC(7)> and L<EVP_MAC-KMAC(7)>. | |
219 | ||
2fc02378 | 220 | =item * |
04916913 RL |
221 | |
222 | KEM Algorithm "RSASVE" | |
b7140b06 SL |
223 | |
224 | See L<EVP_KEM-RSA(7)>. | |
225 | ||
2fc02378 | 226 | =item * |
04916913 RL |
227 | |
228 | Cipher Algorithm "AES-SIV" | |
b7140b06 SL |
229 | |
230 | See L<EVP_EncryptInit(3)/SIV Mode>. | |
231 | ||
2fc02378 | 232 | =item * |
04916913 RL |
233 | |
234 | AES Key Wrap inverse ciphers supported by EVP layer. | |
b7140b06 SL |
235 | |
236 | The inverse ciphers use AES decryption for wrapping, and AES encryption for | |
237 | unwrapping. The algorithms are: "AES-128-WRAP-INV", "AES-192-WRAP-INV", | |
238 | "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV", "AES-192-WRAP-PAD-INV" and | |
239 | "AES-256-WRAP-PAD-INV". | |
240 | ||
2fc02378 BB |
241 | =item * |
242 | ||
7f5a9399 | 243 | CTS ciphers added to EVP layer. |
b7140b06 | 244 | |
7f5a9399 SL |
245 | The algorithms are "AES-128-CBC-CTS", "AES-192-CBC-CTS", "AES-256-CBC-CTS", |
246 | "CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS" and "CAMELLIA-256-CBC-CTS". | |
b7140b06 SL |
247 | CS1, CS2 and CS3 variants are supported. |
248 | ||
249 | =back | |
250 | ||
251 | =head4 CMS and PKCS#7 updates | |
252 | ||
253 | =over 4 | |
254 | ||
2fc02378 | 255 | =item * |
04916913 RL |
256 | |
257 | Added CAdES-BES signature verification support. | |
b7140b06 | 258 | |
2fc02378 | 259 | =item * |
b7140b06 | 260 | |
04916913 RL |
261 | Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API. |
262 | ||
2fc02378 | 263 | =item * |
04916913 RL |
264 | |
265 | Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM | |
b7140b06 SL |
266 | |
267 | This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax. | |
268 | Its purpose is to support encryption and decryption of a digital envelope that | |
269 | is both authenticated and encrypted using AES GCM mode. | |
270 | ||
2fc02378 | 271 | =item * |
04916913 RL |
272 | |
273 | L<PKCS7_get_octet_string(3)> and L<PKCS7_type_is_other(3)> were made public. | |
b7140b06 SL |
274 | |
275 | =back | |
276 | ||
277 | =head4 PKCS#12 API updates | |
278 | ||
279 | The default algorithms for pkcs12 creation with the PKCS12_create() function | |
280 | were changed to more modern PBKDF2 and AES based algorithms. The default | |
281 | MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal | |
282 | with the password-based encryption iteration count. The default digest | |
283 | algorithm for the MAC computation was changed to SHA-256. The pkcs12 | |
284 | application now supports -legacy option that restores the previous | |
285 | default algorithms to support interoperability with legacy systems. | |
286 | ||
04916913 | 287 | Added enhanced PKCS#12 APIs which accept a library context B<OSSL_LIB_CTX> |
b7140b06 SL |
288 | and (where relevant) a property query. Other APIs which handle PKCS#7 and |
289 | PKCS#8 objects have also been enhanced where required. This includes: | |
290 | ||
291 | L<PKCS12_add_key_ex(3)>, L<PKCS12_add_safe_ex(3)>, L<PKCS12_add_safes_ex(3)>, | |
292 | L<PKCS12_create_ex(3)>, L<PKCS12_decrypt_skey_ex(3)>, L<PKCS12_init_ex(3)>, | |
293 | L<PKCS12_item_decrypt_d2i_ex(3)>, L<PKCS12_item_i2d_encrypt_ex(3)>, | |
294 | L<PKCS12_key_gen_asc_ex(3)>, L<PKCS12_key_gen_uni_ex(3)>, L<PKCS12_key_gen_utf8_ex(3)>, | |
295 | L<PKCS12_pack_p7encdata_ex(3)>, L<PKCS12_pbe_crypt_ex(3)>, L<PKCS12_PBE_keyivgen_ex(3)>, | |
296 | L<PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3)>, L<PKCS5_pbe2_set_iv_ex(3)>, | |
297 | L<PKCS5_pbe_set0_algor_ex(3)>, L<PKCS5_pbe_set_ex(3)>, L<PKCS5_pbkdf2_set_ex(3)>, | |
298 | L<PKCS5_v2_PBE_keyivgen_ex(3)>, L<PKCS5_v2_scrypt_keyivgen_ex(3)>, | |
299 | L<PKCS8_decrypt_ex(3)>, L<PKCS8_encrypt_ex(3)>, L<PKCS8_set0_pbe_ex(3)>. | |
300 | ||
301 | As part of this change the EVP_PBE_xxx APIs can also accept a library | |
302 | context and property query and will call an extended version of the key/IV | |
303 | derivation function which supports these parameters. This includes | |
304 | L<EVP_PBE_CipherInit_ex(3)>, L<EVP_PBE_find_ex(3)> and L<EVP_PBE_scrypt_ex(3)>. | |
305 | ||
306 | =head4 Windows thread synchronization changes | |
307 | ||
308 | Windows thread synchronization uses read/write primitives (SRWLock) when | |
309 | supported by the OS, otherwise CriticalSection continues to be used. | |
310 | ||
311 | =head4 Trace API | |
312 | ||
313 | A new generic trace API has been added which provides support for enabling | |
314 | instrumentation through trace output. This feature is mainly intended as an aid | |
315 | for developers and is disabled by default. To utilize it, OpenSSL needs to be | |
04916913 | 316 | configured with the C<enable-trace> option. |
b7140b06 SL |
317 | |
318 | If the tracing API is enabled, the application can activate trace output by | |
319 | registering BIOs as trace channels for a number of tracing and debugging | |
320 | categories. See L<OSSL_trace_enabled(3)>. | |
321 | ||
322 | =head4 Key validation updates | |
323 | ||
324 | L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_param_check(3)> now work for | |
325 | more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448. | |
326 | Previously (in 1.1.1) they would return -2. For key types that do not have | |
327 | parameters then L<EVP_PKEY_param_check(3)> will always return 1. | |
328 | ||
329 | =head3 Other notable deprecations and changes | |
330 | ||
331 | =head4 The function code part of an OpenSSL error code is no longer relevant | |
332 | ||
333 | This code is now always set to zero. Related functions are deprecated. | |
334 | ||
04916913 | 335 | =head4 STACK and HASH macros have been cleaned up |
b7140b06 SL |
336 | |
337 | The type-safe wrappers are declared everywhere and implemented once. | |
5317b6ee | 338 | See L<DEFINE_STACK_OF(3)> and L<DEFINE_LHASH_OF_EX(3)>. |
b7140b06 SL |
339 | |
340 | =head4 The RAND_DRBG subsystem has been removed | |
341 | ||
342 | The new L<EVP_RAND(3)> is a partial replacement: the DRBG callback framework is | |
343 | absent. The RAND_DRBG API did not fit well into the new provider concept as | |
344 | implemented by EVP_RAND and EVP_RAND_CTX. | |
345 | ||
346 | =head4 Removed FIPS_mode() and FIPS_mode_set() | |
347 | ||
348 | These functions are legacy APIs that are not applicable to the new provider | |
349 | model. Applications should instead use | |
350 | L<EVP_default_properties_is_fips_enabled(3)> and | |
351 | L<EVP_default_properties_enable_fips(3)>. | |
352 | ||
353 | =head4 Key generation is slower | |
354 | ||
355 | The Miller-Rabin test now uses 64 rounds, which is used for all prime generation, | |
356 | including RSA key generation. This affects the time for larger keys sizes. | |
357 | ||
358 | The default key generation method for the regular 2-prime RSA keys was changed | |
0b3d2594 | 359 | to the FIPS186-4 B.3.6 method (Generation of Probable Primes with Conditions |
b7140b06 SL |
360 | Based on Auxiliary Probable Primes). This method is slower than the original |
361 | method. | |
362 | ||
363 | =head4 Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898 | |
364 | ||
365 | This checks that the salt length is at least 128 bits, the derived key length is | |
366 | at least 112 bits, and that the iteration count is at least 1000. | |
367 | For backwards compatibility these checks are disabled by default in the | |
0b3d2594 | 368 | default provider, but are enabled by default in the FIPS provider. |
b7140b06 SL |
369 | |
370 | To enable or disable the checks see B<OSSL_KDF_PARAM_PKCS5> in | |
371 | L<EVP_KDF-PBKDF2(7)>. The parameter can be set using L<EVP_KDF_derive(3)>. | |
372 | ||
373 | =head4 Enforce a minimum DH modulus size of 512 bits | |
374 | ||
375 | Smaller sizes now result in an error. | |
376 | ||
377 | =head4 SM2 key changes | |
378 | ||
379 | EC EVP_PKEYs with the SM2 curve have been reworked to automatically become | |
380 | EVP_PKEY_SM2 rather than EVP_PKEY_EC. | |
381 | ||
382 | Unlike in previous OpenSSL versions, this means that applications cannot | |
04916913 | 383 | call C<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations. |
b7140b06 SL |
384 | |
385 | Parameter and key generation is also reworked to make it possible | |
386 | to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate | |
77072e27 TM |
387 | SM2 keys directly and must not create an EVP_PKEY_EC key first. It is no longer |
388 | possible to import an SM2 key with domain parameters other than the SM2 elliptic | |
389 | curve ones. | |
b7140b06 SL |
390 | |
391 | Validation of SM2 keys has been separated from the validation of regular EC | |
392 | keys, allowing to improve the SM2 validation process to reject loaded private | |
393 | keys that are not conforming to the SM2 ISO standard. | |
da496bc1 BB |
394 | In particular, a private scalar I<k> outside the range I<< 1 <= k < n-1 >> is |
395 | now correctly rejected. | |
b7140b06 SL |
396 | |
397 | =head4 EVP_PKEY_set_alias_type() method has been removed | |
398 | ||
399 | This function made a B<EVP_PKEY> object mutable after it had been set up. In | |
400 | OpenSSL 3.0 it was decided that a provided key should not be able to change its | |
401 | type, so this function has been removed. | |
402 | ||
403 | =head4 Functions that return an internal key should be treated as read only | |
404 | ||
405 | Functions such as L<EVP_PKEY_get0_RSA(3)> behave slightly differently in | |
406 | OpenSSL 3.0. Previously they returned a pointer to the low-level key used | |
407 | internally by libcrypto. From OpenSSL 3.0 this key may now be held in a | |
408 | provider. Calling these functions will only return a handle on the internal key | |
409 | where the EVP_PKEY was constructed using this key in the first place, for | |
410 | example using a function or macro such as L<EVP_PKEY_assign_RSA(3)>, | |
411 | L<EVP_PKEY_set1_RSA(3)>, etc. | |
412 | Where the EVP_PKEY holds a provider managed key, then these functions now return | |
413 | a cached copy of the key. Changes to the internal provider key that take place | |
414 | after the first time the cached key is accessed will not be reflected back in | |
415 | the cached copy. Similarly any changes made to the cached copy by application | |
416 | code will not be reflected back in the internal provider key. | |
417 | ||
418 | For the above reasons the keys returned from these functions should typically be | |
419 | treated as read-only. To emphasise this the value returned from | |
420 | L<EVP_PKEY_get0_RSA(3)>, L<EVP_PKEY_get0_DSA(3)>, L<EVP_PKEY_get0_EC_KEY(3)> and | |
421 | L<EVP_PKEY_get0_DH(3)> have been made const. This may break some existing code. | |
422 | Applications broken by this change should be modified. The preferred solution is | |
423 | to refactor the code to avoid the use of these deprecated functions. Failing | |
424 | this the code should be modified to use a const pointer instead. | |
425 | The L<EVP_PKEY_get1_RSA(3)>, L<EVP_PKEY_get1_DSA(3)>, L<EVP_PKEY_get1_EC_KEY(3)> | |
426 | and L<EVP_PKEY_get1_DH(3)> functions continue to return a non-const pointer to | |
427 | enable them to be "freed". However they should also be treated as read-only. | |
428 | ||
429 | =head4 The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer() | |
430 | ||
431 | This may mean result in an error in L<EVP_PKEY_derive_set_peer(3)> rather than | |
432 | during L<EVP_PKEY_derive(3)>. | |
57cd10dd | 433 | To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0). |
b7140b06 SL |
434 | |
435 | =head4 The print format has cosmetic changes for some functions | |
436 | ||
437 | The output from numerous "printing" functions such as L<X509_signature_print(3)>, | |
438 | L<X509_print_ex(3)>, L<X509_CRL_print_ex(3)>, and other similar functions has been | |
439 | amended such that there may be cosmetic differences between the output | |
04916913 RL |
440 | observed in 1.1.1 and 3.0. This also applies to the B<-text> output from the |
441 | B<openssl x509> and B<openssl crl> applications. | |
b7140b06 | 442 | |
04916913 | 443 | =head4 Interactive mode from the B<openssl> program has been removed |
b7140b06 | 444 | |
04916913 | 445 | From now on, running it without arguments is equivalent to B<openssl help>. |
b7140b06 SL |
446 | |
447 | =head4 The error return values from some control calls (ctrl) have changed | |
448 | ||
449 | One significant change is that controls which used to return -2 for | |
450 | invalid inputs, now return -1 indicating a generic error condition instead. | |
451 | ||
452 | =head4 DH and DHX key types have different settable parameters | |
453 | ||
454 | Previously (in 1.1.1) these conflicting parameters were allowed, but will now | |
455 | result in errors. See L<EVP_PKEY-DH(7)> for further details. This affects the | |
456 | behaviour of L<openssl-genpkey(1)> for DH parameter generation. | |
457 | ||
9ff4b7b0 SL |
458 | =head4 EVP_CIPHER_CTX_set_flags() ordering change |
459 | ||
460 | If using a cipher from a provider the B<EVP_CIPH_FLAG_LENGTH_BITS> flag can only | |
461 | be set B<after> the cipher has been assigned to the cipher context. | |
462 | See L<EVP_EncryptInit(3)/FLAGS> for more information. | |
463 | ||
6f242d22 TM |
464 | =head4 Validation of operation context parameters |
465 | ||
466 | Due to move of the implementation of cryptographic operations to the | |
467 | providers, validation of various operation parameters can be postponed until | |
468 | the actual operation is executed where previously it happened immediately | |
469 | when an operation parameter was set. | |
470 | ||
471 | For example when setting an unsupported curve with | |
472 | EVP_PKEY_CTX_set_ec_paramgen_curve_nid() this function call will not fail | |
473 | but later keygen operations with the EVP_PKEY_CTX will fail. | |
474 | ||
b387274d TM |
475 | =head4 Removal of function code from the error codes |
476 | ||
477 | The function code part of the error code is now always set to 0. For that | |
478 | reason the ERR_GET_FUNC() macro was removed. Applications must resolve | |
479 | the error codes only using the library number and the reason code. | |
6f242d22 | 480 | |
b7140b06 SL |
481 | =head2 Installation and Compilation |
482 | ||
483 | Please refer to the INSTALL.md file in the top of the distribution for | |
484 | instructions on how to build and install OpenSSL 3.0. Please also refer to the | |
485 | various platform specific NOTES files for your specific platform. | |
486 | ||
487 | =head2 Upgrading from OpenSSL 1.1.1 | |
488 | ||
489 | Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight | |
490 | forward in most cases. The most likely area where you will encounter problems | |
491 | is if you have used low level APIs in your code (as discussed above). In that | |
492 | case you are likely to start seeing deprecation warnings when compiling your | |
493 | application. If this happens you have 3 options: | |
494 | ||
495 | =over 4 | |
496 | ||
2fc02378 | 497 | =item 1. |
04916913 RL |
498 | |
499 | Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL. | |
b7140b06 | 500 | |
2fc02378 | 501 | =item 2. |
b7140b06 | 502 | |
04916913 RL |
503 | Suppress the warnings. Refer to your compiler documentation on how to do this. |
504 | ||
2fc02378 | 505 | =item 3. |
04916913 RL |
506 | |
507 | Remove your usage of the low level APIs. In this case you will need to rewrite your code to use the high level APIs instead | |
b7140b06 SL |
508 | |
509 | =back | |
510 | ||
6da0f274 DB |
511 | =head3 Error code changes |
512 | ||
513 | As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with | |
514 | widely used file formats, application code that checks for particular error | |
515 | reason codes on key loading failures might need an update. | |
516 | ||
517 | Password-protected keys may deserve special attention. If only some errors | |
518 | are treated as an indicator that the user should be asked about the password again, | |
519 | it's worth testing these scenarios and processing the newly relevant codes. | |
520 | ||
521 | There may be more cases to treat specially, depending on the calling application code. | |
522 | ||
b7140b06 SL |
523 | =head2 Upgrading from OpenSSL 1.0.2 |
524 | ||
525 | Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more | |
526 | difficult. In addition to the issues discussed above in the section about | |
527 | L</Upgrading from OpenSSL 1.1.1>, the main things to be aware of are: | |
528 | ||
529 | =over 4 | |
530 | ||
2fc02378 | 531 | =item 1. |
04916913 RL |
532 | |
533 | The build and installation procedure has changed significantly. | |
b7140b06 SL |
534 | |
535 | Check the file INSTALL.md in the top of the installation for instructions on how | |
536 | to build and install OpenSSL for your platform. Also read the various NOTES | |
537 | files in the same directory, as applicable for your platform. | |
538 | ||
2fc02378 | 539 | =item 2. |
04916913 RL |
540 | |
541 | Many structures have been made opaque in OpenSSL 3.0. | |
b7140b06 SL |
542 | |
543 | The structure definitions have been removed from the public header files and | |
544 | moved to internal header files. In practice this means that you can no longer | |
545 | stack allocate some structures. Instead they must be heap allocated through some | |
04916913 | 546 | function call (typically those function names have a C<_new> suffix to them). |
b7140b06 SL |
547 | Additionally you must use "setter" or "getter" functions to access the fields |
548 | within those structures. | |
549 | ||
550 | For example code that previously looked like this: | |
551 | ||
552 | EVP_MD_CTX md_ctx; | |
553 | ||
554 | /* This line will now generate compiler errors */ | |
555 | EVP_MD_CTX_init(&md_ctx); | |
556 | ||
2fc02378 BB |
557 | The code needs to be amended to look like this: |
558 | ||
b7140b06 SL |
559 | EVP_MD_CTX *md_ctx; |
560 | ||
561 | md_ctx = EVP_MD_CTX_new(); | |
562 | ... | |
563 | ... | |
564 | EVP_MD_CTX_free(md_ctx); | |
565 | ||
2fc02378 | 566 | =item 3. |
04916913 RL |
567 | |
568 | Support for TLSv1.3 has been added. | |
b7140b06 | 569 | |
57cd10dd | 570 | This has a number of implications for SSL/TLS applications. See the |
b7140b06 SL |
571 | L<TLS1.3 page|https://wiki.openssl.org/index.php/TLS1.3> for further details. |
572 | ||
573 | =back | |
574 | ||
575 | More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0 | |
576 | can be found on the | |
57cd10dd | 577 | L<OpenSSL 1.1.0 Changes page|https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>. |
b7140b06 SL |
578 | |
579 | =head3 Upgrading from the OpenSSL 2.0 FIPS Object Module | |
580 | ||
581 | The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built | |
582 | separately and then integrated into your main OpenSSL 1.0.2 build. | |
583 | In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of | |
584 | OpenSSL and is no longer a separate download. For further information see | |
585 | L</Completing the installation of the FIPS Module>. | |
586 | ||
04916913 | 587 | The function calls FIPS_mode() and FIPS_mode_set() have been removed |
b7140b06 SL |
588 | from OpenSSL 3.0. You should rewrite your application to not use them. |
589 | See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details. | |
590 | ||
591 | =head2 Completing the installation of the FIPS Module | |
592 | ||
593 | The FIPS Module will be built and installed automatically if FIPS support has | |
594 | been configured. The current documentation can be found in the | |
595 | L<README-FIPS|https://github.com/openssl/openssl/blob/master/README-FIPS.md> file. | |
596 | ||
597 | =head2 Programming | |
598 | ||
599 | Applications written to work with OpenSSL 1.1.1 will mostly just work with | |
600 | OpenSSL 3.0. However changes will be required if you want to take advantage of | |
601 | some of the new features that OpenSSL 3.0 makes available. In order to do that | |
602 | you need to understand some new concepts introduced in OpenSSL 3.0. | |
603 | Read L<crypto(7)/Library contexts> for further information. | |
604 | ||
605 | =head3 Library Context | |
606 | ||
607 | A library context allows different components of a complex application to each | |
608 | use a different library context and have different providers loaded with | |
609 | different configuration settings. | |
610 | See L<crypto(7)/Library contexts> for further info. | |
611 | ||
612 | If the user creates an B<OSSL_LIB_CTX> via L<OSSL_LIB_CTX_new(3)> then many | |
613 | functions may need to be changed to pass additional parameters to handle the | |
614 | library context. | |
615 | ||
616 | =head4 Using a Library Context - Old functions that should be changed | |
617 | ||
618 | If a library context is needed then all EVP_* digest functions that return a | |
619 | B<const EVP_MD *> such as EVP_sha256() should be replaced with a call to | |
620 | L<EVP_MD_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>. | |
621 | ||
622 | If a library context is needed then all EVP_* cipher functions that return a | |
623 | B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call to | |
624 | L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>. | |
625 | ||
626 | Some functions can be passed an object that has already been set up with a library | |
3d9d1ce5 MC |
627 | context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)>, L<d2i_X509_REQ(3)> and |
628 | L<d2i_X509_PUBKEY(3)>. If NULL is passed instead then the created object will be | |
629 | set up with the default library context. Use L<X509_new_ex(3)>, | |
630 | L<X509_CRL_new_ex(3)>, L<X509_REQ_new_ex(3)> and L<X509_PUBKEY_new_ex(3)> if a | |
631 | library context is required. | |
b7140b06 | 632 | |
e304aa87 | 633 | All functions listed below with a I<NAME> have a replacement function I<NAME_ex> |
b7140b06 SL |
634 | that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other |
635 | mappings are listed along with the respective name. | |
636 | ||
637 | =over 4 | |
638 | ||
2fc02378 | 639 | =item * |
04916913 | 640 | |
3d9d1ce5 MC |
641 | L<ASN1_item_new(3)>, L<ASN1_item_d2i(3)>, L<ASN1_item_d2i_fp(3)>, |
642 | L<ASN1_item_d2i_bio(3)>, L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)> | |
04916913 | 643 | |
2fc02378 | 644 | =item * |
b7140b06 | 645 | |
1941684d SL |
646 | L<BIO_new(3)> |
647 | ||
2fc02378 | 648 | =item * |
1941684d SL |
649 | |
650 | b2i_RSA_PVK_bio() and i2b_PVK_bio() | |
651 | ||
2fc02378 | 652 | =item * |
1941684d | 653 | |
04916913 | 654 | L<BN_CTX_new(3)> and L<BN_CTX_secure_new(3)> |
b7140b06 | 655 | |
2fc02378 | 656 | =item * |
04916913 RL |
657 | |
658 | L<CMS_AuthEnvelopedData_create(3)>, L<CMS_ContentInfo_new(3)>, L<CMS_data_create(3)>, | |
b7140b06 SL |
659 | L<CMS_digest_create(3)>, L<CMS_EncryptedData_encrypt(3)>, L<CMS_encrypt(3)>, |
660 | L<CMS_EnvelopedData_create(3)>, L<CMS_ReceiptRequest_create0(3)> and L<CMS_sign(3)> | |
661 | ||
2fc02378 | 662 | =item * |
04916913 RL |
663 | |
664 | L<CONF_modules_load_file(3)> | |
665 | ||
2fc02378 | 666 | =item * |
04916913 RL |
667 | |
668 | L<CTLOG_new(3)>, L<CTLOG_new_from_base64(3)> and L<CTLOG_STORE_new(3)> | |
b7140b06 | 669 | |
2fc02378 | 670 | =item * |
b7140b06 | 671 | |
04916913 | 672 | L<CT_POLICY_EVAL_CTX_new(3)> |
b7140b06 | 673 | |
2fc02378 | 674 | =item * |
b7140b06 | 675 | |
04916913 RL |
676 | L<d2i_AutoPrivateKey(3)>, L<d2i_PrivateKey(3)> and L<d2i_PUBKEY(3)> |
677 | ||
2fc02378 | 678 | =item * |
04916913 RL |
679 | |
680 | L<d2i_PrivateKey_bio(3)> and L<d2i_PrivateKey_fp(3)> | |
b7140b06 SL |
681 | |
682 | Use L<d2i_PrivateKey_ex_bio(3)> and L<d2i_PrivateKey_ex_fp(3)> | |
683 | ||
2fc02378 | 684 | =item * |
04916913 RL |
685 | |
686 | L<EC_GROUP_new(3)> | |
b7140b06 SL |
687 | |
688 | Use L<EC_GROUP_new_by_curve_name_ex(3)> or L<EC_GROUP_new_from_params(3)>. | |
689 | ||
2fc02378 | 690 | =item * |
04916913 RL |
691 | |
692 | L<EVP_DigestSignInit(3)> and L<EVP_DigestVerifyInit(3)> | |
693 | ||
2fc02378 | 694 | =item * |
04916913 RL |
695 | |
696 | L<EVP_PBE_CipherInit(3)>, L<EVP_PBE_find(3)> and L<EVP_PBE_scrypt(3)> | |
697 | ||
2fc02378 | 698 | =item * |
b7140b06 | 699 | |
1941684d SL |
700 | L<PKCS5_PBE_keyivgen(3)> |
701 | ||
2fc02378 | 702 | =item * |
1941684d | 703 | |
04916913 | 704 | L<EVP_PKCS82PKEY(3)> |
b7140b06 | 705 | |
2fc02378 | 706 | =item * |
b7140b06 | 707 | |
04916913 | 708 | L<EVP_PKEY_CTX_new_id(3)> |
b7140b06 SL |
709 | |
710 | Use L<EVP_PKEY_CTX_new_from_name(3)> | |
711 | ||
2fc02378 | 712 | =item * |
04916913 RL |
713 | |
714 | L<EVP_PKEY_derive_set_peer(3)>, L<EVP_PKEY_new_raw_private_key(3)> | |
b7140b06 SL |
715 | and L<EVP_PKEY_new_raw_public_key(3)> |
716 | ||
2fc02378 | 717 | =item * |
04916913 RL |
718 | |
719 | L<EVP_SignFinal(3)> and L<EVP_VerifyFinal(3)> | |
720 | ||
2fc02378 | 721 | =item * |
04916913 RL |
722 | |
723 | L<NCONF_new(3)> | |
b7140b06 | 724 | |
2fc02378 | 725 | =item * |
b7140b06 | 726 | |
04916913 | 727 | L<OCSP_RESPID_match(3)> and L<OCSP_RESPID_set_by_key(3)> |
b7140b06 | 728 | |
2fc02378 | 729 | =item * |
b7140b06 | 730 | |
04916913 | 731 | L<OPENSSL_thread_stop(3)> |
b7140b06 | 732 | |
2fc02378 | 733 | =item * |
04916913 RL |
734 | |
735 | L<OSSL_STORE_open(3)> | |
736 | ||
2fc02378 | 737 | =item * |
04916913 RL |
738 | |
739 | L<PEM_read_bio_Parameters(3)>, L<PEM_read_bio_PrivateKey(3)>, L<PEM_read_bio_PUBKEY(3)>, | |
b7140b06 SL |
740 | L<PEM_read_PrivateKey(3)> and L<PEM_read_PUBKEY(3)> |
741 | ||
2fc02378 | 742 | =item * |
04916913 RL |
743 | |
744 | L<PEM_write_bio_PrivateKey(3)>, L<PEM_write_bio_PUBKEY(3)>, L<PEM_write_PrivateKey(3)> | |
b7140b06 SL |
745 | and L<PEM_write_PUBKEY(3)> |
746 | ||
2fc02378 | 747 | =item * |
b7140b06 | 748 | |
04916913 RL |
749 | L<PEM_X509_INFO_read_bio(3)> and L<PEM_X509_INFO_read(3)> |
750 | ||
2fc02378 | 751 | =item * |
04916913 RL |
752 | |
753 | L<PKCS12_add_key(3)>, L<PKCS12_add_safe(3)>, L<PKCS12_add_safes(3)>, | |
b7140b06 SL |
754 | L<PKCS12_create(3)>, L<PKCS12_decrypt_skey(3)>, L<PKCS12_init(3)>, L<PKCS12_item_decrypt_d2i(3)>, |
755 | L<PKCS12_item_i2d_encrypt(3)>, L<PKCS12_key_gen_asc(3)>, L<PKCS12_key_gen_uni(3)>, | |
756 | L<PKCS12_key_gen_utf8(3)>, L<PKCS12_pack_p7encdata(3)>, L<PKCS12_pbe_crypt(3)>, | |
757 | L<PKCS12_PBE_keyivgen(3)>, L<PKCS12_SAFEBAG_create_pkcs8_encrypt(3)> | |
758 | ||
2fc02378 | 759 | =item * |
04916913 RL |
760 | |
761 | L<PKCS5_pbe_set0_algor(3)>, L<PKCS5_pbe_set(3)>, L<PKCS5_pbe2_set_iv(3)>, | |
b7140b06 SL |
762 | L<PKCS5_pbkdf2_set(3)> and L<PKCS5_v2_scrypt_keyivgen(3)> |
763 | ||
2fc02378 | 764 | =item * |
04916913 RL |
765 | |
766 | L<PKCS7_encrypt(3)>, L<PKCS7_new(3)> and L<PKCS7_sign(3)> | |
767 | ||
2fc02378 | 768 | =item * |
04916913 RL |
769 | |
770 | L<PKCS8_decrypt(3)>, L<PKCS8_encrypt(3)> and L<PKCS8_set0_pbe(3)> | |
771 | ||
2fc02378 | 772 | =item * |
b7140b06 | 773 | |
04916913 | 774 | L<RAND_bytes(3)> and L<RAND_priv_bytes(3)> |
b7140b06 | 775 | |
2fc02378 | 776 | =item * |
b7140b06 | 777 | |
04916913 | 778 | L<SMIME_write_ASN1(3)> |
b7140b06 | 779 | |
2fc02378 | 780 | =item * |
b7140b06 | 781 | |
1941684d SL |
782 | L<SSL_load_client_CA_file(3)> |
783 | ||
2fc02378 | 784 | =item * |
1941684d SL |
785 | |
786 | L<SSL_CTX_new(3)> | |
787 | ||
2fc02378 | 788 | =item * |
1941684d | 789 | |
04916913 | 790 | L<TS_RESP_CTX_new(3)> |
b7140b06 | 791 | |
2fc02378 | 792 | =item * |
b7140b06 | 793 | |
04916913 | 794 | L<X509_CRL_new(3)> |
b7140b06 | 795 | |
2fc02378 | 796 | =item * |
b7140b06 | 797 | |
04916913 | 798 | L<X509_load_cert_crl_file(3)> and L<X509_load_cert_file(3)> |
b7140b06 | 799 | |
2fc02378 | 800 | =item * |
b7140b06 | 801 | |
04916913 RL |
802 | L<X509_LOOKUP_by_subject(3)> and L<X509_LOOKUP_ctrl(3)> |
803 | ||
2fc02378 | 804 | =item * |
04916913 RL |
805 | |
806 | L<X509_NAME_hash(3)> | |
807 | ||
2fc02378 | 808 | =item * |
04916913 RL |
809 | |
810 | L<X509_new(3)> | |
811 | ||
2fc02378 | 812 | =item * |
04916913 RL |
813 | |
814 | L<X509_REQ_new(3)> and L<X509_REQ_verify(3)> | |
815 | ||
2fc02378 | 816 | =item * |
04916913 RL |
817 | |
818 | L<X509_STORE_CTX_new(3)>, L<X509_STORE_set_default_paths(3)>, L<X509_STORE_load_file(3)>, | |
b7140b06 SL |
819 | L<X509_STORE_load_locations(3)> and L<X509_STORE_load_store(3)> |
820 | ||
821 | =back | |
822 | ||
823 | =head4 New functions that use a Library context | |
824 | ||
825 | The following functions can be passed a library context if required. | |
826 | Passing NULL will use the default library context. | |
827 | ||
828 | =over 4 | |
829 | ||
2fc02378 | 830 | =item * |
04916913 | 831 | |
1941684d SL |
832 | L<BIO_new_from_core_bio(3)> |
833 | ||
2fc02378 | 834 | =item * |
1941684d | 835 | |
04916913 RL |
836 | L<EVP_ASYM_CIPHER_fetch(3)> and L<EVP_ASYM_CIPHER_do_all_provided(3)> |
837 | ||
2fc02378 | 838 | =item * |
04916913 RL |
839 | |
840 | L<EVP_CIPHER_fetch(3)> and L<EVP_CIPHER_do_all_provided(3)> | |
b7140b06 | 841 | |
2fc02378 | 842 | =item * |
b7140b06 | 843 | |
04916913 | 844 | L<EVP_default_properties_enable_fips(3)> and |
b7140b06 SL |
845 | L<EVP_default_properties_is_fips_enabled(3)> |
846 | ||
2fc02378 | 847 | =item * |
04916913 RL |
848 | |
849 | L<EVP_KDF_fetch(3)> and L<EVP_KDF_do_all_provided(3)> | |
850 | ||
2fc02378 | 851 | =item * |
04916913 RL |
852 | |
853 | L<EVP_KEM_fetch(3)> and L<EVP_KEM_do_all_provided(3)> | |
b7140b06 | 854 | |
2fc02378 | 855 | =item * |
b7140b06 | 856 | |
04916913 | 857 | L<EVP_KEYEXCH_fetch(3)> and L<EVP_KEYEXCH_do_all_provided(3)> |
b7140b06 | 858 | |
2fc02378 | 859 | =item * |
b7140b06 | 860 | |
04916913 | 861 | L<EVP_KEYMGMT_fetch(3)> and L<EVP_KEYMGMT_do_all_provided(3)> |
b7140b06 | 862 | |
2fc02378 | 863 | =item * |
b7140b06 | 864 | |
04916913 | 865 | L<EVP_MAC_fetch(3)> and L<EVP_MAC_do_all_provided(3)> |
b7140b06 | 866 | |
2fc02378 | 867 | =item * |
b7140b06 | 868 | |
04916913 | 869 | L<EVP_MD_fetch(3)> and L<EVP_MD_do_all_provided(3)> |
b7140b06 | 870 | |
2fc02378 | 871 | =item * |
b7140b06 | 872 | |
04916913 | 873 | L<EVP_PKEY_CTX_new_from_pkey(3)> |
b7140b06 | 874 | |
2fc02378 | 875 | =item * |
b7140b06 | 876 | |
04916913 | 877 | L<EVP_PKEY_Q_keygen(3)> |
b7140b06 | 878 | |
2fc02378 | 879 | =item * |
b7140b06 | 880 | |
04916913 | 881 | L<EVP_Q_mac(3)> and L<EVP_Q_digest(3)> |
b7140b06 | 882 | |
2fc02378 | 883 | =item * |
b7140b06 | 884 | |
04916913 | 885 | L<EVP_RAND(3)> and L<EVP_RAND_do_all_provided(3)> |
b7140b06 | 886 | |
2fc02378 | 887 | =item * |
b7140b06 | 888 | |
04916913 | 889 | L<EVP_set_default_properties(3)> |
b7140b06 | 890 | |
2fc02378 | 891 | =item * |
b7140b06 | 892 | |
04916913 | 893 | L<EVP_SIGNATURE_fetch(3)> and L<EVP_SIGNATURE_do_all_provided(3)> |
b7140b06 | 894 | |
2fc02378 | 895 | =item * |
04916913 RL |
896 | |
897 | L<OSSL_CMP_CTX_new(3)> and L<OSSL_CMP_SRV_CTX_new(3)> | |
898 | ||
2fc02378 | 899 | =item * |
04916913 RL |
900 | |
901 | L<OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(3)> | |
902 | ||
2fc02378 | 903 | =item * |
04916913 RL |
904 | |
905 | L<OSSL_CRMF_MSG_create_popo(3)> and L<OSSL_CRMF_MSGS_verify_popo(3)> | |
906 | ||
2fc02378 | 907 | =item * |
04916913 RL |
908 | |
909 | L<OSSL_CRMF_pbm_new(3)> and L<OSSL_CRMF_pbmp_new(3)> | |
910 | ||
2fc02378 | 911 | =item * |
04916913 RL |
912 | |
913 | L<OSSL_DECODER_CTX_add_extra(3)> and L<OSSL_DECODER_CTX_new_for_pkey(3)> | |
914 | ||
2fc02378 | 915 | =item * |
04916913 RL |
916 | |
917 | L<OSSL_DECODER_fetch(3)> and L<OSSL_DECODER_do_all_provided(3)> | |
918 | ||
2fc02378 | 919 | =item * |
04916913 RL |
920 | |
921 | L<OSSL_ENCODER_CTX_add_extra(3)> | |
922 | ||
2fc02378 | 923 | =item * |
04916913 RL |
924 | |
925 | L<OSSL_ENCODER_fetch(3)> and L<OSSL_ENCODER_do_all_provided(3)> | |
926 | ||
2fc02378 | 927 | =item * |
04916913 RL |
928 | |
929 | L<OSSL_LIB_CTX_free(3)>, L<OSSL_LIB_CTX_load_config(3)> and L<OSSL_LIB_CTX_set0_default(3)> | |
930 | ||
2fc02378 | 931 | =item * |
04916913 RL |
932 | |
933 | L<OSSL_PROVIDER_add_builtin(3)>, L<OSSL_PROVIDER_available(3)>, | |
b7140b06 SL |
934 | L<OSSL_PROVIDER_do_all(3)>, L<OSSL_PROVIDER_load(3)>, |
935 | L<OSSL_PROVIDER_set_default_search_path(3)> and L<OSSL_PROVIDER_try_load(3)> | |
936 | ||
2fc02378 | 937 | =item * |
04916913 RL |
938 | |
939 | L<OSSL_SELF_TEST_get_callback(3)> and L<OSSL_SELF_TEST_set_callback(3)> | |
940 | ||
2fc02378 | 941 | =item * |
04916913 RL |
942 | |
943 | L<OSSL_STORE_attach(3)> | |
944 | ||
2fc02378 | 945 | =item * |
b7140b06 | 946 | |
04916913 | 947 | L<OSSL_STORE_LOADER_fetch(3)> and L<OSSL_STORE_LOADER_do_all_provided(3)> |
b7140b06 | 948 | |
2fc02378 | 949 | =item * |
b7140b06 | 950 | |
04916913 | 951 | L<RAND_get0_primary(3)>, L<RAND_get0_private(3)>, L<RAND_get0_public(3)>, |
b7140b06 SL |
952 | L<RAND_set_DRBG_type(3)> and L<RAND_set_seed_source_type(3)> |
953 | ||
954 | =back | |
955 | ||
956 | =head3 Providers | |
957 | ||
958 | Providers are described in detail here L<crypto(7)/Providers>. | |
959 | See also L<crypto(7)/OPENSSL PROVIDERS>. | |
960 | ||
961 | =head3 Fetching algorithms and property queries | |
962 | ||
963 | Implicit and Explicit Fetching is described in detail here | |
964 | L<crypto(7)/ALGORITHM FETCHING>. | |
965 | ||
318a9dfa | 966 | =head3 Mapping EVP controls and flags to provider L<OSSL_PARAM(3)> parameters |
9ff4b7b0 SL |
967 | |
968 | The existing functions for controls (such as L<EVP_CIPHER_CTX_ctrl(3)>) and | |
969 | manipulating flags (such as L<EVP_MD_CTX_set_flags(3)>)internally use | |
970 | B<OSSL_PARAMS> to pass information to/from provider objects. | |
971 | See L<OSSL_PARAM(3)> for additional information related to parameters. | |
972 | ||
973 | For ciphers see L<EVP_EncryptInit(3)/CONTROLS>, L<EVP_EncryptInit(3)/FLAGS> and | |
974 | L<EVP_EncryptInit(3)/PARAMETERS>. | |
975 | ||
976 | For digests see L<EVP_DigestInit(3)/CONTROLS>, L<EVP_DigestInit(3)/FLAGS> and | |
977 | L<EVP_DigestInit(3)/PARAMETERS>. | |
978 | ||
b7140b06 SL |
979 | =head3 Deprecation of Low Level Functions |
980 | ||
981 | A significant number of APIs have been deprecated in OpenSSL 3.0. | |
982 | This section describes some common categories of deprecations. | |
983 | See L</Deprecated function mappings> for the list of deprecated functions | |
984 | that refer to these categories. | |
985 | ||
986 | =head4 Providers are a replacement for engines and low-level method overrides | |
987 | ||
988 | Any accessor that uses an ENGINE is deprecated (such as EVP_PKEY_set1_engine()). | |
989 | Applications using engines should instead use providers. | |
990 | ||
e304aa87 | 991 | Before providers were added algorithms were overridden by changing the methods |
b7140b06 SL |
992 | used by algorithms. All these methods such as RSA_new_method() and RSA_meth_new() |
993 | are now deprecated and can be replaced by using providers instead. | |
994 | ||
995 | =head4 Deprecated i2d and d2i functions for low-level key types | |
996 | ||
997 | Any i2d and d2i functions such as d2i_DHparams() that take a low-level key type | |
998 | have been deprecated. Applications should instead use the L<OSSL_DECODER(3)> and | |
999 | L<OSSL_ENCODER(3)> APIs to read and write files. | |
1000 | See L<d2i_RSAPrivateKey(3)/Migration> for further details. | |
1001 | ||
1002 | =head4 Deprecated low-level key object getters and setters | |
1003 | ||
1004 | Applications that set or get low-level key objects (such as EVP_PKEY_set1_DH() | |
1005 | or EVP_PKEY_get0()) should instead use the OSSL_ENCODER | |
1006 | (See L<OSSL_ENCODER_to_bio(3)>) or OSSL_DECODER (See L<OSSL_DECODER_from_bio(3)>) | |
1007 | APIs, or alternatively use L<EVP_PKEY_fromdata(3)> or L<EVP_PKEY_todata(3)>. | |
1008 | ||
1009 | =head4 Deprecated low-level key parameter getters | |
1010 | ||
1011 | Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now | |
1012 | deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>, | |
1013 | L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>, | |
57cd10dd | 1014 | L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or |
b7140b06 SL |
1015 | L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY. |
1016 | Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>, | |
1017 | L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>, | |
1018 | L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and | |
1019 | L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>. | |
1020 | Applications may also use L<EVP_PKEY_todata(3)> to return all fields. | |
1021 | ||
1022 | =head4 Deprecated low-level key parameter setters | |
1023 | ||
1024 | Functions that access low-level objects directly such as L<RSA_set0_crt_params(3)> | |
1025 | are now deprecated. Applications should use L<EVP_PKEY_fromdata(3)> to create | |
1026 | new keys from user provided key data. Keys should be immutable once they are | |
1027 | created, so if required the user may use L<EVP_PKEY_todata(3)>, L<OSSL_PARAM_merge(3)>, | |
1028 | and L<EVP_PKEY_fromdata(3)> to create a modified key. | |
1029 | See L<EVP_PKEY-DH(7)/Examples> for more information. | |
1030 | See L</Deprecated low-level key generation functions> for information on | |
1031 | generating a key using parameters. | |
1032 | ||
1033 | =head4 Deprecated low-level object creation | |
1034 | ||
1035 | Low-level objects were created using methods such as L<RSA_new(3)>, | |
1036 | L<RSA_up_ref(3)> and L<RSA_free(3)>. Applications should instead use the | |
1037 | high-level EVP_PKEY APIs, e.g. L<EVP_PKEY_new(3)>, L<EVP_PKEY_up_ref(3)> and | |
1038 | L<EVP_PKEY_free(3)>. | |
1039 | See also L<EVP_PKEY_CTX_new_from_name(3)> and L<EVP_PKEY_CTX_new_from_pkey(3)>. | |
1040 | ||
04916913 | 1041 | EVP_PKEYs may be created in a variety of ways: |
b7140b06 SL |
1042 | See also L</Deprecated low-level key generation functions>, |
1043 | L</Deprecated low-level key reading and writing functions> and | |
1044 | L</Deprecated low-level key parameter setters>. | |
1045 | ||
1046 | =head4 Deprecated low-level encryption functions | |
1047 | ||
1048 | Low-level encryption functions such as L<AES_encrypt(3)> and L<AES_decrypt(3)> | |
1049 | have been informally discouraged from use for a long time. Applications should | |
1050 | instead use the high level EVP APIs L<EVP_EncryptInit_ex(3)>, | |
1051 | L<EVP_EncryptUpdate(3)>, and L<EVP_EncryptFinal_ex(3)> or | |
1052 | L<EVP_DecryptInit_ex(3)>, L<EVP_DecryptUpdate(3)> and L<EVP_DecryptFinal_ex(3)>. | |
1053 | ||
1054 | =head4 Deprecated low-level digest functions | |
1055 | ||
1056 | Use of low-level digest functions such as L<SHA1_Init(3)> have been | |
1057 | informally discouraged from use for a long time. Applications should instead | |
1058 | use the the high level EVP APIs L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)> | |
1059 | and L<EVP_DigestFinal_ex(3)>, or the quick one-shot L<EVP_Q_digest(3)>. | |
1060 | ||
1061 | Note that the functions L<SHA1(3)>, L<SHA224(3)>, L<SHA256(3)>, L<SHA384(3)> | |
1062 | and L<SHA512(3)> have changed to macros that use L<EVP_Q_digest(3)>. | |
1063 | ||
1064 | =head4 Deprecated low-level signing functions | |
1065 | ||
1066 | Use of low-level signing functions such as L<DSA_sign(3)> have been | |
1067 | informally discouraged for a long time. Instead applications should use | |
1068 | L<EVP_DigestSign(3)> and L<EVP_DigestVerify(3)>. | |
1069 | See also L<EVP_SIGNATURE-RSA(7)>, L<EVP_SIGNATURE-DSA(7)>, | |
1070 | L<EVP_SIGNATURE-ECDSA(7)> and L<EVP_SIGNATURE-ED25519(7)>. | |
1071 | ||
1072 | =head4 Deprecated low-level MAC functions | |
1073 | ||
1074 | Low-level mac functions such as L<CMAC_Init(3)> are deprecated. | |
1075 | Applications should instead use the new L<EVP_MAC(3)> interface, using | |
1076 | L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>, | |
1077 | L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)> or the single-shot MAC function | |
1078 | L<EVP_Q_mac(3)>. | |
1079 | See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>, | |
1080 | L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and | |
1081 | L<EVP_MAC-Siphash(7)> for additional information. | |
1082 | ||
d1ebd993 | 1083 | Note that the one-shot method HMAC() is still available for compatibility purposes, |
1084 | but this can also be replaced by using EVP_Q_MAC if a library context is required. | |
b7140b06 SL |
1085 | |
1086 | =head4 Deprecated low-level validation functions | |
1087 | ||
1088 | Low-level validation functions such as L<DH_check(3)> have been informally | |
1089 | discouraged from use for a long time. Applications should instead use the high-level | |
1090 | EVP_PKEY APIs such as L<EVP_PKEY_check(3)>, L<EVP_PKEY_param_check(3)>, | |
1091 | L<EVP_PKEY_param_check_quick(3)>, L<EVP_PKEY_public_check(3)>, | |
1092 | L<EVP_PKEY_public_check_quick(3)>, L<EVP_PKEY_private_check(3)>, | |
1093 | and L<EVP_PKEY_pairwise_check(3)>. | |
1094 | ||
1095 | =head4 Deprecated low-level key exchange functions | |
1096 | ||
1097 | Many low-level functions have been informally discouraged from use for a long | |
1098 | time. Applications should instead use L<EVP_PKEY_derive(3)>. | |
1099 | See L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYEXCH-ECDH(7)> and L<EVP_KEYEXCH-X25519(7)>. | |
1100 | ||
1101 | =head4 Deprecated low-level key generation functions | |
1102 | ||
1103 | Many low-level functions have been informally discouraged from use for a long | |
1104 | time. Applications should instead use L<EVP_PKEY_keygen_init(3)> and | |
1105 | L<EVP_PKEY_generate(3)> as described in L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, | |
1106 | L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-EC(7)> and L<EVP_PKEY-X25519(7)>. | |
1107 | The 'quick' one-shot function L<EVP_PKEY_Q_keygen(3)> and macros for the most | |
1108 | common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)> may also be used. | |
1109 | ||
1110 | =head4 Deprecated low-level key reading and writing functions | |
1111 | ||
1112 | Use of low-level objects (such as DSA) has been informally discouraged from use | |
1113 | for a long time. Functions to read and write these low-level objects (such as | |
1114 | PEM_read_DSA_PUBKEY()) should be replaced. Applications should instead use | |
1115 | L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>. | |
1116 | ||
1117 | =head4 Deprecated low-level key printing functions | |
1118 | ||
1119 | Use of low-level objects (such as DSA) has been informally discouraged from use | |
1120 | for a long time. Functions to print these low-level objects such as | |
1121 | DSA_print() should be replaced with the equivalent EVP_PKEY functions. | |
1122 | Application should use one of L<EVP_PKEY_print_public(3)>, | |
1123 | L<EVP_PKEY_print_private(3)>, L<EVP_PKEY_print_params(3)>, | |
1124 | L<EVP_PKEY_print_public_fp(3)>, L<EVP_PKEY_print_private_fp(3)> or | |
1125 | L<EVP_PKEY_print_params_fp(3)>. Note that internally these use | |
1126 | L<OSSL_ENCODER_to_bio(3)> and L<OSSL_DECODER_from_bio(3)>. | |
1127 | ||
1128 | =head3 Deprecated function mappings | |
1129 | ||
1130 | The following functions have been deprecated in 3.0. | |
1131 | ||
1132 | =over 4 | |
1133 | ||
2fc02378 | 1134 | =item * |
04916913 RL |
1135 | |
1136 | AES_bi_ige_encrypt() and AES_ige_encrypt() | |
b7140b06 SL |
1137 | |
1138 | There is no replacement for the IGE functions. New code should not use these modes. | |
1139 | These undocumented functions were never integrated into the EVP layer. | |
1140 | They implemented the AES Infinite Garble Extension (IGE) mode and AES | |
1141 | Bi-directional IGE mode. These modes were never formally standardised and | |
1142 | usage of these functions is believed to be very small. In particular | |
1143 | AES_bi_ige_encrypt() has a known bug. It accepts 2 AES keys, but only one | |
1144 | is ever used. The security implications are believed to be minimal, but | |
57cd10dd | 1145 | this issue was never fixed for backwards compatibility reasons. |
b7140b06 | 1146 | |
2fc02378 | 1147 | =item * |
04916913 RL |
1148 | |
1149 | AES_encrypt(), AES_decrypt(), AES_set_encrypt_key(), AES_set_decrypt_key(), | |
1150 | AES_cbc_encrypt(), AES_cfb128_encrypt(), AES_cfb1_encrypt(), AES_cfb8_encrypt(), | |
1151 | AES_ecb_encrypt(), AES_ofb128_encrypt() | |
b7140b06 | 1152 | |
2fc02378 | 1153 | =item * |
04916913 RL |
1154 | |
1155 | AES_unwrap_key(), AES_wrap_key() | |
b7140b06 SL |
1156 | |
1157 | See L</Deprecated low-level encryption functions> | |
1158 | ||
2fc02378 | 1159 | =item * |
04916913 RL |
1160 | |
1161 | AES_options() | |
b7140b06 SL |
1162 | |
1163 | There is no replacement. It returned a string indicating if the AES code was unrolled. | |
1164 | ||
2fc02378 | 1165 | =item * |
04916913 RL |
1166 | |
1167 | ASN1_digest(), ASN1_sign(), ASN1_verify() | |
b7140b06 SL |
1168 | |
1169 | There are no replacements. These old functions are not used, and could be | |
1170 | disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7. | |
1171 | ||
2fc02378 | 1172 | =item * |
04916913 RL |
1173 | |
1174 | ASN1_STRING_length_set() | |
b7140b06 SL |
1175 | |
1176 | Use L<ASN1_STRING_set(3)> or L<ASN1_STRING_set0(3)> instead. | |
1177 | This was a potentially unsafe function that could change the bounds of a | |
1178 | previously passed in pointer. | |
1179 | ||
2fc02378 | 1180 | =item * |
04916913 RL |
1181 | |
1182 | BF_encrypt(), BF_decrypt(), BF_set_key(), BF_cbc_encrypt(), BF_cfb64_encrypt(), | |
1183 | BF_ecb_encrypt(), BF_ofb64_encrypt() | |
b7140b06 SL |
1184 | |
1185 | See L</Deprecated low-level encryption functions>. | |
1186 | The Blowfish algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
1187 | ||
2fc02378 | 1188 | =item * |
04916913 RL |
1189 | |
1190 | BF_options() | |
b7140b06 SL |
1191 | |
1192 | There is no replacement. This option returned a constant string. | |
1193 | ||
2fc02378 | 1194 | =item * |
04916913 | 1195 | |
0800318a TM |
1196 | BIO_get_callback(), BIO_set_callback(), BIO_debug_callback() |
1197 | ||
1198 | Use the respective non-deprecated _ex() functions. | |
1199 | ||
2fc02378 | 1200 | =item * |
0800318a | 1201 | |
04916913 | 1202 | BN_is_prime_ex(), BN_is_prime_fasttest_ex() |
b7140b06 | 1203 | |
4c100990 | 1204 | Use L<BN_check_prime(3)> which avoids possible misuse and always uses at least |
b7140b06 SL |
1205 | 64 rounds of the Miller-Rabin primality test. |
1206 | ||
2fc02378 | 1207 | =item * |
04916913 RL |
1208 | |
1209 | BN_pseudo_rand(), BN_pseudo_rand_range() | |
b7140b06 SL |
1210 | |
1211 | Use L<BN_rand(3)> and L<BN_rand_range(3)>. | |
1212 | ||
2fc02378 | 1213 | =item * |
04916913 RL |
1214 | |
1215 | BN_X931_derive_prime_ex(), BN_X931_generate_prime_ex(), BN_X931_generate_Xpq() | |
b7140b06 SL |
1216 | |
1217 | There are no replacements for these low-level functions. They were used internally | |
1218 | by RSA_X931_derive_ex() and RSA_X931_generate_key_ex() which are also deprecated. | |
1219 | Use L<EVP_PKEY_keygen(3)> instead. | |
1220 | ||
2fc02378 | 1221 | =item * |
04916913 RL |
1222 | |
1223 | Camellia_encrypt(), Camellia_decrypt(), Camellia_set_key(), | |
1224 | Camellia_cbc_encrypt(), Camellia_cfb128_encrypt(), Camellia_cfb1_encrypt(), | |
1225 | Camellia_cfb8_encrypt(), Camellia_ctr128_encrypt(), Camellia_ecb_encrypt(), | |
1226 | Camellia_ofb128_encrypt() | |
b7140b06 SL |
1227 | |
1228 | See L</Deprecated low-level encryption functions>. | |
1229 | ||
2fc02378 | 1230 | =item * |
04916913 RL |
1231 | |
1232 | CAST_encrypt(), CAST_decrypt(), CAST_set_key(), CAST_cbc_encrypt(), | |
1233 | CAST_cfb64_encrypt(), CAST_ecb_encrypt(), CAST_ofb64_encrypt() | |
b7140b06 SL |
1234 | |
1235 | See L</Deprecated low-level encryption functions>. | |
1236 | The CAST algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
1237 | ||
2fc02378 | 1238 | =item * |
04916913 RL |
1239 | |
1240 | CMAC_CTX_new(), CMAC_CTX_cleanup(), CMAC_CTX_copy(), CMAC_CTX_free(), | |
1241 | CMAC_CTX_get0_cipher_ctx() | |
b7140b06 SL |
1242 | |
1243 | See L</Deprecated low-level MAC functions>. | |
1244 | ||
2fc02378 | 1245 | =item * |
04916913 RL |
1246 | |
1247 | CMAC_Init(), CMAC_Update(), CMAC_Final(), CMAC_resume() | |
b7140b06 SL |
1248 | |
1249 | See L</Deprecated low-level MAC functions>. | |
1250 | ||
2fc02378 | 1251 | =item * |
04916913 RL |
1252 | |
1253 | CRYPTO_mem_ctrl(), CRYPTO_mem_debug_free(), CRYPTO_mem_debug_malloc(), | |
1254 | CRYPTO_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_realloc(), | |
1255 | CRYPTO_mem_leaks(), CRYPTO_mem_leaks_cb(), CRYPTO_mem_leaks_fp(), | |
1256 | CRYPTO_set_mem_debug() | |
b7140b06 SL |
1257 | |
1258 | Memory-leak checking has been deprecated in favor of more modern development | |
1259 | tools, such as compiler memory and leak sanitizers or Valgrind. | |
1260 | ||
2fc02378 | 1261 | =item * |
04916913 | 1262 | |
7f5a9399 SL |
1263 | CRYPTO_cts128_encrypt_block(), CRYPTO_cts128_encrypt(), |
1264 | CRYPTO_cts128_decrypt_block(), CRYPTO_cts128_decrypt(), | |
1265 | CRYPTO_nistcts128_encrypt_block(), CRYPTO_nistcts128_encrypt(), | |
1266 | CRYPTO_nistcts128_decrypt_block(), CRYPTO_nistcts128_decrypt() | |
1267 | ||
1268 | Use the higher level functions EVP_CipherInit_ex2(), EVP_CipherUpdate() and | |
1269 | EVP_CipherFinal_ex() instead. | |
1270 | See the "cts_mode" parameter in | |
1271 | L<EVP_EncryptInit(3)/Gettable and Settable EVP_CIPHER_CTX parameters>. | |
1272 | See L<EVP_EncryptInit(3)/EXAMPLES> for a AES-256-CBC-CTS example. | |
1273 | ||
1274 | =item * | |
1275 | ||
04916913 RL |
1276 | d2i_DHparams(), d2i_DHxparams(), d2i_DSAparams(), d2i_DSAPrivateKey(), |
1277 | d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), d2i_DSA_PUBKEY(), | |
1278 | d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), d2i_DSAPublicKey(), | |
1279 | d2i_ECParameters(), d2i_ECPrivateKey(), d2i_ECPrivateKey_bio(), | |
1280 | d2i_ECPrivateKey_fp(), d2i_EC_PUBKEY(), d2i_EC_PUBKEY_bio(), | |
1281 | d2i_EC_PUBKEY_fp(), o2i_ECPublicKey(), d2i_RSAPrivateKey(), | |
1282 | d2i_RSAPrivateKey_bio(), d2i_RSAPrivateKey_fp(), d2i_RSA_PUBKEY(), | |
1283 | d2i_RSA_PUBKEY_bio(), d2i_RSA_PUBKEY_fp(), d2i_RSAPublicKey(), | |
1284 | d2i_RSAPublicKey_bio(), d2i_RSAPublicKey_fp() | |
b7140b06 SL |
1285 | |
1286 | See L</Deprecated i2d and d2i functions for low-level key types> | |
1287 | ||
2fc02378 | 1288 | =item * |
04916913 RL |
1289 | |
1290 | DES_crypt(), DES_fcrypt(), DES_encrypt1(), DES_encrypt2(), DES_encrypt3(), | |
1291 | DES_decrypt3(), DES_ede3_cbc_encrypt(), DES_ede3_cfb64_encrypt(), | |
1292 | DES_ede3_cfb_encrypt(),DES_ede3_ofb64_encrypt(), | |
1293 | DES_ecb_encrypt(), DES_ecb3_encrypt(), DES_ofb64_encrypt(), DES_ofb_encrypt(), | |
1294 | DES_cfb64_encrypt DES_cfb_encrypt(), DES_cbc_encrypt(), DES_ncbc_encrypt(), | |
57cd10dd | 1295 | DES_pcbc_encrypt(), DES_xcbc_encrypt(), DES_cbc_cksum(), DES_quad_cksum(), |
04916913 RL |
1296 | DES_check_key_parity(), DES_is_weak_key(), DES_key_sched(), DES_options(), |
1297 | DES_random_key(), DES_set_key(), DES_set_key_checked(), DES_set_key_unchecked(), | |
1298 | DES_set_odd_parity(), DES_string_to_2keys(), DES_string_to_key() | |
b7140b06 SL |
1299 | |
1300 | See L</Deprecated low-level encryption functions>. | |
1301 | Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB", | |
1302 | "DES-CFB1" and "DES-CFB8" have been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
1303 | ||
2fc02378 | 1304 | =item * |
04916913 RL |
1305 | |
1306 | DH_bits(), DH_security_bits(), DH_size() | |
b7140b06 | 1307 | |
ed576acd TM |
1308 | Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and |
1309 | L<EVP_PKEY_get_size(3)>. | |
b7140b06 | 1310 | |
2fc02378 | 1311 | =item * |
04916913 RL |
1312 | |
1313 | DH_check(), DH_check_ex(), DH_check_params(), DH_check_params_ex(), | |
1314 | DH_check_pub_key(), DH_check_pub_key_ex() | |
b7140b06 SL |
1315 | |
1316 | See L</Deprecated low-level validation functions> | |
1317 | ||
2fc02378 | 1318 | =item * |
04916913 RL |
1319 | |
1320 | DH_clear_flags(), DH_test_flags(), DH_set_flags() | |
b7140b06 | 1321 | |
04916913 RL |
1322 | The B<DH_FLAG_CACHE_MONT_P> flag has been deprecated without replacement. |
1323 | The B<DH_FLAG_TYPE_DH> and B<DH_FLAG_TYPE_DHX> have been deprecated. | |
b7140b06 SL |
1324 | Use EVP_PKEY_is_a() to determine the type of a key. |
1325 | There is no replacement for setting these flags. | |
1326 | ||
2fc02378 | 1327 | =item * |
04916913 RL |
1328 | |
1329 | DH_compute_key() DH_compute_key_padded() | |
b7140b06 SL |
1330 | |
1331 | See L</Deprecated low-level key exchange functions>. | |
1332 | ||
2fc02378 | 1333 | =item * |
04916913 RL |
1334 | |
1335 | DH_new(), DH_new_by_nid(), DH_free(), DH_up_ref() | |
b7140b06 SL |
1336 | |
1337 | See L</Deprecated low-level object creation> | |
1338 | ||
2fc02378 | 1339 | =item * |
04916913 RL |
1340 | |
1341 | DH_generate_key(), DH_generate_parameters_ex() | |
b7140b06 SL |
1342 | |
1343 | See L</Deprecated low-level key generation functions>. | |
1344 | ||
2fc02378 | 1345 | =item * |
04916913 RL |
1346 | |
1347 | DH_get0_pqg(), DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_key(), | |
1348 | DH_get0_priv_key(), DH_get0_pub_key(), DH_get_length(), DH_get_nid() | |
b7140b06 SL |
1349 | |
1350 | See L</Deprecated low-level key parameter getters> | |
1351 | ||
2fc02378 | 1352 | =item * |
04916913 RL |
1353 | |
1354 | DH_get_1024_160(), DH_get_2048_224(), DH_get_2048_256() | |
b7140b06 SL |
1355 | |
1356 | Applications should instead set the B<OSSL_PKEY_PARAM_GROUP_NAME> as specified in | |
1357 | L<EVP_PKEY-DH(7)/DH parameters>) to one of "dh_1024_160", "dh_2048_224" or | |
1358 | "dh_2048_256" when generating a DH key. | |
1359 | ||
2fc02378 | 1360 | =item * |
04916913 RL |
1361 | |
1362 | DH_KDF_X9_42() | |
b7140b06 SL |
1363 | |
1364 | Applications should use L<EVP_PKEY_CTX_set_dh_kdf_type(3)> instead. | |
1365 | ||
2fc02378 | 1366 | =item * |
04916913 RL |
1367 | |
1368 | DH_get_default_method(), DH_get0_engine(), DH_meth_*(), DH_new_method(), | |
1369 | DH_OpenSSL(), DH_get_ex_data(), DH_set_default_method(), DH_set_method(), | |
1370 | DH_set_ex_data() | |
b7140b06 SL |
1371 | |
1372 | See L</Providers are a replacement for engines and low-level method overrides> | |
1373 | ||
2fc02378 | 1374 | =item * |
04916913 RL |
1375 | |
1376 | DHparams_print(), DHparams_print_fp() | |
b7140b06 SL |
1377 | |
1378 | See L</Deprecated low-level key printing functions> | |
1379 | ||
2fc02378 | 1380 | =item * |
04916913 RL |
1381 | |
1382 | DH_set0_key(), DH_set0_pqg(), DH_set_length() | |
b7140b06 SL |
1383 | |
1384 | See L</Deprecated low-level key parameter setters> | |
1385 | ||
2fc02378 | 1386 | =item * |
04916913 RL |
1387 | |
1388 | DSA_bits(), DSA_security_bits(), DSA_size() | |
b7140b06 | 1389 | |
ed576acd TM |
1390 | Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and |
1391 | L<EVP_PKEY_get_size(3)>. | |
b7140b06 | 1392 | |
2fc02378 | 1393 | =item * |
04916913 RL |
1394 | |
1395 | DHparams_dup(), DSA_dup_DH() | |
b7140b06 SL |
1396 | |
1397 | There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)> | |
1398 | and L<EVP_PKEY_dup(3)> instead. | |
1399 | ||
2fc02378 | 1400 | =item * |
04916913 RL |
1401 | |
1402 | DSA_generate_key(), DSA_generate_parameters_ex() | |
b7140b06 SL |
1403 | |
1404 | See L</Deprecated low-level key generation functions>. | |
1405 | ||
2fc02378 | 1406 | =item * |
04916913 RL |
1407 | |
1408 | DSA_get0_engine(), DSA_get_default_method(), DSA_get_ex_data(), | |
1409 | DSA_get_method(), DSA_meth_*(), DSA_new_method(), DSA_OpenSSL(), | |
1410 | DSA_set_default_method(), DSA_set_ex_data(), DSA_set_method() | |
b7140b06 SL |
1411 | |
1412 | See L</Providers are a replacement for engines and low-level method overrides>. | |
1413 | ||
2fc02378 | 1414 | =item * |
04916913 RL |
1415 | |
1416 | DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_pqg(), DSA_get0_key(), | |
1417 | DSA_get0_priv_key(), DSA_get0_pub_key() | |
b7140b06 SL |
1418 | |
1419 | See L</Deprecated low-level key parameter getters>. | |
1420 | ||
2fc02378 | 1421 | =item * |
04916913 RL |
1422 | |
1423 | DSA_new(), DSA_free(), DSA_up_ref() | |
b7140b06 SL |
1424 | |
1425 | See L</Deprecated low-level object creation> | |
1426 | ||
2fc02378 | 1427 | =item * |
04916913 RL |
1428 | |
1429 | DSAparams_dup() | |
b7140b06 SL |
1430 | |
1431 | There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)> | |
1432 | and L<EVP_PKEY_dup(3)> instead. | |
1433 | ||
2fc02378 | 1434 | =item * |
04916913 RL |
1435 | |
1436 | DSAparams_print(), DSAparams_print_fp(), DSA_print(), DSA_print_fp() | |
b7140b06 SL |
1437 | |
1438 | See L</Deprecated low-level key printing functions> | |
1439 | ||
2fc02378 | 1440 | =item * |
04916913 RL |
1441 | |
1442 | DSA_set0_key(), DSA_set0_pqg() | |
b7140b06 SL |
1443 | |
1444 | See L</Deprecated low-level key parameter setters> | |
1445 | ||
2fc02378 | 1446 | =item * |
04916913 RL |
1447 | |
1448 | DSA_set_flags(), DSA_clear_flags(), DSA_test_flags() | |
b7140b06 | 1449 | |
04916913 | 1450 | The B<DSA_FLAG_CACHE_MONT_P> flag has been deprecated without replacement. |
b7140b06 | 1451 | |
2fc02378 | 1452 | =item * |
04916913 RL |
1453 | |
1454 | DSA_sign(), DSA_do_sign(), DSA_sign_setup(), DSA_verify(), DSA_do_verify() | |
b7140b06 SL |
1455 | |
1456 | See L</Deprecated low-level signing functions>. | |
1457 | ||
2fc02378 | 1458 | =item * |
04916913 RL |
1459 | |
1460 | ECDH_compute_key() | |
b7140b06 SL |
1461 | |
1462 | See L</Deprecated low-level key exchange functions>. | |
1463 | ||
2fc02378 | 1464 | =item * |
04916913 RL |
1465 | |
1466 | ECDH_KDF_X9_62() | |
b7140b06 SL |
1467 | |
1468 | Applications may either set this using the helper function | |
318a9dfa | 1469 | L<EVP_PKEY_CTX_set_ecdh_kdf_type(3)> or by setting an L<OSSL_PARAM(3)> using the |
b7140b06 SL |
1470 | "kdf-type" as shown in L<EVP_KEYEXCH-ECDH(7)/EXAMPLES> |
1471 | ||
2fc02378 | 1472 | =item * |
04916913 RL |
1473 | |
1474 | ECDSA_sign(), ECDSA_sign_ex(), ECDSA_sign_setup(), ECDSA_do_sign(), | |
1475 | ECDSA_do_sign_ex(), ECDSA_verify(), ECDSA_do_verify() | |
b7140b06 SL |
1476 | |
1477 | See L</Deprecated low-level signing functions>. | |
1478 | ||
2fc02378 | 1479 | =item * |
04916913 RL |
1480 | |
1481 | ECDSA_size() | |
b7140b06 | 1482 | |
ed576acd | 1483 | Applications should use L<EVP_PKEY_get_size(3)>. |
b7140b06 | 1484 | |
2fc02378 | 1485 | =item * |
04916913 RL |
1486 | |
1487 | EC_GF2m_simple_method(), EC_GFp_mont_method(), EC_GFp_nist_method(), | |
1488 | EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(), | |
1489 | EC_GFp_simple_method() | |
b7140b06 SL |
1490 | |
1491 | There are no replacements for these functions. Applications should rely on the | |
1492 | library automatically assigning a suitable method internally when an EC_GROUP | |
1493 | is constructed. | |
1494 | ||
2fc02378 | 1495 | =item * |
04916913 RL |
1496 | |
1497 | EC_GROUP_clear_free() | |
b7140b06 SL |
1498 | |
1499 | Use L<EC_GROUP_free(3)> instead. | |
1500 | ||
2fc02378 | 1501 | =item * |
04916913 RL |
1502 | |
1503 | EC_GROUP_get_curve_GF2m(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(), | |
1504 | EC_GROUP_set_curve_GFp() | |
b7140b06 SL |
1505 | |
1506 | Applications should use L<EC_GROUP_get_curve(3)> and L<EC_GROUP_set_curve(3)>. | |
1507 | ||
2fc02378 | 1508 | =item * |
04916913 RL |
1509 | |
1510 | EC_GROUP_have_precompute_mult(), EC_GROUP_precompute_mult(), | |
1511 | EC_KEY_precompute_mult() | |
b7140b06 SL |
1512 | |
1513 | These functions are not widely used. Applications should instead switch to | |
1514 | named curves which OpenSSL has hardcoded lookup tables for. | |
1515 | ||
2fc02378 | 1516 | =item * |
04916913 RL |
1517 | |
1518 | EC_GROUP_new(), EC_GROUP_method_of(), EC_POINT_method_of() | |
b7140b06 SL |
1519 | |
1520 | EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned | |
1521 | internally without application intervention. | |
1522 | Users of EC_GROUP_new() should switch to a different suitable constructor. | |
1523 | ||
2fc02378 | 1524 | =item * |
04916913 RL |
1525 | |
1526 | EC_KEY_can_sign() | |
b7140b06 SL |
1527 | |
1528 | Applications should use L<EVP_PKEY_can_sign(3)> instead. | |
1529 | ||
2fc02378 | 1530 | =item * |
04916913 RL |
1531 | |
1532 | EC_KEY_check_key() | |
b7140b06 SL |
1533 | |
1534 | See L</Deprecated low-level validation functions> | |
1535 | ||
2fc02378 | 1536 | =item * |
04916913 RL |
1537 | |
1538 | EC_KEY_set_flags(), EC_KEY_get_flags(), EC_KEY_clear_flags() | |
b7140b06 | 1539 | |
e304aa87 | 1540 | See L<EVP_PKEY-EC(7)/Common EC parameters> which handles flags as separate |
b7140b06 SL |
1541 | parameters for B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>, |
1542 | B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>, B<OSSL_PKEY_PARAM_EC_ENCODING>, | |
57cd10dd | 1543 | B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> and |
b7140b06 SL |
1544 | B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>. |
1545 | See also L<EVP_PKEY-EC(7)/EXAMPLES> | |
1546 | ||
2fc02378 | 1547 | =item * |
04916913 RL |
1548 | |
1549 | EC_KEY_dup(), EC_KEY_copy() | |
b7140b06 SL |
1550 | |
1551 | There is no direct replacement. Applications may use L<EVP_PKEY_copy_parameters(3)> | |
1552 | and L<EVP_PKEY_dup(3)> instead. | |
1553 | ||
2fc02378 | 1554 | =item * |
04916913 RL |
1555 | |
1556 | EC_KEY_decoded_from_explicit_params() | |
b7140b06 SL |
1557 | |
1558 | There is no replacement. | |
1559 | ||
2fc02378 | 1560 | =item * |
04916913 RL |
1561 | |
1562 | EC_KEY_generate_key() | |
b7140b06 SL |
1563 | |
1564 | See L</Deprecated low-level key generation functions>. | |
1565 | ||
2fc02378 | 1566 | =item * |
04916913 RL |
1567 | |
1568 | EC_KEY_get0_group(), EC_KEY_get0_private_key(), EC_KEY_get0_public_key(), | |
1569 | EC_KEY_get_conv_form(), EC_KEY_get_enc_flags() | |
b7140b06 SL |
1570 | |
1571 | See L</Deprecated low-level key parameter getters>. | |
1572 | ||
2fc02378 | 1573 | =item * |
04916913 RL |
1574 | |
1575 | EC_KEY_get0_engine(), EC_KEY_get_default_method(), EC_KEY_get_method(), | |
1576 | EC_KEY_new_method(), EC_KEY_get_ex_data(), EC_KEY_OpenSSL(), | |
1577 | EC_KEY_set_ex_data(), EC_KEY_set_default_method(), EC_KEY_METHOD_*(), | |
1578 | EC_KEY_set_method() | |
b7140b06 SL |
1579 | |
1580 | See L</Providers are a replacement for engines and low-level method overrides> | |
1581 | ||
2fc02378 | 1582 | =item * |
04916913 RL |
1583 | |
1584 | EC_METHOD_get_field_type() | |
b7140b06 SL |
1585 | |
1586 | Use L<EC_GROUP_get_field_type(3)> instead. | |
1587 | See L</Providers are a replacement for engines and low-level method overrides> | |
1588 | ||
2fc02378 | 1589 | =item * |
04916913 RL |
1590 | |
1591 | EC_KEY_key2buf(), EC_KEY_oct2key(), EC_KEY_oct2priv(), EC_KEY_priv2buf(), | |
1592 | EC_KEY_priv2oct() | |
b7140b06 SL |
1593 | |
1594 | There are no replacements for these. | |
1595 | ||
2fc02378 | 1596 | =item * |
04916913 RL |
1597 | |
1598 | EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(), EC_KEY_up_ref() | |
b7140b06 SL |
1599 | |
1600 | See L</Deprecated low-level object creation> | |
1601 | ||
2fc02378 | 1602 | =item * |
04916913 RL |
1603 | |
1604 | EC_KEY_print(), EC_KEY_print_fp() | |
b7140b06 SL |
1605 | |
1606 | See L</Deprecated low-level key printing functions> | |
1607 | ||
2fc02378 | 1608 | =item * |
04916913 RL |
1609 | |
1610 | EC_KEY_set_asn1_flag(), EC_KEY_set_conv_form(), EC_KEY_set_enc_flags() | |
b7140b06 SL |
1611 | |
1612 | See L</Deprecated low-level key parameter setters>. | |
1613 | ||
2fc02378 | 1614 | =item * |
04916913 RL |
1615 | |
1616 | EC_KEY_set_group(), EC_KEY_set_private_key(), EC_KEY_set_public_key(), | |
1617 | EC_KEY_set_public_key_affine_coordinates() | |
b7140b06 SL |
1618 | |
1619 | See L</Deprecated low-level key parameter setters>. | |
1620 | ||
2fc02378 | 1621 | =item * |
04916913 RL |
1622 | |
1623 | ECParameters_print(), ECParameters_print_fp(), ECPKParameters_print(), | |
1624 | ECPKParameters_print_fp() | |
b7140b06 SL |
1625 | |
1626 | See L</Deprecated low-level key printing functions> | |
1627 | ||
2fc02378 | 1628 | =item * |
04916913 RL |
1629 | |
1630 | EC_POINT_bn2point(), EC_POINT_point2bn() | |
b7140b06 SL |
1631 | |
1632 | These functions were not particularly useful, since EC point serialization | |
1633 | formats are not individual big-endian integers. | |
1634 | ||
2fc02378 | 1635 | =item * |
04916913 RL |
1636 | |
1637 | EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GFp(), | |
1638 | EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_set_affine_coordinates_GFp() | |
b7140b06 SL |
1639 | |
1640 | Applications should use L<EC_POINT_get_affine_coordinates(3)> and | |
1641 | L<EC_POINT_set_affine_coordinates(3)> instead. | |
1642 | ||
2fc02378 | 1643 | =item * |
04916913 RL |
1644 | |
1645 | EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_Jprojective_coordinates_GFp() | |
b7140b06 SL |
1646 | |
1647 | These functions are not widely used. Applications should instead use the | |
1648 | L<EC_POINT_set_affine_coordinates(3)> and L<EC_POINT_get_affine_coordinates(3)> | |
1649 | functions. | |
1650 | ||
2fc02378 | 1651 | =item * |
04916913 RL |
1652 | |
1653 | EC_POINT_make_affine(), EC_POINTs_make_affine() | |
b7140b06 SL |
1654 | |
1655 | There is no replacement. These functions were not widely used, and OpenSSL | |
1656 | automatically performs this conversion when needed. | |
1657 | ||
2fc02378 | 1658 | =item * |
04916913 RL |
1659 | |
1660 | EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GFp() | |
b7140b06 SL |
1661 | |
1662 | Applications should use L<EC_POINT_set_compressed_coordinates(3)> instead. | |
1663 | ||
2fc02378 | 1664 | =item * |
04916913 RL |
1665 | |
1666 | EC_POINTs_mul() | |
b7140b06 SL |
1667 | |
1668 | This function is not widely used. Applications should instead use the | |
1669 | L<EC_POINT_mul(3)> function. | |
1670 | ||
2fc02378 | 1671 | =item * |
04916913 RL |
1672 | |
1673 | B<ENGINE_*()> | |
b7140b06 SL |
1674 | |
1675 | All engine functions are deprecated. An engine should be rewritten as a provider. | |
1676 | See L</Providers are a replacement for engines and low-level method overrides>. | |
1677 | ||
2fc02378 | 1678 | =item * |
04916913 RL |
1679 | |
1680 | B<ERR_load_*()>, ERR_func_error_string(), ERR_get_error_line(), | |
1681 | ERR_get_error_line_data(), ERR_get_state() | |
b7140b06 SL |
1682 | |
1683 | OpenSSL now loads error strings automatically so these functions are not needed. | |
1684 | ||
2fc02378 | 1685 | =item * |
04916913 RL |
1686 | |
1687 | ERR_peek_error_line_data(), ERR_peek_last_error_line_data() | |
b7140b06 SL |
1688 | |
1689 | The new functions are L<ERR_peek_error_func(3)>, L<ERR_peek_last_error_func(3)>, | |
1690 | L<ERR_peek_error_data(3)>, L<ERR_peek_last_error_data(3)>, L<ERR_get_error_all(3)>, | |
1691 | L<ERR_peek_error_all(3)> and L<ERR_peek_last_error_all(3)>. | |
1692 | Applications should use L<ERR_get_error_all(3)>, or pick information | |
1693 | with ERR_peek functions and finish off with getting the error code by using | |
1694 | L<ERR_get_error(3)>. | |
1695 | ||
2fc02378 | 1696 | =item * |
04916913 RL |
1697 | |
1698 | EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_iv_noconst(), EVP_CIPHER_CTX_original_iv() | |
b7140b06 SL |
1699 | |
1700 | Applications should instead use L<EVP_CIPHER_CTX_get_updated_iv(3)>, | |
1701 | L<EVP_CIPHER_CTX_get_updated_iv(3)> and L<EVP_CIPHER_CTX_get_original_iv(3)> | |
1702 | respectively. | |
1703 | See L<EVP_CIPHER_CTX_get_original_iv(3)> for further information. | |
1704 | ||
2fc02378 | 1705 | =item * |
04916913 RL |
1706 | |
1707 | B<EVP_CIPHER_meth_*()>, EVP_MD_CTX_set_update_fn(), EVP_MD_CTX_update_fn(), | |
1708 | B<EVP_MD_meth_*()> | |
b7140b06 SL |
1709 | |
1710 | See L</Providers are a replacement for engines and low-level method overrides>. | |
1711 | ||
2fc02378 | 1712 | =item * |
04916913 RL |
1713 | |
1714 | EVP_PKEY_CTRL_PKCS7_ENCRYPT(), EVP_PKEY_CTRL_PKCS7_DECRYPT(), | |
1715 | EVP_PKEY_CTRL_PKCS7_SIGN(), EVP_PKEY_CTRL_CMS_ENCRYPT(), | |
1716 | EVP_PKEY_CTRL_CMS_DECRYPT(), and EVP_PKEY_CTRL_CMS_SIGN() | |
b7140b06 SL |
1717 | |
1718 | These control operations are not invoked by the OpenSSL library anymore and | |
1719 | are replaced by direct checks of the key operation against the key type | |
1720 | when the operation is initialized. | |
1721 | ||
2fc02378 | 1722 | =item * |
04916913 RL |
1723 | |
1724 | EVP_PKEY_CTX_get0_dh_kdf_ukm(), EVP_PKEY_CTX_get0_ecdh_kdf_ukm() | |
b7140b06 SL |
1725 | |
1726 | See the "kdf-ukm" item in L<EVP_KEYEXCH-DH(7)/DH key exchange parameters> and | |
1727 | L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>. | |
1728 | These functions are obsolete and should not be required. | |
1729 | ||
2fc02378 | 1730 | =item * |
04916913 RL |
1731 | |
1732 | EVP_PKEY_CTX_set_rsa_keygen_pubexp() | |
b7140b06 SL |
1733 | |
1734 | Applications should use L<EVP_PKEY_CTX_set1_rsa_keygen_pubexp(3)> instead. | |
1735 | ||
2fc02378 | 1736 | =item * |
04916913 RL |
1737 | |
1738 | EVP_PKEY_cmp(), EVP_PKEY_cmp_parameters() | |
b7140b06 SL |
1739 | |
1740 | Applications should use L<EVP_PKEY_eq(3)> and L<EVP_PKEY_parameters_eq(3)> instead. | |
1741 | See L<EVP_PKEY_copy_parameters(3)> for further details. | |
1742 | ||
2fc02378 | 1743 | =item * |
04916913 | 1744 | |
57cd10dd | 1745 | EVP_PKEY_encrypt_old(), EVP_PKEY_decrypt_old(), |
b7140b06 SL |
1746 | |
1747 | Applications should use L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)> or | |
1748 | L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)> instead. | |
1749 | ||
2fc02378 | 1750 | =item * |
04916913 RL |
1751 | |
1752 | EVP_PKEY_get0() | |
b7140b06 SL |
1753 | |
1754 | This function returns NULL if the key comes from a provider. | |
1755 | ||
2fc02378 | 1756 | =item * |
04916913 RL |
1757 | |
1758 | EVP_PKEY_get0_DH(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_RSA(), | |
1759 | EVP_PKEY_get1_DH(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_EC_KEY and EVP_PKEY_get1_RSA(), | |
1760 | EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash() | |
b7140b06 SL |
1761 | |
1762 | See L</Functions that return an internal key should be treated as read only>. | |
1763 | ||
2fc02378 | 1764 | =item * |
04916913 RL |
1765 | |
1766 | B<EVP_PKEY_meth_*()> | |
b7140b06 SL |
1767 | |
1768 | See L</Providers are a replacement for engines and low-level method overrides>. | |
1769 | ||
2fc02378 | 1770 | =item * |
04916913 RL |
1771 | |
1772 | EVP_PKEY_new_CMAC_key() | |
b7140b06 SL |
1773 | |
1774 | See L</Deprecated low-level MAC functions>. | |
1775 | ||
2fc02378 | 1776 | =item * |
04916913 RL |
1777 | |
1778 | EVP_PKEY_assign(), EVP_PKEY_set1_DH(), EVP_PKEY_set1_DSA(), | |
1779 | EVP_PKEY_set1_EC_KEY(), EVP_PKEY_set1_RSA() | |
b7140b06 SL |
1780 | |
1781 | See L</Deprecated low-level key object getters and setters> | |
1782 | ||
2fc02378 | 1783 | =item * |
04916913 RL |
1784 | |
1785 | EVP_PKEY_set1_tls_encodedpoint() EVP_PKEY_get1_tls_encodedpoint() | |
b7140b06 SL |
1786 | |
1787 | These functions were previously used by libssl to set or get an encoded public | |
1788 | key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more | |
1789 | generic functions L<EVP_PKEY_set1_encoded_public_key(3)> and | |
1790 | L<EVP_PKEY_get1_encoded_public_key(3)>. | |
1791 | The old versions have been converted to deprecated macros that just call the | |
1792 | new functions. | |
1793 | ||
2fc02378 | 1794 | =item * |
04916913 RL |
1795 | |
1796 | EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine() | |
b7140b06 SL |
1797 | |
1798 | See L</Providers are a replacement for engines and low-level method overrides>. | |
1799 | ||
2fc02378 | 1800 | =item * |
04916913 RL |
1801 | |
1802 | EVP_PKEY_set_alias_type() | |
b7140b06 SL |
1803 | |
1804 | This function has been removed. There is no replacement. | |
1805 | See L</EVP_PKEY_set_alias_type() method has been removed> | |
1806 | ||
2fc02378 | 1807 | =item * |
04916913 RL |
1808 | |
1809 | HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), HMAC_size() | |
b7140b06 SL |
1810 | |
1811 | See L</Deprecated low-level MAC functions>. | |
1812 | ||
2fc02378 | 1813 | =item * |
04916913 RL |
1814 | |
1815 | HMAC_CTX_new(), HMAC_CTX_free(), HMAC_CTX_copy(), HMAC_CTX_reset(), | |
1816 | HMAC_CTX_set_flags(), HMAC_CTX_get_md() | |
b7140b06 SL |
1817 | |
1818 | See L</Deprecated low-level MAC functions>. | |
1819 | ||
2fc02378 | 1820 | =item * |
04916913 RL |
1821 | |
1822 | i2d_DHparams(), i2d_DHxparams() | |
b7140b06 SL |
1823 | |
1824 | See L</Deprecated low-level key reading and writing functions> | |
57cd10dd | 1825 | and L<d2i_RSAPrivateKey(3)/Migration> |
b7140b06 | 1826 | |
2fc02378 | 1827 | =item * |
04916913 RL |
1828 | |
1829 | i2d_DSAparams(), i2d_DSAPrivateKey(), i2d_DSAPrivateKey_bio(), | |
1830 | i2d_DSAPrivateKey_fp(), i2d_DSA_PUBKEY(), i2d_DSA_PUBKEY_bio(), | |
1831 | i2d_DSA_PUBKEY_fp(), i2d_DSAPublicKey() | |
b7140b06 SL |
1832 | |
1833 | See L</Deprecated low-level key reading and writing functions> | |
57cd10dd | 1834 | and L<d2i_RSAPrivateKey(3)/Migration> |
b7140b06 | 1835 | |
2fc02378 | 1836 | =item * |
04916913 RL |
1837 | |
1838 | i2d_ECParameters(), i2d_ECPrivateKey(), i2d_ECPrivateKey_bio(), | |
1839 | i2d_ECPrivateKey_fp(), i2d_EC_PUBKEY(), i2d_EC_PUBKEY_bio(), | |
1840 | i2d_EC_PUBKEY_fp(), i2o_ECPublicKey() | |
b7140b06 SL |
1841 | |
1842 | See L</Deprecated low-level key reading and writing functions> | |
57cd10dd | 1843 | and L<d2i_RSAPrivateKey(3)/Migration> |
b7140b06 | 1844 | |
2fc02378 | 1845 | =item * |
04916913 RL |
1846 | |
1847 | i2d_RSAPrivateKey(), i2d_RSAPrivateKey_bio(), i2d_RSAPrivateKey_fp(), | |
1848 | i2d_RSA_PUBKEY(), i2d_RSA_PUBKEY_bio(), i2d_RSA_PUBKEY_fp(), | |
1849 | i2d_RSAPublicKey(), i2d_RSAPublicKey_bio(), i2d_RSAPublicKey_fp() | |
b7140b06 SL |
1850 | |
1851 | See L</Deprecated low-level key reading and writing functions> | |
57cd10dd | 1852 | and L<d2i_RSAPrivateKey(3)/Migration> |
b7140b06 | 1853 | |
2fc02378 | 1854 | =item * |
04916913 RL |
1855 | |
1856 | IDEA_encrypt(), IDEA_set_decrypt_key(), IDEA_set_encrypt_key(), | |
1857 | IDEA_cbc_encrypt(), IDEA_cfb64_encrypt(), IDEA_ecb_encrypt(), | |
1858 | IDEA_ofb64_encrypt() | |
b7140b06 SL |
1859 | |
1860 | See L</Deprecated low-level encryption functions>. | |
1861 | IDEA has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
1862 | ||
2fc02378 | 1863 | =item * |
04916913 RL |
1864 | |
1865 | IDEA_options() | |
b7140b06 SL |
1866 | |
1867 | There is no replacement. This function returned a constant string. | |
1868 | ||
2fc02378 | 1869 | =item * |
04916913 RL |
1870 | |
1871 | MD2(), MD2_Init(), MD2_Update(), MD2_Final() | |
b7140b06 SL |
1872 | |
1873 | See L</Deprecated low-level encryption functions>. | |
1874 | MD2 has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
1875 | ||
2fc02378 | 1876 | =item * |
04916913 RL |
1877 | |
1878 | MD2_options() | |
b7140b06 SL |
1879 | |
1880 | There is no replacement. This function returned a constant string. | |
1881 | ||
2fc02378 | 1882 | =item * |
04916913 RL |
1883 | |
1884 | MD4(), MD4_Init(), MD4_Update(), MD4_Final(), MD4_Transform() | |
b7140b06 SL |
1885 | |
1886 | See L</Deprecated low-level encryption functions>. | |
1887 | MD4 has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
1888 | ||
2fc02378 | 1889 | =item * |
04916913 RL |
1890 | |
1891 | MDC2(), MDC2_Init(), MDC2_Update(), MDC2_Final() | |
b7140b06 SL |
1892 | |
1893 | See L</Deprecated low-level encryption functions>. | |
1894 | MDC2 has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
1895 | ||
2fc02378 | 1896 | =item * |
04916913 RL |
1897 | |
1898 | MD5(), MD5_Init(), MD5_Update(), MD5_Final(), MD5_Transform() | |
b7140b06 SL |
1899 | |
1900 | See L</Deprecated low-level encryption functions>. | |
1901 | ||
2fc02378 | 1902 | =item * |
04916913 RL |
1903 | |
1904 | NCONF_WIN32() | |
b7140b06 SL |
1905 | |
1906 | This undocumented function has no replacement. | |
1907 | See L<config(5)/HISTORY> for more details. | |
1908 | ||
2fc02378 | 1909 | =item * |
04916913 RL |
1910 | |
1911 | OCSP_parse_url() | |
b7140b06 SL |
1912 | |
1913 | Use L<OSSL_HTTP_parse_url(3)> instead. | |
1914 | ||
2fc02378 | 1915 | =item * |
04916913 RL |
1916 | |
1917 | B<OCSP_REQ_CTX> type and B<OCSP_REQ_CTX_*()> functions | |
b7140b06 SL |
1918 | |
1919 | These methods were used to collect all necessary data to form a HTTP request, | |
1920 | and to perform the HTTP transfer with that request. With OpenSSL 3.0, the | |
04916913 RL |
1921 | type is B<OSSL_HTTP_REQ_CTX>, and the deprecated functions are replaced |
1922 | with B<OSSL_HTTP_REQ_CTX_*()>. See L<OSSL_HTTP_REQ_CTX(3)> for additional | |
1923 | details. | |
b7140b06 | 1924 | |
2fc02378 | 1925 | =item * |
04916913 RL |
1926 | |
1927 | OPENSSL_fork_child(), OPENSSL_fork_parent(), OPENSSL_fork_prepare() | |
b7140b06 SL |
1928 | |
1929 | There is no replacement for these functions. These pthread fork support methods | |
1930 | were unused by OpenSSL. | |
1931 | ||
2fc02378 | 1932 | =item * |
04916913 RL |
1933 | |
1934 | OSSL_STORE_ctrl(), OSSL_STORE_do_all_loaders(), OSSL_STORE_LOADER_get0_engine(), | |
1935 | OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_new(), | |
1936 | OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_close(), | |
1937 | OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_eof(), | |
1938 | OSSL_STORE_LOADER_set_error(), OSSL_STORE_LOADER_set_expect(), | |
1939 | OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_load(), | |
1940 | OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(), | |
1941 | OSSL_STORE_register_loader(), OSSL_STORE_unregister_loader(), | |
1942 | OSSL_STORE_vctrl() | |
b7140b06 SL |
1943 | |
1944 | These functions helped applications and engines create loaders for | |
1945 | schemes they supported. These are all deprecated and discouraged in favour of | |
1946 | provider implementations, see L<provider-storemgmt(7)>. | |
1947 | ||
2fc02378 | 1948 | =item * |
04916913 RL |
1949 | |
1950 | PEM_read_DHparams(), PEM_read_bio_DHparams(), | |
1951 | PEM_read_DSAparams(), PEM_read_bio_DSAparams(), | |
1952 | PEM_read_DSAPrivateKey(), PEM_read_DSA_PUBKEY(), | |
1953 | PEM_read_bio_DSAPrivateKey and PEM_read_bio_DSA_PUBKEY(), | |
1954 | PEM_read_ECPKParameters(), PEM_read_ECPrivateKey(), PEM_read_EC_PUBKEY(), | |
1955 | PEM_read_bio_ECPKParameters(), PEM_read_bio_ECPrivateKey(), PEM_read_bio_EC_PUBKEY(), | |
1956 | PEM_read_RSAPrivateKey(), PEM_read_RSA_PUBKEY(), PEM_read_RSAPublicKey(), | |
1957 | PEM_read_bio_RSAPrivateKey(), PEM_read_bio_RSA_PUBKEY(), PEM_read_bio_RSAPublicKey(), | |
1958 | PEM_write_bio_DHparams(), PEM_write_bio_DHxparams(), PEM_write_DHparams(), PEM_write_DHxparams(), | |
1959 | PEM_write_DSAparams(), PEM_write_DSAPrivateKey(), PEM_write_DSA_PUBKEY(), | |
1960 | PEM_write_bio_DSAparams(), PEM_write_bio_DSAPrivateKey(), PEM_write_bio_DSA_PUBKEY(), | |
1961 | PEM_write_ECPKParameters(), PEM_write_ECPrivateKey(), PEM_write_EC_PUBKEY(), | |
1962 | PEM_write_bio_ECPKParameters(), PEM_write_bio_ECPrivateKey(), PEM_write_bio_EC_PUBKEY(), | |
1963 | PEM_write_RSAPrivateKey(), PEM_write_RSA_PUBKEY(), PEM_write_RSAPublicKey(), | |
1964 | PEM_write_bio_RSAPrivateKey(), PEM_write_bio_RSA_PUBKEY(), | |
1965 | PEM_write_bio_RSAPublicKey(), | |
b7140b06 SL |
1966 | |
1967 | See L</Deprecated low-level key reading and writing functions> | |
1968 | ||
2fc02378 | 1969 | =item * |
04916913 RL |
1970 | |
1971 | PKCS1_MGF1() | |
b7140b06 SL |
1972 | |
1973 | See L</Deprecated low-level encryption functions>. | |
1974 | ||
2fc02378 | 1975 | =item * |
04916913 RL |
1976 | |
1977 | RAND_get_rand_method(), RAND_set_rand_method(), RAND_OpenSSL(), | |
1978 | RAND_set_rand_engine() | |
b7140b06 SL |
1979 | |
1980 | Applications should instead use L<RAND_set_DRBG_type(3)>, | |
1981 | L<EVP_RAND(3)> and L<EVP_RAND(7)>. | |
1982 | See L<RAND_set_rand_method(3)> for more details. | |
1983 | ||
2fc02378 | 1984 | =item * |
04916913 RL |
1985 | |
1986 | RC2_encrypt(), RC2_decrypt(), RC2_set_key(), RC2_cbc_encrypt(), RC2_cfb64_encrypt(), | |
1987 | RC2_ecb_encrypt(), RC2_ofb64_encrypt(), | |
1988 | RC4(), RC4_set_key(), RC4_options(), | |
1989 | RC5_32_encrypt(), RC5_32_set_key(), RC5_32_decrypt(), RC5_32_cbc_encrypt(), | |
1990 | RC5_32_cfb64_encrypt(), RC5_32_ecb_encrypt(), RC5_32_ofb64_encrypt() | |
b7140b06 SL |
1991 | |
1992 | See L</Deprecated low-level encryption functions>. | |
1993 | The Algorithms "RC2", "RC4" and "RC5" have been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
1994 | ||
2fc02378 | 1995 | =item * |
04916913 RL |
1996 | |
1997 | RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update(), RIPEMD160_Final(), | |
1998 | RIPEMD160_Transform() | |
b7140b06 SL |
1999 | |
2000 | See L</Deprecated low-level digest functions>. | |
2001 | The RIPE algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
2002 | ||
2fc02378 | 2003 | =item * |
04916913 RL |
2004 | |
2005 | RSA_bits(), RSA_security_bits(), RSA_size() | |
b7140b06 | 2006 | |
ed576acd TM |
2007 | Use L<EVP_PKEY_get_bits(3)>, L<EVP_PKEY_get_security_bits(3)> and |
2008 | L<EVP_PKEY_get_size(3)>. | |
b7140b06 | 2009 | |
2fc02378 | 2010 | =item * |
04916913 RL |
2011 | |
2012 | RSA_check_key(), RSA_check_key_ex() | |
b7140b06 SL |
2013 | |
2014 | See L</Deprecated low-level validation functions> | |
2015 | ||
2fc02378 | 2016 | =item * |
04916913 RL |
2017 | |
2018 | RSA_clear_flags(), RSA_flags(), RSA_set_flags(), RSA_test_flags(), | |
2019 | RSA_setup_blinding(), RSA_blinding_off(), RSA_blinding_on() | |
b7140b06 SL |
2020 | |
2021 | All of these RSA flags have been deprecated without replacement: | |
2022 | ||
04916913 RL |
2023 | B<RSA_FLAG_BLINDING>, B<RSA_FLAG_CACHE_PRIVATE>, B<RSA_FLAG_CACHE_PUBLIC>, |
2024 | B<RSA_FLAG_EXT_PKEY>, B<RSA_FLAG_NO_BLINDING>, B<RSA_FLAG_THREAD_SAFE> | |
2025 | B<RSA_METHOD_FLAG_NO_CHECK> | |
b7140b06 | 2026 | |
2fc02378 | 2027 | =item * |
04916913 RL |
2028 | |
2029 | RSA_generate_key_ex(), RSA_generate_multi_prime_key() | |
b7140b06 SL |
2030 | |
2031 | See L</Deprecated low-level key generation functions>. | |
2032 | ||
2fc02378 | 2033 | =item * |
04916913 RL |
2034 | |
2035 | RSA_get0_engine() | |
b7140b06 SL |
2036 | |
2037 | See L</Providers are a replacement for engines and low-level method overrides> | |
2038 | ||
2fc02378 | 2039 | =item * |
04916913 RL |
2040 | |
2041 | RSA_get0_crt_params(), RSA_get0_d(), RSA_get0_dmp1(), RSA_get0_dmq1(), | |
2042 | RSA_get0_e(), RSA_get0_factors(), RSA_get0_iqmp(), RSA_get0_key(), | |
2043 | RSA_get0_multi_prime_crt_params(), RSA_get0_multi_prime_factors(), RSA_get0_n(), | |
2044 | RSA_get0_p(), RSA_get0_pss_params(), RSA_get0_q(), | |
2045 | RSA_get_multi_prime_extra_count() | |
b7140b06 SL |
2046 | |
2047 | See L</Deprecated low-level key parameter getters> | |
2048 | ||
2fc02378 | 2049 | =item * |
04916913 RL |
2050 | |
2051 | RSA_new(), RSA_free(), RSA_up_ref() | |
b7140b06 SL |
2052 | |
2053 | See L</Deprecated low-level object creation>. | |
2054 | ||
2fc02378 | 2055 | =item * |
04916913 RL |
2056 | |
2057 | RSA_get_default_method(), RSA_get_ex_data and RSA_get_method() | |
b7140b06 SL |
2058 | |
2059 | See L</Providers are a replacement for engines and low-level method overrides>. | |
2060 | ||
2fc02378 | 2061 | =item * |
04916913 RL |
2062 | |
2063 | RSA_get_version() | |
b7140b06 SL |
2064 | |
2065 | There is no replacement. | |
2066 | ||
2fc02378 | 2067 | =item * |
04916913 RL |
2068 | |
2069 | B<RSA_meth_*()>, RSA_new_method(), RSA_null_method and RSA_PKCS1_OpenSSL() | |
b7140b06 SL |
2070 | |
2071 | See L</Providers are a replacement for engines and low-level method overrides>. | |
2072 | ||
2fc02378 | 2073 | =item * |
04916913 RL |
2074 | |
2075 | B<RSA_padding_add_*()>, B<RSA_padding_check_*()> | |
b7140b06 SL |
2076 | |
2077 | See L</Deprecated low-level signing functions> and | |
2078 | L</Deprecated low-level encryption functions>. | |
2079 | ||
2fc02378 | 2080 | =item * |
04916913 RL |
2081 | |
2082 | RSA_print(), RSA_print_fp() | |
b7140b06 SL |
2083 | |
2084 | See L</Deprecated low-level key printing functions> | |
2085 | ||
2fc02378 | 2086 | =item * |
04916913 RL |
2087 | |
2088 | RSA_public_encrypt(), RSA_private_decrypt() | |
b7140b06 SL |
2089 | |
2090 | See L</Deprecated low-level encryption functions> | |
2091 | ||
2fc02378 | 2092 | =item * |
04916913 RL |
2093 | |
2094 | RSA_private_encrypt(), RSA_public_decrypt() | |
b7140b06 | 2095 | |
e0ad156d TM |
2096 | This is equivalent to doing sign and verify recover operations (with a padding |
2097 | mode of none). See L</Deprecated low-level signing functions>. | |
b7140b06 | 2098 | |
2fc02378 | 2099 | =item * |
04916913 RL |
2100 | |
2101 | RSAPrivateKey_dup(), RSAPublicKey_dup() | |
b7140b06 SL |
2102 | |
2103 | There is no direct replacement. Applications may use L<EVP_PKEY_dup(3)>. | |
2104 | ||
2fc02378 | 2105 | =item * |
04916913 RL |
2106 | |
2107 | RSAPublicKey_it(), RSAPrivateKey_it() | |
b7140b06 SL |
2108 | |
2109 | See L</Deprecated low-level key reading and writing functions> | |
2110 | ||
2fc02378 | 2111 | =item * |
04916913 RL |
2112 | |
2113 | RSA_set0_crt_params(), RSA_set0_factors(), RSA_set0_key(), | |
2114 | RSA_set0_multi_prime_params() | |
b7140b06 SL |
2115 | |
2116 | See L</Deprecated low-level key parameter setters>. | |
2117 | ||
2fc02378 | 2118 | =item * |
04916913 RL |
2119 | |
2120 | RSA_set_default_method(), RSA_set_method(), RSA_set_ex_data() | |
b7140b06 SL |
2121 | |
2122 | See L</Providers are a replacement for engines and low-level method overrides> | |
2123 | ||
2fc02378 | 2124 | =item * |
04916913 RL |
2125 | |
2126 | RSA_sign(), RSA_sign_ASN1_OCTET_STRING(), RSA_verify(), | |
2127 | RSA_verify_ASN1_OCTET_STRING(), RSA_verify_PKCS1_PSS(), | |
2128 | RSA_verify_PKCS1_PSS_mgf1() | |
b7140b06 SL |
2129 | |
2130 | See L</Deprecated low-level signing functions>. | |
2131 | ||
2fc02378 | 2132 | =item * |
04916913 RL |
2133 | |
2134 | RSA_X931_derive_ex(), RSA_X931_generate_key_ex(), RSA_X931_hash_id() | |
b7140b06 SL |
2135 | |
2136 | There are no replacements for these functions. | |
2137 | X931 padding can be set using L<EVP_SIGNATURE-RSA(7)/Signature Parameters>. | |
2138 | See B<OSSL_SIGNATURE_PARAM_PAD_MODE>. | |
2139 | ||
2fc02378 | 2140 | =item * |
04916913 RL |
2141 | |
2142 | SEED_encrypt(), SEED_decrypt(), SEED_set_key(), SEED_cbc_encrypt(), | |
2143 | SEED_cfb128_encrypt(), SEED_ecb_encrypt(), SEED_ofb128_encrypt() | |
b7140b06 SL |
2144 | |
2145 | See L</Deprecated low-level encryption functions>. | |
2146 | The SEED algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
2147 | ||
2fc02378 | 2148 | =item * |
04916913 RL |
2149 | |
2150 | SHA1_Init(), SHA1_Update(), SHA1_Final(), SHA1_Transform(), | |
2151 | SHA224_Init(), SHA224_Update(), SHA224_Final(), | |
2152 | SHA256_Init(), SHA256_Update(), SHA256_Final(), SHA256_Transform(), | |
2153 | SHA384_Init(), SHA384_Update(), SHA384_Final(), | |
2154 | SHA512_Init(), SHA512_Update(), SHA512_Final(), SHA512_Transform() | |
b7140b06 SL |
2155 | |
2156 | See L</Deprecated low-level digest functions>. | |
2157 | ||
2fc02378 | 2158 | =item * |
04916913 RL |
2159 | |
2160 | SRP_Calc_A(), SRP_Calc_B(), SRP_Calc_client_key(), SRP_Calc_server_key(), | |
2161 | SRP_Calc_u(), SRP_Calc_x(), SRP_check_known_gN_param(), SRP_create_verifier(), | |
2162 | SRP_create_verifier_BN(), SRP_get_default_gN(), SRP_user_pwd_free(), SRP_user_pwd_new(), | |
2163 | SRP_user_pwd_set0_sv(), SRP_user_pwd_set1_ids(), SRP_user_pwd_set_gN(), | |
2164 | SRP_VBASE_add0_user(), SRP_VBASE_free(), SRP_VBASE_get1_by_user(), SRP_VBASE_init(), | |
2165 | SRP_VBASE_new(), SRP_Verify_A_mod_N(), SRP_Verify_B_mod_N() | |
b7140b06 SL |
2166 | |
2167 | There are no replacements for the SRP functions. | |
2168 | ||
2fc02378 | 2169 | =item * |
04916913 RL |
2170 | |
2171 | SSL_CTX_set_tmp_dh_callback(), SSL_set_tmp_dh_callback(), | |
2172 | SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh() | |
b7140b06 SL |
2173 | |
2174 | These are used to set the Diffie-Hellman (DH) parameters that are to be used by | |
2175 | servers requiring ephemeral DH keys. Instead applications should consider using | |
2176 | the built-in DH parameters that are available by calling L<SSL_CTX_set_dh_auto(3)> | |
2177 | or L<SSL_set_dh_auto(3)>. If custom parameters are necessary then applications can | |
2178 | use the alternative functions L<SSL_CTX_set0_tmp_dh_pkey(3)> and | |
2179 | L<SSL_set0_tmp_dh_pkey(3)>. There is no direct replacement for the "callback" | |
2180 | functions. The callback was originally useful in order to have different | |
2181 | parameters for export and non-export ciphersuites. Export ciphersuites are no | |
2182 | longer supported by OpenSSL. Use of the callback functions should be replaced | |
2183 | by one of the other methods described above. | |
2184 | ||
2fc02378 | 2185 | =item * |
04916913 RL |
2186 | |
2187 | SSL_CTX_set_tlsext_ticket_key_cb() | |
b7140b06 SL |
2188 | |
2189 | Use the new L<SSL_CTX_set_tlsext_ticket_key_evp_cb(3)> function instead. | |
2190 | ||
2fc02378 | 2191 | =item * |
04916913 RL |
2192 | |
2193 | WHIRLPOOL(), WHIRLPOOL_Init(), WHIRLPOOL_Update(), WHIRLPOOL_Final(), | |
2194 | WHIRLPOOL_BitUpdate() | |
b7140b06 SL |
2195 | |
2196 | See L</Deprecated low-level digest functions>. | |
2197 | The Whirlpool algorithm has been moved to the L<Legacy Provider|/Legacy Algorithms>. | |
2198 | ||
2fc02378 | 2199 | =item * |
04916913 RL |
2200 | |
2201 | X509_certificate_type() | |
b7140b06 SL |
2202 | |
2203 | This was an undocumented function. Applications can use L<X509_get0_pubkey(3)> | |
2204 | and L<X509_get0_signature(3)> instead. | |
2205 | ||
2fc02378 | 2206 | =item * |
04916913 RL |
2207 | |
2208 | X509_http_nbio(), X509_CRL_http_nbio() | |
b7140b06 SL |
2209 | |
2210 | Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead. | |
2211 | ||
2212 | =back | |
2213 | ||
2214 | =head2 Using the FIPS Module in applications | |
2215 | ||
2216 | See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details. | |
2217 | ||
2218 | =head2 OpenSSL command line application changes | |
2219 | ||
2220 | =head3 New applications | |
2221 | ||
04916913 RL |
2222 | L<B<openssl kdf>|openssl-kdf(1)> uses the new L<EVP_KDF(3)> API. |
2223 | L<B<openssl kdf>|openssl-mac(1)> uses the new L<EVP_MAC(3)> API. | |
b7140b06 SL |
2224 | |
2225 | =head3 Added options | |
2226 | ||
04916913 RL |
2227 | B<-provider_path> and B<-provider> are available to all apps and can be used |
2228 | multiple times to load any providers, such as the 'legacy' provider or third | |
2229 | party providers. If used then the 'default' provider would also need to be | |
2230 | specified if required. The B<-provider_path> must be specified before the | |
57cd10dd | 2231 | B<-provider> option. |
b7140b06 | 2232 | |
04916913 RL |
2233 | The B<list> app has many new options. See L<openssl-list(1)> for more |
2234 | information. | |
b7140b06 | 2235 | |
04916913 RL |
2236 | B<-crl_lastupdate> and B<-crl_nextupdate> used by B<openssl ca> allows |
2237 | explicit setting of fields in the generated CRL. | |
b7140b06 SL |
2238 | |
2239 | =head3 Removed options | |
2240 | ||
2241 | Interactive mode is not longer available. | |
2242 | ||
04916913 RL |
2243 | The B<-crypt> option used by B<openssl passwd>. |
2244 | The B<-c> option used by B<openssl x509>, B<openssl dhparam>, | |
2245 | B<openssl dsaparam>, and B<openssl ecparam>. | |
b7140b06 SL |
2246 | |
2247 | =head3 Other Changes | |
2248 | ||
2249 | The output of Command line applications may have minor changes. | |
2250 | These are primarily changes in capitalisation and white space. However, in some | |
2251 | cases, there are additional differences. | |
04916913 RL |
2252 | For example, the DH parameters output from B<openssl dhparam> now lists 'P', |
2253 | 'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and | |
2254 | 'counter' respectively. | |
b7140b06 | 2255 | |
04916913 | 2256 | The B<openssl> commands that read keys, certificates, and CRLs now |
b7140b06 SL |
2257 | automatically detect the PEM or DER format of the input files so it is not |
2258 | necessary to explicitly specify the input format anymore. However if the | |
2259 | input format option is used the specified format will be required. | |
2260 | ||
04916913 | 2261 | B<openssl speed> no longer uses low-level API calls. |
b7140b06 SL |
2262 | This implies some of the performance numbers might not be comparable with the |
2263 | previous releases due to higher overhead. This applies particularly to | |
2264 | measuring performance on smaller data chunks. | |
2265 | ||
04916913 RL |
2266 | b<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>, |
2267 | B<openssl genrsa> and B<openssl rsa> have been modified to use PKEY APIs. | |
2268 | B<openssl genrsa> and B<openssl rsa> now write PKCS #8 keys by default. | |
b7140b06 SL |
2269 | |
2270 | =head3 Default settings | |
2271 | ||
04916913 | 2272 | "SHA256" is now the default digest for TS query used by B<openssl ts>. |
b7140b06 SL |
2273 | |
2274 | =head3 Deprecated apps | |
2275 | ||
04916913 RL |
2276 | B<openssl rsautl> is deprecated, use B<openssl pkeyutl> instead. |
2277 | B<openssl dhparam>, B<openssl dsa>, B<openssl gendsa>, B<openssl dsaparam>, | |
2278 | B<openssl genrsa>, B<openssl rsa>, B<openssl genrsa> and B<openssl rsa> are | |
b7140b06 SL |
2279 | now in maintenance mode and no new features will be added to them. |
2280 | ||
2281 | =head2 TLS Changes | |
2282 | ||
2283 | =over 4 | |
2284 | ||
2fc02378 | 2285 | =item * |
04916913 RL |
2286 | |
2287 | TLS 1.3 FFDHE key exchange support added | |
b7140b06 SL |
2288 | |
2289 | This uses DH safe prime named groups. | |
2290 | ||
2fc02378 | 2291 | =item * |
04916913 RL |
2292 | |
2293 | Support for fully "pluggable" TLSv1.3 groups. | |
b7140b06 SL |
2294 | |
2295 | This means that providers may supply their own group implementations (using | |
2296 | either the "key exchange" or the "key encapsulation" methods) which will | |
2297 | automatically be detected and used by libssl. | |
2298 | ||
2fc02378 | 2299 | =item * |
04916913 RL |
2300 | |
2301 | SSL and SSL_CTX options are now 64 bit instead of 32 bit. | |
b7140b06 SL |
2302 | |
2303 | The signatures of the functions to get and set options on SSL and | |
2304 | SSL_CTX objects changed from "unsigned long" to "uint64_t" type. | |
2305 | ||
24f84b4e TM |
2306 | This may require source code changes. For example it is no longer possible |
2307 | to use the B<SSL_OP_> macro values in preprocessor C<#if> conditions. | |
2308 | However it is still possible to test whether these macros are defined or not. | |
b7140b06 SL |
2309 | |
2310 | See L<SSL_CTX_get_options(3)>, L<SSL_CTX_set_options(3)>, | |
2311 | L<SSL_get_options(3)> and L<SSL_set_options(3)>. | |
2312 | ||
2fc02378 | 2313 | =item * |
04916913 RL |
2314 | |
2315 | SSL_set1_host() and SSL_add1_host() Changes | |
b7140b06 SL |
2316 | |
2317 | These functions now take IP literal addresses as well as actual hostnames. | |
2318 | ||
2fc02378 | 2319 | =item * |
04916913 RL |
2320 | |
2321 | Added SSL option SSL_OP_CLEANSE_PLAINTEXT | |
b7140b06 SL |
2322 | |
2323 | If the option is set, openssl cleanses (zeroizes) plaintext bytes from | |
2324 | internal buffers after delivering them to the application. Note, | |
2325 | the application is still responsible for cleansing other copies | |
2326 | (e.g.: data received by L<SSL_read(3)>). | |
2327 | ||
2fc02378 | 2328 | =item * |
04916913 RL |
2329 | |
2330 | Client-initiated renegotiation is disabled by default. | |
b7140b06 | 2331 | |
04916913 RL |
2332 | To allow it, use the B<-client_renegotiation> option, |
2333 | the B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION> flag, or the C<ClientRenegotiation> | |
b7140b06 SL |
2334 | config parameter as appropriate. |
2335 | ||
2fc02378 | 2336 | =item * |
04916913 RL |
2337 | |
2338 | Secure renegotiation is now required by default for TLS connections | |
b7140b06 SL |
2339 | |
2340 | Support for RFC 5746 secure renegotiation is now required by default for | |
2341 | SSL or TLS connections to succeed. Applications that require the ability | |
2342 | to connect to legacy peers will need to explicitly set | |
2343 | SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT | |
2344 | is no longer set as part of SSL_OP_ALL. | |
2345 | ||
2fc02378 | 2346 | =item * |
04916913 RL |
2347 | |
2348 | Combining the Configure options no-ec and no-dh no longer disables TLSv1.3 | |
b7140b06 SL |
2349 | |
2350 | Typically if OpenSSL has no EC or DH algorithms then it cannot support | |
2351 | connections with TLSv1.3. However OpenSSL now supports "pluggable" groups | |
2352 | through providers. Therefore third party providers may supply group | |
2353 | implementations even where there are no built-in ones. Attempting to create | |
2354 | TLS connections in such a build without also disabling TLSv1.3 at run time or | |
2355 | using third party provider groups may result in handshake failures. TLSv1.3 | |
2356 | can be disabled at compile time using the "no-tls1_3" Configure option. | |
2357 | ||
2fc02378 | 2358 | =item * |
04916913 RL |
2359 | |
2360 | SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() changes. | |
b7140b06 SL |
2361 | |
2362 | The methods now ignore unknown ciphers. | |
2363 | ||
2fc02378 | 2364 | =item * |
04916913 RL |
2365 | |
2366 | Security callback change. | |
b7140b06 SL |
2367 | |
2368 | The security callback, which can be customised by application code, supports | |
2369 | the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY | |
2370 | in the "other" parameter. In most places this is what is passed. All these | |
2371 | places occur server side. However there was one client side call of this | |
2372 | security operation and it passed a DH object instead. This is incorrect | |
2373 | according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all | |
2374 | of the other locations. Therefore this client side call has been changed to | |
2375 | pass an EVP_PKEY instead. | |
2376 | ||
2fc02378 | 2377 | =item * |
04916913 RL |
2378 | |
2379 | New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF | |
b7140b06 SL |
2380 | |
2381 | The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option | |
2382 | is set, an unexpected EOF is ignored, it pretends a close notify was received | |
2383 | instead and so the returned error becomes SSL_ERROR_ZERO_RETURN. | |
2384 | ||
2fc02378 | 2385 | =item * |
04916913 RL |
2386 | |
2387 | The security strength of SHA1 and MD5 based signatures in TLS has been reduced. | |
b7140b06 SL |
2388 | |
2389 | This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer | |
2390 | working at the default security level of 1 and instead requires security | |
2391 | level 0. The security level can be changed either using the cipher string | |
da496bc1 | 2392 | with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. This also means |
b7140b06 SL |
2393 | that where the signature algorithms extension is missing from a ClientHello |
2394 | then the handshake will fail in TLS 1.2 at security level 1. This is because, | |
2395 | although this extension is optional, failing to provide one means that | |
2396 | OpenSSL will fallback to a default set of signature algorithms. This default | |
2397 | set requires the availability of SHA1. | |
2398 | ||
2fc02378 | 2399 | =item * |
04916913 RL |
2400 | |
2401 | X509 certificates signed using SHA1 are no longer allowed at security level 1 and above. | |
b7140b06 SL |
2402 | |
2403 | In TLS/SSL the default security level is 1. It can be set either using the cipher | |
04916913 | 2404 | string with C<@SECLEVEL>, or calling L<SSL_CTX_set_security_level(3)>. If the |
b7140b06 SL |
2405 | leaf certificate is signed with SHA-1, a call to L<SSL_CTX_use_certificate(3)> |
2406 | will fail if the security level is not lowered first. | |
2407 | Outside TLS/SSL, the default security level is -1 (effectively 0). It can | |
04916913 | 2408 | be set using L<X509_VERIFY_PARAM_set_auth_level(3)> or using the B<-auth_level> |
b7140b06 SL |
2409 | options of the commands. |
2410 | ||
2411 | =back | |
2412 | ||
2413 | =head1 SEE ALSO | |
2414 | ||
2415 | L<fips_module(7)> | |
2416 | ||
4741c80c | 2417 | =head1 HISTORY |
2418 | ||
2419 | The migration guide was created for OpenSSL 3.0. | |
2420 | ||
b7140b06 SL |
2421 | =head1 COPYRIGHT |
2422 | ||
fecb3aae | 2423 | Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved. |
b7140b06 SL |
2424 | |
2425 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
2426 | this file except in compliance with the License. You can obtain a copy | |
2427 | in the file LICENSE in the source distribution or at | |
2428 | L<https://www.openssl.org/source/license.html>. | |
2429 | ||
2430 | =cut |