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