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