Debian Codegraph @

upstream/debian-trixie/man7/ossl-guide-migration.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL-GUIDE-MIGRATION 7SSL"
58 .TH OSSL-GUIDE-MIGRATION 7SSL 2026-04-07 3.5.6 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ossl\-guide\-migration, migration_guide
65 \&\- OpenSSL Guide: Migrating from older OpenSSL versions
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 See the individual manual pages for details.
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 This guide details the changes required to migrate to new versions of OpenSSL.
72 Currently this covers OpenSSL 3.0 & 3.1. For earlier versions refer to
73 <https://github.com/openssl/openssl/blob/master/CHANGES.md>.
74 For an overview of some of the key concepts introduced in OpenSSL 3.0 see
75 \&\fBcrypto\fR\|(7).
76 .SH "OPENSSL 3.1"
77 .IX Header "OPENSSL 3.1"
78 .SS "Main Changes from OpenSSL 3.0"
79 .IX Subsection "Main Changes from OpenSSL 3.0"
80 The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms,
81 consequently the property query \f(CW\*(C`fips=yes\*(C'\fR is mandatory for applications that
82 want to operate in a FIPS approved manner. The algorithms are:
83 .IP "Triple DES ECB" 4
84 .IX Item "Triple DES ECB"
85 .PD 0
86 .IP "Triple DES CBC" 4
87 .IX Item "Triple DES CBC"
88 .IP EdDSA 4
89 .IX Item "EdDSA"
90 .PD
91 .PP
92 There are no other changes requiring additional migration measures since OpenSSL 3.0.
93 .SH "OPENSSL 3.0"
94 .IX Header "OPENSSL 3.0"
95 .SS "Main Changes from OpenSSL 1.1.1"
96 .IX Subsection "Main Changes from OpenSSL 1.1.1"
97 \fIMajor Release\fR
98 .IX Subsection "Major Release"
99 .PP
100 OpenSSL 3.0 is a major release and consequently any application that currently
101 uses an older version of OpenSSL will at the very least need to be recompiled in
102 order to work with the new version. It is the intention that the large majority
103 of applications will work unchanged with OpenSSL 3.0 if those applications
104 previously worked with OpenSSL 1.1.1. However this is not guaranteed and some
105 changes may be required in some cases. Changes may also be required if
106 applications need to take advantage of some of the new features available in
107 OpenSSL 3.0 such as the availability of the FIPS module.
108 .PP
109 \fILicense Change\fR
110 .IX Subsection "License Change"
111 .PP
112 In previous versions, OpenSSL was licensed under the dual OpenSSL and SSLeay
113 licenses <https://www.openssl.org/source/license-openssl-ssleay.txt>
114 (both licenses apply). From OpenSSL 3.0 this is replaced by the
115 Apache License v2 <https://www.openssl.org/source/apache-license-2.0.txt>.
116 .PP
117 \fIProviders and FIPS support\fR
118 .IX Subsection "Providers and FIPS support"
119 .PP
120 One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider
121 concept. Providers collect together and make available algorithm implementations.
122 With OpenSSL 3.0 it is possible to specify, either programmatically or via a
123 config file, which providers you want to use for any given application.
124 OpenSSL 3.0 comes with 5 different providers as standard. Over time third
125 parties may distribute additional providers that can be plugged into OpenSSL.
126 All algorithm implementations available via providers are accessed through the
127 "high level" APIs (for example those functions prefixed with \f(CW\*(C`EVP\*(C'\fR). They cannot
128 be accessed using the "Low Level APIs".
129 .PP
130 One of the standard providers available is the FIPS provider. This makes
131 available FIPS validated cryptographic algorithms.
132 The FIPS provider is disabled by default and needs to be enabled explicitly
133 at configuration time using the \f(CW\*(C`enable\-fips\*(C'\fR option. If it is enabled,
134 the FIPS provider gets built and installed in addition to the other standard
135 providers. No separate installation procedure is necessary.
136 There is however a dedicated \f(CW\*(C`install_fips\*(C'\fR make target, which serves the
137 special purpose of installing only the FIPS provider into an existing
138 OpenSSL installation.
139 .PP
140 Not all algorithms may be available for the application at a particular moment.
141 If the application code uses any digest or cipher algorithm via the EVP interface,
142 the application should verify the result of the \fBEVP_EncryptInit\fR\|(3),
143 \&\fBEVP_EncryptInit_ex\fR\|(3), and \fBEVP_DigestInit\fR\|(3) functions. In case when
144 the requested algorithm is not available, these functions will fail.
145 .PP
146 See also "Legacy Algorithms" for information on the legacy provider.
147 .PP
148 See also "Completing the installation of the FIPS Module" and
149 "Using the FIPS Module in applications".
150 .PP
151 \fILow Level APIs\fR
152 .IX Subsection "Low Level APIs"
153 .PP
154 OpenSSL has historically provided two sets of APIs for invoking cryptographic
155 algorithms: the "high level" APIs (such as the \f(CW\*(C`EVP\*(C'\fR APIs) and the "low level"
156 APIs. The high level APIs are typically designed to work across all algorithm
157 types. The "low level" APIs are targeted at a specific algorithm implementation.
158 For example, the EVP APIs provide the functions \fBEVP_EncryptInit_ex\fR\|(3),
159 \&\fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_EncryptFinal\fR\|(3) to perform symmetric
160 encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc.
161 On the other hand, to do AES encryption using the low level APIs you would have
162 to call AES specific functions such as \fBAES_set_encrypt_key\fR\|(3),
163 \&\fBAES_encrypt\fR\|(3), and so on. The functions for 3DES are different.
164 Use of the low level APIs has been informally discouraged by the OpenSSL
165 development team for a long time. However in OpenSSL 3.0 this is made more
166 formal. All such low level APIs have been deprecated. You may still use them in
167 your applications, but you may start to see deprecation warnings during
168 compilation (dependent on compiler support for this). Deprecated APIs may be
169 removed from future versions of OpenSSL so you are strongly encouraged to update
170 your code to use the high level APIs instead.
171 .PP
172 This is described in more detail in "Deprecation of Low Level Functions"
173 .PP
174 \fILegacy Algorithms\fR
175 .IX Subsection "Legacy Algorithms"
176 .PP
177 Some cryptographic algorithms such as \fBMD2\fR and \fBDES\fR that were available via
178 the EVP APIs are now considered legacy and their use is strongly discouraged.
179 These legacy EVP algorithms are still available in OpenSSL 3.0 but not by
180 default. If you want to use them then you must load the legacy provider.
181 This can be as simple as a config file change, or can be done programmatically.
182 See \fBOSSL_PROVIDER\-legacy\fR\|(7) for a complete list of algorithms.
183 Applications using the EVP APIs to access these algorithms should instead use
184 more modern algorithms. If that is not possible then these applications
185 should ensure that the legacy provider has been loaded. This can be achieved
186 either programmatically or via configuration. See \fBcrypto\fR\|(7) man page for
187 more information about providers.
188 .PP
189 \fIEngines and "METHOD" APIs\fR
190 .IX Subsection "Engines and ""METHOD"" APIs"
191 .PP
192 The refactoring to support Providers conflicts internally with the APIs used to
193 support engines, including the ENGINE API and any function that creates or
194 modifies custom "METHODS" (for example \fBEVP_MD_meth_new\fR\|(3),
195 \&\fBEVP_CIPHER_meth_new\fR\|(3), \fBEVP_PKEY_meth_new\fR\|(3), \fBRSA_meth_new\fR\|(3),
196 \&\fBEC_KEY_METHOD_new\fR\|(3), etc.). These functions are being deprecated in
197 OpenSSL 3.0, and users of these APIs should know that their use can likely
198 bypass provider selection and configuration, with unintended consequences.
199 This is particularly relevant for applications written to use the OpenSSL 3.0
200 FIPS module, as detailed below. Authors and maintainers of external engines are
201 strongly encouraged to refactor their code transforming engines into providers
202 using the new Provider API and avoiding deprecated methods.
203 .PP
204 \fISupport of legacy engines\fR
205 .IX Subsection "Support of legacy engines"
206 .PP
207 If openssl is not built without engine support or deprecated API support, engines
208 will still work. However, their applicability will be limited.
209 .PP
210 New algorithms provided via engines will still work.
211 .PP
212 Engine-backed keys can be loaded via custom \fBOSSL_STORE\fR implementation.
213 In this case the \fBEVP_PKEY\fR objects created via \fBENGINE_load_private_key\fR\|(3)
214 will be considered legacy and will continue to work.
215 .PP
216 To ensure the future compatibility, the engines should be turned to providers.
217 To prefer the provider-based hardware offload, you can specify the default
218 properties to prefer your provider.
219 .PP
220 Setting engine-based or application-based default low-level crypto method such
221 as \fBRSA_METHOD\fR or \fBEC_KEY_METHOD\fR is still possible and keys inside the
222 default provider will use the engine-based implementation for the crypto
223 operations. However \fBEVP_PKEY\fRs created by decoding by using \fBOSSL_DECODER\fR,
224 \&\fBPEM_\fR or \fBd2i_\fR APIs will be provider-based. To create a fully legacy
225 \&\fBEVP_PKEY\fRs \fBEVP_PKEY_set1_RSA\fR\|(3), \fBEVP_PKEY_set1_EC_KEY\fR\|(3) or similar
226 functions must be used.
227 .PP
228 \fIVersioning Scheme\fR
229 .IX Subsection "Versioning Scheme"
230 .PP
231 The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new
232 versioning scheme has this format:
233 .PP
234 MAJOR.MINOR.PATCH
235 .PP
236 For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter
237 at the end of the release version number. This will no longer be used and
238 instead the patch level is indicated by the final number in the version. A
239 change in the second (MINOR) number indicates that new features may have been
240 added. OpenSSL versions with the same major number are API and ABI compatible.
241 If the major number changes then API and ABI compatibility is not guaranteed.
242 .PP
243 For more information, see \fBOpenSSL_version\fR\|(3).
244 .PP
245 \fIOther major new features\fR
246 .IX Subsection "Other major new features"
247 .PP
248 Certificate Management Protocol (CMP, RFC 9810)
249 .IX Subsection "Certificate Management Protocol (CMP, RFC 9810)"
250 .PP
251 This also covers CRMF (RFC 4211) and HTTP transfer (RFC 9811)
252 See \fBopenssl\-cmp\fR\|(1) and \fBOSSL_CMP_exec_certreq\fR\|(3) as starting points.
253 .PP
254 HTTP(S) client
255 .IX Subsection "HTTP(S) client"
256 .PP
257 A proper HTTP(S) client that supports GET and POST, redirection, plain and
258 ASN.1\-encoded contents, proxies, and timeouts.
259 .PP
260 Key Derivation Function API (EVP_KDF)
261 .IX Subsection "Key Derivation Function API (EVP_KDF)"
262 .PP
263 This simplifies the process of adding new KDF and PRF implementations.
264 .PP
265 Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object
266 which was not a logical mapping.
267 Existing applications that use KDF algorithms using EVP_PKEY
268 (scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge
269 internally.
270 All new applications should use the new \fBEVP_KDF\fR\|(3) interface.
271 See also "Key Derivation Function (KDF)" in \fBOSSL_PROVIDER\-default\fR\|(7) and
272 "Key Derivation Function (KDF)" in \fBOSSL_PROVIDER\-FIPS\fR\|(7).
273 .PP
274 Message Authentication Code API (EVP_MAC)
275 .IX Subsection "Message Authentication Code API (EVP_MAC)"
276 .PP
277 This simplifies the process of adding MAC implementations.
278 .PP
279 This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued
280 use of MACs through raw private keys in functionality such as
281 \&\fBEVP_DigestSign\fR\|(3) and \fBEVP_DigestVerify\fR\|(3).
282 .PP
283 All new applications should use the new \fBEVP_MAC\fR\|(3) interface.
284 See also "Message Authentication Code (MAC)" in \fBOSSL_PROVIDER\-default\fR\|(7)
285 and "Message Authentication Code (MAC)" in \fBOSSL_PROVIDER\-FIPS\fR\|(7).
286 .PP
287 Algorithm Fetching
288 .IX Subsection "Algorithm Fetching"
289 .PP
290 Using calls to convenience functions such as \fBEVP_sha256()\fR and \fBEVP_aes_256_gcm()\fR may
291 incur a performance penalty when using providers.
292 Retrieving algorithms from providers involves searching for an algorithm by name.
293 This is much slower than directly accessing a method table.
294 It is recommended to prefetch algorithms if an algorithm is used many times.
295 See "Performance" in \fBcrypto\fR\|(7), "Explicit fetching" in \fBcrypto\fR\|(7) and "Implicit fetching" in \fBcrypto\fR\|(7).
296 .PP
297 Support for Linux Kernel TLS
298 .IX Subsection "Support for Linux Kernel TLS"
299 .PP
300 In order to use KTLS, support for it must be compiled in using the
301 \&\f(CW\*(C`enable\-ktls\*(C'\fR configuration option. It must also be enabled at run time using
302 the \fBSSL_OP_ENABLE_KTLS\fR option.
303 .PP
304 New Algorithms
305 .IX Subsection "New Algorithms"
306 .IP \(bu 4
307 KDF algorithms "SINGLE STEP" and "SSH"
308 .Sp
309 See \fBEVP_KDF\-SS\fR\|(7) and \fBEVP_KDF\-SSHKDF\fR\|(7)
310 .IP \(bu 4
311 MAC Algorithms "GMAC" and "KMAC"
312 .Sp
313 See \fBEVP_MAC\-GMAC\fR\|(7) and \fBEVP_MAC\-KMAC\fR\|(7).
314 .IP \(bu 4
315 KEM Algorithm "RSASVE"
316 .Sp
317 See \fBEVP_KEM\-RSA\fR\|(7).
318 .IP \(bu 4
319 Cipher Algorithm "AES-SIV"
320 .Sp
321 See "SIV Mode" in \fBEVP_EncryptInit\fR\|(3).
322 .IP \(bu 4
323 AES Key Wrap inverse ciphers supported by EVP layer.
324 .Sp
325 The inverse ciphers use AES decryption for wrapping, and AES encryption for
326 unwrapping. The algorithms are: "AES\-128\-WRAP\-INV", "AES\-192\-WRAP\-INV",
327 "AES\-256\-WRAP\-INV", "AES\-128\-WRAP\-PAD\-INV", "AES\-192\-WRAP\-PAD\-INV" and
328 "AES\-256\-WRAP\-PAD\-INV".
329 .IP \(bu 4
330 CTS ciphers added to EVP layer.
331 .Sp
332 The algorithms are "AES\-128\-CBC\-CTS", "AES\-192\-CBC\-CTS", "AES\-256\-CBC\-CTS",
333 "CAMELLIA\-128\-CBC\-CTS", "CAMELLIA\-192\-CBC\-CTS" and "CAMELLIA\-256\-CBC\-CTS".
334 CS1, CS2 and CS3 variants are supported.
335 .PP
336 CMS and PKCS#7 updates
337 .IX Subsection "CMS and PKCS#7 updates"
338 .IP \(bu 4
339 Added CAdES-BES signature verification support.
340 .IP \(bu 4
341 Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API.
342 .IP \(bu 4
343 Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM
344 .Sp
345 This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax.
346 Its purpose is to support encryption and decryption of a digital envelope that
347 is both authenticated and encrypted using AES GCM mode.
348 .IP \(bu 4
349 \&\fBPKCS7_get_octet_string\fR\|(3) and \fBPKCS7_type_is_other\fR\|(3) were made public.
350 .PP
351 PKCS#12 API updates
352 .IX Subsection "PKCS#12 API updates"
353 .PP
354 The default algorithms for pkcs12 creation with the \fBPKCS12_create()\fR function
355 were changed to more modern PBKDF2 and AES based algorithms. The default
356 MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal
357 with the password-based encryption iteration count. The default digest
358 algorithm for the MAC computation was changed to SHA\-256. The pkcs12
359 application now supports \-legacy option that restores the previous
360 default algorithms to support interoperability with legacy systems.
361 .PP
362 Added enhanced PKCS#12 APIs which accept a library context \fBOSSL_LIB_CTX\fR
363 and (where relevant) a property query. Other APIs which handle PKCS#7 and
364 PKCS#8 objects have also been enhanced where required. This includes:
365 .PP
366 \&\fBPKCS12_add_key_ex\fR\|(3), \fBPKCS12_add_safe_ex\fR\|(3), \fBPKCS12_add_safes_ex\fR\|(3),
367 \&\fBPKCS12_create_ex\fR\|(3), \fBPKCS12_decrypt_skey_ex\fR\|(3), \fBPKCS12_init_ex\fR\|(3),
368 \&\fBPKCS12_item_decrypt_d2i_ex\fR\|(3), \fBPKCS12_item_i2d_encrypt_ex\fR\|(3),
369 \&\fBPKCS12_key_gen_asc_ex\fR\|(3), \fBPKCS12_key_gen_uni_ex\fR\|(3), \fBPKCS12_key_gen_utf8_ex\fR\|(3),
370 \&\fBPKCS12_pack_p7encdata_ex\fR\|(3), \fBPKCS12_pbe_crypt_ex\fR\|(3), \fBPKCS12_PBE_keyivgen_ex\fR\|(3),
371 \&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt_ex\fR\|(3), \fBPKCS5_pbe2_set_iv_ex\fR\|(3),
372 \&\fBPKCS5_pbe_set0_algor_ex\fR\|(3), \fBPKCS5_pbe_set_ex\fR\|(3), \fBPKCS5_pbkdf2_set_ex\fR\|(3),
373 \&\fBPKCS5_v2_PBE_keyivgen_ex\fR\|(3), \fBPKCS5_v2_scrypt_keyivgen_ex\fR\|(3),
374 \&\fBPKCS8_decrypt_ex\fR\|(3), \fBPKCS8_encrypt_ex\fR\|(3), \fBPKCS8_set0_pbe_ex\fR\|(3).
375 .PP
376 As part of this change the EVP_PBE_xxx APIs can also accept a library
377 context and property query and will call an extended version of the key/IV
378 derivation function which supports these parameters. This includes
379 \&\fBEVP_PBE_CipherInit_ex\fR\|(3), \fBEVP_PBE_find_ex\fR\|(3) and \fBEVP_PBE_scrypt_ex\fR\|(3).
380 .PP
381 PKCS#12 KDF versus FIPS
382 .IX Subsection "PKCS#12 KDF versus FIPS"
383 .PP
384 Unlike in 1.x.y, the PKCS12KDF algorithm used when a PKCS#12 structure
385 is created with a MAC that does not work with the FIPS provider as the PKCS12KDF
386 is not a FIPS approvable mechanism.
387 .PP
388 See \fBEVP_KDF\-PKCS12KDF\fR\|(7), \fBPKCS12_create\fR\|(3), \fBopenssl\-pkcs12\fR\|(1),
389 \&\fBOSSL_PROVIDER\-FIPS\fR\|(7).
390 .PP
391 Windows thread synchronization changes
392 .IX Subsection "Windows thread synchronization changes"
393 .PP
394 Windows thread synchronization uses read/write primitives (SRWLock) when
395 supported by the OS, otherwise CriticalSection continues to be used.
396 .PP
397 Trace API
398 .IX Subsection "Trace API"
399 .PP
400 A new generic trace API has been added which provides support for enabling
401 instrumentation through trace output. This feature is mainly intended as an aid
402 for developers and is disabled by default. To utilize it, OpenSSL needs to be
403 configured with the \f(CW\*(C`enable\-trace\*(C'\fR option.
404 .PP
405 If the tracing API is enabled, the application can activate trace output by
406 registering BIOs as trace channels for a number of tracing and debugging
407 categories. See \fBOSSL_trace_enabled\fR\|(3).
408 .PP
409 Key validation updates
410 .IX Subsection "Key validation updates"
411 .PP
412 \&\fBEVP_PKEY_public_check\fR\|(3) and \fBEVP_PKEY_param_check\fR\|(3) now work for
413 more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448.
414 Previously (in 1.1.1) they would return \-2. For key types that do not have
415 parameters \fBEVP_PKEY_param_check\fR\|(3) will always return 1.
416 .PP
417 \fIOther notable deprecations and changes\fR
418 .IX Subsection "Other notable deprecations and changes"
419 .PP
420 The function code part of an OpenSSL error code is no longer relevant
421 .IX Subsection "The function code part of an OpenSSL error code is no longer relevant"
422 .PP
423 This code is now always set to zero. Related functions are deprecated.
424 .PP
425 STACK and HASH macros have been cleaned up
426 .IX Subsection "STACK and HASH macros have been cleaned up"
427 .PP
428 The type-safe wrappers are declared everywhere and implemented once.
429 See \fBDEFINE_STACK_OF\fR\|(3) and \fBDEFINE_LHASH_OF_EX\fR\|(3).
430 .PP
431 The RAND_DRBG subsystem has been removed
432 .IX Subsection "The RAND_DRBG subsystem has been removed"
433 .PP
434 The new \fBEVP_RAND\fR\|(3) is a partial replacement: the DRBG callback framework is
435 absent. The RAND_DRBG API did not fit well into the new provider concept as
436 implemented by EVP_RAND and EVP_RAND_CTX.
437 .PP
438 Removed \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR
439 .IX Subsection "Removed FIPS_mode() and FIPS_mode_set()"
440 .PP
441 These functions are legacy APIs that are not applicable to the new provider
442 model. Applications should instead use
443 \&\fBEVP_default_properties_is_fips_enabled\fR\|(3) and
444 \&\fBEVP_default_properties_enable_fips\fR\|(3).
445 .PP
446 Key generation is slower
447 .IX Subsection "Key generation is slower"
448 .PP
449 The Miller-Rabin test now uses 64 rounds, which is used for all prime generation,
450 including RSA key generation. This affects the time for larger keys sizes.
451 .PP
452 The default key generation method for the regular 2\-prime RSA keys was changed
453 to the FIPS186\-4 B.3.6 method (Generation of Probable Primes with Conditions
454 Based on Auxiliary Probable Primes). This method is slower than the original
455 method.
456 .PP
457 Change PBKDF2 to conform to SP800\-132 instead of the older PKCS5 RFC2898
458 .IX Subsection "Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898"
459 .PP
460 This checks that the salt length is at least 128 bits, the derived key length is
461 at least 112 bits, and that the iteration count is at least 1000.
462 For backwards compatibility these checks are disabled by default in the
463 default provider, but are enabled by default in the FIPS provider.
464 .PP
465 To enable or disable the checks see \fBOSSL_KDF_PARAM_PKCS5\fR in
466 \&\fBEVP_KDF\-PBKDF2\fR\|(7). The parameter can be set using \fBEVP_KDF_derive\fR\|(3).
467 .PP
468 Enforce a minimum DH modulus size of 512 bits
469 .IX Subsection "Enforce a minimum DH modulus size of 512 bits"
470 .PP
471 Smaller sizes now result in an error.
472 .PP
473 SM2 key changes
474 .IX Subsection "SM2 key changes"
475 .PP
476 EC EVP_PKEYs with the SM2 curve have been reworked to automatically become
477 EVP_PKEY_SM2 rather than EVP_PKEY_EC.
478 .PP
479 Unlike in previous OpenSSL versions, this means that applications cannot
480 call \fBEVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)\fR to get SM2 computations.
481 .PP
482 Parameter and key generation is also reworked to make it possible
483 to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
484 SM2 keys directly and must not create an EVP_PKEY_EC key first. It is no longer
485 possible to import an SM2 key with domain parameters other than the SM2 elliptic
486 curve ones.
487 .PP
488 Validation of SM2 keys has been separated from the validation of regular EC
489 keys, allowing to improve the SM2 validation process to reject loaded private
490 keys that are not conforming to the SM2 ISO standard.
491 In particular, a private scalar \fIk\fR outside the range \fI1 <= k < n\-1\fR is
492 now correctly rejected.
493 .PP
494 \fBEVP_PKEY_set_alias_type()\fR method has been removed
495 .IX Subsection "EVP_PKEY_set_alias_type() method has been removed"
496 .PP
497 This function made a \fBEVP_PKEY\fR object mutable after it had been set up. In
498 OpenSSL 3.0 it was decided that a provided key should not be able to change its
499 type, so this function has been removed.
500 .PP
501 Functions that return an internal key should be treated as read only
502 .IX Subsection "Functions that return an internal key should be treated as read only"
503 .PP
504 Functions such as \fBEVP_PKEY_get0_RSA\fR\|(3) behave slightly differently in
505 OpenSSL 3.0. Previously they returned a pointer to the low-level key used
506 internally by libcrypto. From OpenSSL 3.0 this key may now be held in a
507 provider. Calling these functions will only return a handle on the internal key
508 where the EVP_PKEY was constructed using this key in the first place, for
509 example using a function or macro such as \fBEVP_PKEY_assign_RSA\fR\|(3),
510 \&\fBEVP_PKEY_set1_RSA\fR\|(3), etc.
511 Where the EVP_PKEY holds a provider managed key, then these functions now return
512 a cached copy of the key. Changes to the internal provider key that take place
513 after the first time the cached key is accessed will not be reflected back in
514 the cached copy. Similarly any changes made to the cached copy by application
515 code will not be reflected back in the internal provider key.
516 .PP
517 For the above reasons the keys returned from these functions should typically be
518 treated as read-only. To emphasise this the value returned from
519 \&\fBEVP_PKEY_get0_RSA\fR\|(3), \fBEVP_PKEY_get0_DSA\fR\|(3), \fBEVP_PKEY_get0_EC_KEY\fR\|(3) and
520 \&\fBEVP_PKEY_get0_DH\fR\|(3) have been made const. This may break some existing code.
521 Applications broken by this change should be modified. The preferred solution is
522 to refactor the code to avoid the use of these deprecated functions. Failing
523 this the code should be modified to use a const pointer instead.
524 The \fBEVP_PKEY_get1_RSA\fR\|(3), \fBEVP_PKEY_get1_DSA\fR\|(3), \fBEVP_PKEY_get1_EC_KEY\fR\|(3)
525 and \fBEVP_PKEY_get1_DH\fR\|(3) functions continue to return a non-const pointer to
526 enable them to be "freed". However they should also be treated as read-only.
527 .PP
528 The public key check has moved from \fBEVP_PKEY_derive()\fR to \fBEVP_PKEY_derive_set_peer()\fR
529 .IX Subsection "The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()"
530 .PP
531 This may mean result in an error in \fBEVP_PKEY_derive_set_peer\fR\|(3) rather than
532 during \fBEVP_PKEY_derive\fR\|(3).
533 To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0).
534 .PP
535 The print format has cosmetic changes for some functions
536 .IX Subsection "The print format has cosmetic changes for some functions"
537 .PP
538 The output from numerous "printing" functions such as \fBX509_signature_print\fR\|(3),
539 \&\fBX509_print_ex\fR\|(3), \fBX509_CRL_print_ex\fR\|(3), and other similar functions has been
540 amended such that there may be cosmetic differences between the output
541 observed in 1.1.1 and 3.0. This also applies to the \fB\-text\fR output from the
542 \&\fBopenssl x509\fR and \fBopenssl crl\fR applications.
543 .PP
544 Interactive mode from the \fBopenssl\fR program has been removed
545 .IX Subsection "Interactive mode from the openssl program has been removed"
546 .PP
547 From now on, running it without arguments is equivalent to \fBopenssl help\fR.
548 .PP
549 The error return values from some control calls (ctrl) have changed
550 .IX Subsection "The error return values from some control calls (ctrl) have changed"
551 .PP
552 One significant change is that controls which used to return \-2 for
553 invalid inputs, now return \-1 indicating a generic error condition instead.
554 .PP
555 DH and DHX key types have different settable parameters
556 .IX Subsection "DH and DHX key types have different settable parameters"
557 .PP
558 Previously (in 1.1.1) these conflicting parameters were allowed, but will now
559 result in errors. See \fBEVP_PKEY\-DH\fR\|(7) for further details. This affects the
560 behaviour of \fBopenssl\-genpkey\fR\|(1) for DH parameter generation.
561 .PP
562 \fBEVP_CIPHER_CTX_set_flags()\fR ordering change
563 .IX Subsection "EVP_CIPHER_CTX_set_flags() ordering change"
564 .PP
565 If using a cipher from a provider the \fBEVP_CIPH_FLAG_LENGTH_BITS\fR flag can only
566 be set \fBafter\fR the cipher has been assigned to the cipher context.
567 See "FLAGS" in \fBEVP_EncryptInit\fR\|(3) for more information.
568 .PP
569 Validation of operation context parameters
570 .IX Subsection "Validation of operation context parameters"
571 .PP
572 Due to move of the implementation of cryptographic operations to the
573 providers, validation of various operation parameters can be postponed until
574 the actual operation is executed where previously it happened immediately
575 when an operation parameter was set.
576 .PP
577 For example when setting an unsupported curve with
578 \&\fBEVP_PKEY_CTX_set_ec_paramgen_curve_nid()\fR this function call will not fail
579 but later keygen operations with the EVP_PKEY_CTX will fail.
580 .PP
581 Removal of function code from the error codes
582 .IX Subsection "Removal of function code from the error codes"
583 .PP
584 The function code part of the error code is now always set to 0. For that
585 reason the \fBERR_GET_FUNC()\fR macro was removed. Applications must resolve
586 the error codes only using the library number and the reason code.
587 .PP
588 ChaCha20\-Poly1305 cipher does not allow a truncated IV length to be used
589 .IX Subsection "ChaCha20-Poly1305 cipher does not allow a truncated IV length to be used"
590 .PP
591 In OpenSSL 3.0 setting the IV length to any value other than 12 will result in an
592 error.
593 Prior to OpenSSL 3.0 the ivlen could be smaller that the required 12 byte length,
594 using EVP_CIPHER_CTX_ctrl(ctx, EVP_CRTL_AEAD_SET_IVLEN, ivlen, NULL). This resulted
595 in an IV that had leading zero padding.
596 .SS "Installation and Compilation"
597 .IX Subsection "Installation and Compilation"
598 Please refer to the INSTALL.md file in the top of the distribution for
599 instructions on how to build and install OpenSSL 3.0. Please also refer to the
600 various platform specific NOTES files for your specific platform.
601 .SS "Upgrading from OpenSSL 1.1.1"
602 .IX Subsection "Upgrading from OpenSSL 1.1.1"
603 Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight
604 forward in most cases. The most likely area where you will encounter problems
605 is if you have used low level APIs in your code (as discussed above). In that
606 case you are likely to start seeing deprecation warnings when compiling your
607 application. If this happens you have 3 options:
608 .IP 1. 4
609 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.
610 .IP 2. 4
611 Suppress the warnings. Refer to your compiler documentation on how to do this.
612 .IP 3. 4
613 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
614 .PP
615 \fIError code changes\fR
616 .IX Subsection "Error code changes"
617 .PP
618 As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with
619 widely used file formats, application code that checks for particular error
620 reason codes on key loading failures might need an update.
621 .PP
622 Password-protected keys may deserve special attention. If only some errors
623 are treated as an indicator that the user should be asked about the password again,
624 it's worth testing these scenarios and processing the newly relevant codes.
625 .PP
626 There may be more cases to treat specially, depending on the calling application code.
627 .SS "Upgrading from OpenSSL 1.0.2"
628 .IX Subsection "Upgrading from OpenSSL 1.0.2"
629 Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more
630 difficult. In addition to the issues discussed above in the section about
631 "Upgrading from OpenSSL 1.1.1", the main things to be aware of are:
632 .IP 1. 4
633 The build and installation procedure has changed significantly.
634 .Sp
635 Check the file INSTALL.md in the top of the installation for instructions on how
636 to build and install OpenSSL for your platform. Also read the various NOTES
637 files in the same directory, as applicable for your platform.
638 .IP 2. 4
639 Many structures have been made opaque in OpenSSL 3.0.
640 .Sp
641 The structure definitions have been removed from the public header files and
642 moved to internal header files. In practice this means that you can no longer
643 stack allocate some structures. Instead they must be heap allocated through some
644 function call (typically those function names have a \f(CW\*(C`_new\*(C'\fR suffix to them).
645 Additionally you must use "setter" or "getter" functions to access the fields
646 within those structures.
647 .Sp
648 For example code that previously looked like this:
649 .Sp
650 .Vb 1
651 \& EVP_MD_CTX md_ctx;
652 \&
653 \& /* This line will now generate compiler errors */
654 \& EVP_MD_CTX_init(&md_ctx);
655 .Ve
656 .Sp
657 The code needs to be amended to look like this:
658 .Sp
659 .Vb 1
660 \& EVP_MD_CTX *md_ctx;
661 \&
662 \& md_ctx = EVP_MD_CTX_new();
663 \& ...
664 \& ...
665 \& EVP_MD_CTX_free(md_ctx);
666 .Ve
667 .IP 3. 4
668 Support for TLSv1.3 has been added.
669 .Sp
670 This has a number of implications for SSL/TLS applications. See the
671 TLS1.3 page <https://github.com/openssl/openssl/wiki/TLS1.3> for further details.
672 .PP
673 More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0
674 can be found on the
675 OpenSSL 1.1.0 Changes page <https://github.com/openssl/openssl/wiki/OpenSSL_1.1.0_Changes>.
676 .PP
677 \fIUpgrading from the OpenSSL 2.0 FIPS Object Module\fR
678 .IX Subsection "Upgrading from the OpenSSL 2.0 FIPS Object Module"
679 .PP
680 The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built
681 separately and then integrated into your main OpenSSL 1.0.2 build.
682 In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of
683 OpenSSL and is no longer a separate download. For further information see
684 "Completing the installation of the FIPS Module".
685 .PP
686 The function calls \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR have been removed
687 from OpenSSL 3.0. You should rewrite your application to not use them.
688 See \fBfips_module\fR\|(7) and \fBOSSL_PROVIDER\-FIPS\fR\|(7) for details.
689 .SS "Completing the installation of the FIPS Module"
690 .IX Subsection "Completing the installation of the FIPS Module"
691 The FIPS Module will be built and installed automatically if FIPS support has
692 been configured. The current documentation can be found in the
693 README-FIPS <https://github.com/openssl/openssl/blob/master/README-FIPS.md> file.
694 .SS Programming
695 .IX Subsection "Programming"
696 Applications written to work with OpenSSL 1.1.1 will mostly just work with
697 OpenSSL 3.0. However changes will be required if you want to take advantage of
698 some of the new features that OpenSSL 3.0 makes available. In order to do that
699 you need to understand some new concepts introduced in OpenSSL 3.0.
700 Read "Library contexts" in \fBcrypto\fR\|(7) for further information.
701 .PP
702 \fILibrary Context\fR
703 .IX Subsection "Library Context"
704 .PP
705 A library context allows different components of a complex application to each
706 use a different library context and have different providers loaded with
707 different configuration settings.
708 See "Library contexts" in \fBcrypto\fR\|(7) for further info.
709 .PP
710 If the user creates an \fBOSSL_LIB_CTX\fR via \fBOSSL_LIB_CTX_new\fR\|(3) then many
711 functions may need to be changed to pass additional parameters to handle the
712 library context.
713 .PP
714 Using a Library Context \- Old functions that should be changed
715 .IX Subsection "Using a Library Context - Old functions that should be changed"
716 .PP
717 If a library context is needed then all EVP_* digest functions that return a
718 \&\fBconst EVP_MD *\fR such as \fBEVP_sha256()\fR should be replaced with a call to
719 \&\fBEVP_MD_fetch\fR\|(3). See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7).
720 .PP
721 If a library context is needed then all EVP_* cipher functions that return a
722 \&\fBconst EVP_CIPHER *\fR such as \fBEVP_aes_128_cbc()\fR should be replaced vith a call to
723 \&\fBEVP_CIPHER_fetch\fR\|(3). See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7).
724 .PP
725 Some functions can be passed an object that has already been set up with a library
726 context such as \fBd2i_X509\fR\|(3), \fBd2i_X509_CRL\fR\|(3), \fBd2i_X509_REQ\fR\|(3) and
727 \&\fBd2i_X509_PUBKEY\fR\|(3). If NULL is passed instead then the created object will be
728 set up with the default library context. Use \fBX509_new_ex\fR\|(3),
729 \&\fBX509_CRL_new_ex\fR\|(3), \fBX509_REQ_new_ex\fR\|(3) and \fBX509_PUBKEY_new_ex\fR\|(3) if a
730 library context is required.
731 .PP
732 All functions listed below with a \fINAME\fR have a replacement function \fINAME_ex\fR
733 that takes \fBOSSL_LIB_CTX\fR as an additional argument. Functions that have other
734 mappings are listed along with the respective name.
735 .IP \(bu 4
736 \&\fBASN1_item_new\fR\|(3), \fBASN1_item_d2i\fR\|(3), \fBASN1_item_d2i_fp\fR\|(3),
737 \&\fBASN1_item_d2i_bio\fR\|(3), \fBASN1_item_sign\fR\|(3) and \fBASN1_item_verify\fR\|(3)
738 .IP \(bu 4
739 \&\fBBIO_new\fR\|(3)
740 .IP \(bu 4
741 \&\fBb2i_RSA_PVK_bio()\fR and \fBi2b_PVK_bio()\fR
742 .IP \(bu 4
743 \&\fBBN_CTX_new\fR\|(3) and \fBBN_CTX_secure_new\fR\|(3)
744 .IP \(bu 4
745 \&\fBCMS_AuthEnvelopedData_create\fR\|(3), \fBCMS_ContentInfo_new\fR\|(3), \fBCMS_data_create\fR\|(3),
746 \&\fBCMS_digest_create\fR\|(3), \fBCMS_EncryptedData_encrypt\fR\|(3), \fBCMS_encrypt\fR\|(3),
747 \&\fBCMS_EnvelopedData_create\fR\|(3), \fBCMS_ReceiptRequest_create0\fR\|(3) and \fBCMS_sign\fR\|(3)
748 .IP \(bu 4
749 \&\fBCONF_modules_load_file\fR\|(3)
750 .IP \(bu 4
751 \&\fBCTLOG_new\fR\|(3), \fBCTLOG_new_from_base64\fR\|(3) and \fBCTLOG_STORE_new\fR\|(3)
752 .IP \(bu 4
753 \&\fBCT_POLICY_EVAL_CTX_new\fR\|(3)
754 .IP \(bu 4
755 \&\fBd2i_AutoPrivateKey\fR\|(3), \fBd2i_PrivateKey\fR\|(3) and \fBd2i_PUBKEY\fR\|(3)
756 .IP \(bu 4
757 \&\fBd2i_PrivateKey_bio\fR\|(3) and \fBd2i_PrivateKey_fp\fR\|(3)
758 .Sp
759 Use \fBd2i_PrivateKey_ex_bio\fR\|(3) and \fBd2i_PrivateKey_ex_fp\fR\|(3)
760 .IP \(bu 4
761 \&\fBEC_GROUP_new\fR\|(3)
762 .Sp
763 Use \fBEC_GROUP_new_by_curve_name_ex\fR\|(3) or \fBEC_GROUP_new_from_params\fR\|(3).
764 .IP \(bu 4
765 \&\fBEVP_DigestSignInit\fR\|(3) and \fBEVP_DigestVerifyInit\fR\|(3)
766 .IP \(bu 4
767 \&\fBEVP_PBE_CipherInit\fR\|(3), \fBEVP_PBE_find\fR\|(3) and \fBEVP_PBE_scrypt\fR\|(3)
768 .IP \(bu 4
769 \&\fBPKCS5_PBE_keyivgen\fR\|(3)
770 .IP \(bu 4
771 \&\fBEVP_PKCS82PKEY\fR\|(3)
772 .IP \(bu 4
773 \&\fBEVP_PKEY_CTX_new_id\fR\|(3)
774 .Sp
775 Use \fBEVP_PKEY_CTX_new_from_name\fR\|(3)
776 .IP \(bu 4
777 \&\fBEVP_PKEY_derive_set_peer\fR\|(3), \fBEVP_PKEY_new_raw_private_key\fR\|(3)
778 and \fBEVP_PKEY_new_raw_public_key\fR\|(3)
779 .IP \(bu 4
780 \&\fBEVP_SignFinal\fR\|(3) and \fBEVP_VerifyFinal\fR\|(3)
781 .IP \(bu 4
782 \&\fBNCONF_new\fR\|(3)
783 .IP \(bu 4
784 \&\fBOCSP_RESPID_match\fR\|(3) and \fBOCSP_RESPID_set_by_key\fR\|(3)
785 .IP \(bu 4
786 \&\fBOPENSSL_thread_stop\fR\|(3)
787 .IP \(bu 4
788 \&\fBOSSL_STORE_open\fR\|(3)
789 .IP \(bu 4
790 \&\fBPEM_read_bio_Parameters\fR\|(3), \fBPEM_read_bio_PrivateKey\fR\|(3), \fBPEM_read_bio_PUBKEY\fR\|(3),
791 \&\fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_read_PUBKEY\fR\|(3)
792 .IP \(bu 4
793 \&\fBPEM_write_bio_PrivateKey\fR\|(3), \fBPEM_write_bio_PUBKEY\fR\|(3), \fBPEM_write_PrivateKey\fR\|(3)
794 and \fBPEM_write_PUBKEY\fR\|(3)
795 .IP \(bu 4
796 \&\fBPEM_X509_INFO_read_bio\fR\|(3) and \fBPEM_X509_INFO_read\fR\|(3)
797 .IP \(bu 4
798 \&\fBPKCS12_add_key\fR\|(3), \fBPKCS12_add_safe\fR\|(3), \fBPKCS12_add_safes\fR\|(3),
799 \&\fBPKCS12_create\fR\|(3), \fBPKCS12_decrypt_skey\fR\|(3), \fBPKCS12_init\fR\|(3), \fBPKCS12_item_decrypt_d2i\fR\|(3),
800 \&\fBPKCS12_item_i2d_encrypt\fR\|(3), \fBPKCS12_key_gen_asc\fR\|(3), \fBPKCS12_key_gen_uni\fR\|(3),
801 \&\fBPKCS12_key_gen_utf8\fR\|(3), \fBPKCS12_pack_p7encdata\fR\|(3), \fBPKCS12_pbe_crypt\fR\|(3),
802 \&\fBPKCS12_PBE_keyivgen\fR\|(3), \fBPKCS12_SAFEBAG_create_pkcs8_encrypt\fR\|(3)
803 .IP \(bu 4
804 \&\fBPKCS5_pbe_set0_algor\fR\|(3), \fBPKCS5_pbe_set\fR\|(3), \fBPKCS5_pbe2_set_iv\fR\|(3),
805 \&\fBPKCS5_pbkdf2_set\fR\|(3) and \fBPKCS5_v2_scrypt_keyivgen\fR\|(3)
806 .IP \(bu 4
807 \&\fBPKCS7_encrypt\fR\|(3), \fBPKCS7_new\fR\|(3) and \fBPKCS7_sign\fR\|(3)
808 .IP \(bu 4
809 \&\fBPKCS8_decrypt\fR\|(3), \fBPKCS8_encrypt\fR\|(3) and \fBPKCS8_set0_pbe\fR\|(3)
810 .IP \(bu 4
811 \&\fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3)
812 .IP \(bu 4
813 \&\fBSMIME_write_ASN1\fR\|(3)
814 .IP \(bu 4
815 \&\fBSSL_load_client_CA_file\fR\|(3)
816 .IP \(bu 4
817 \&\fBSSL_CTX_new\fR\|(3)
818 .IP \(bu 4
819 \&\fBTS_RESP_CTX_new\fR\|(3)
820 .IP \(bu 4
821 \&\fBX509_CRL_new\fR\|(3)
822 .IP \(bu 4
823 \&\fBX509_load_cert_crl_file\fR\|(3) and \fBX509_load_cert_file\fR\|(3)
824 .IP \(bu 4
825 \&\fBX509_LOOKUP_by_subject\fR\|(3) and \fBX509_LOOKUP_ctrl\fR\|(3)
826 .IP \(bu 4
827 \&\fBX509_NAME_hash\fR\|(3)
828 .IP \(bu 4
829 \&\fBX509_new\fR\|(3)
830 .IP \(bu 4
831 \&\fBX509_REQ_new\fR\|(3) and \fBX509_REQ_verify\fR\|(3)
832 .IP \(bu 4
833 \&\fBX509_STORE_CTX_new\fR\|(3), \fBX509_STORE_set_default_paths\fR\|(3), \fBX509_STORE_load_file\fR\|(3),
834 \&\fBX509_STORE_load_locations\fR\|(3) and \fBX509_STORE_load_store\fR\|(3)
835 .PP
836 New functions that use a Library context
837 .IX Subsection "New functions that use a Library context"
838 .PP
839 The following functions can be passed a library context if required.
840 Passing NULL will use the default library context.
841 .IP \(bu 4
842 \&\fBBIO_new_from_core_bio\fR\|(3)
843 .IP \(bu 4
844 \&\fBEVP_ASYM_CIPHER_fetch\fR\|(3) and \fBEVP_ASYM_CIPHER_do_all_provided\fR\|(3)
845 .IP \(bu 4
846 \&\fBEVP_CIPHER_fetch\fR\|(3) and \fBEVP_CIPHER_do_all_provided\fR\|(3)
847 .IP \(bu 4
848 \&\fBEVP_default_properties_enable_fips\fR\|(3) and
849 \&\fBEVP_default_properties_is_fips_enabled\fR\|(3)
850 .IP \(bu 4
851 \&\fBEVP_KDF_fetch\fR\|(3) and \fBEVP_KDF_do_all_provided\fR\|(3)
852 .IP \(bu 4
853 \&\fBEVP_KEM_fetch\fR\|(3) and \fBEVP_KEM_do_all_provided\fR\|(3)
854 .IP \(bu 4
855 \&\fBEVP_KEYEXCH_fetch\fR\|(3) and \fBEVP_KEYEXCH_do_all_provided\fR\|(3)
856 .IP \(bu 4
857 \&\fBEVP_KEYMGMT_fetch\fR\|(3) and \fBEVP_KEYMGMT_do_all_provided\fR\|(3)
858 .IP \(bu 4
859 \&\fBEVP_MAC_fetch\fR\|(3) and \fBEVP_MAC_do_all_provided\fR\|(3)
860 .IP \(bu 4
861 \&\fBEVP_MD_fetch\fR\|(3) and \fBEVP_MD_do_all_provided\fR\|(3)
862 .IP \(bu 4
863 \&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3)
864 .IP \(bu 4
865 \&\fBEVP_PKEY_Q_keygen\fR\|(3)
866 .IP \(bu 4
867 \&\fBEVP_Q_mac\fR\|(3) and \fBEVP_Q_digest\fR\|(3)
868 .IP \(bu 4
869 \&\fBEVP_RAND\fR\|(3) and \fBEVP_RAND_do_all_provided\fR\|(3)
870 .IP \(bu 4
871 \&\fBEVP_set_default_properties\fR\|(3)
872 .IP \(bu 4
873 \&\fBEVP_SIGNATURE_fetch\fR\|(3) and \fBEVP_SIGNATURE_do_all_provided\fR\|(3)
874 .IP \(bu 4
875 \&\fBOSSL_CMP_CTX_new\fR\|(3) and \fBOSSL_CMP_SRV_CTX_new\fR\|(3)
876 .IP \(bu 4
877 \&\fBOSSL_CRMF_ENCRYPTEDVALUE_get1_encCert\fR\|(3)
878 .IP \(bu 4
879 \&\fBOSSL_CRMF_MSG_create_popo\fR\|(3) and \fBOSSL_CRMF_MSGS_verify_popo\fR\|(3)
880 .IP \(bu 4
881 \&\fBOSSL_CRMF_pbm_new\fR\|(3) and \fBOSSL_CRMF_pbmp_new\fR\|(3)
882 .IP \(bu 4
883 \&\fBOSSL_DECODER_CTX_add_extra\fR\|(3) and \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3)
884 .IP \(bu 4
885 \&\fBOSSL_DECODER_fetch\fR\|(3) and \fBOSSL_DECODER_do_all_provided\fR\|(3)
886 .IP \(bu 4
887 \&\fBOSSL_ENCODER_CTX_add_extra\fR\|(3)
888 .IP \(bu 4
889 \&\fBOSSL_ENCODER_fetch\fR\|(3) and \fBOSSL_ENCODER_do_all_provided\fR\|(3)
890 .IP \(bu 4
891 \&\fBOSSL_LIB_CTX_free\fR\|(3), \fBOSSL_LIB_CTX_load_config\fR\|(3) and \fBOSSL_LIB_CTX_set0_default\fR\|(3)
892 .IP \(bu 4
893 \&\fBOSSL_PROVIDER_add_builtin\fR\|(3), \fBOSSL_PROVIDER_available\fR\|(3),
894 \&\fBOSSL_PROVIDER_do_all\fR\|(3), \fBOSSL_PROVIDER_load\fR\|(3),
895 \&\fBOSSL_PROVIDER_set_default_search_path\fR\|(3) and \fBOSSL_PROVIDER_try_load\fR\|(3)
896 .IP \(bu 4
897 \&\fBOSSL_SELF_TEST_get_callback\fR\|(3) and \fBOSSL_SELF_TEST_set_callback\fR\|(3)
898 .IP \(bu 4
899 \&\fBOSSL_STORE_attach\fR\|(3)
900 .IP \(bu 4
901 \&\fBOSSL_STORE_LOADER_fetch\fR\|(3) and \fBOSSL_STORE_LOADER_do_all_provided\fR\|(3)
902 .IP \(bu 4
903 \&\fBRAND_get0_primary\fR\|(3), \fBRAND_get0_private\fR\|(3), \fBRAND_get0_public\fR\|(3),
904 \&\fBRAND_set_DRBG_type\fR\|(3) and \fBRAND_set_seed_source_type\fR\|(3)
905 .PP
906 \fIProviders\fR
907 .IX Subsection "Providers"
908 .PP
909 Providers are described in detail here "Providers" in \fBcrypto\fR\|(7).
910 See also "OPENSSL PROVIDERS" in \fBcrypto\fR\|(7).
911 .PP
912 \fIFetching algorithms and property queries\fR
913 .IX Subsection "Fetching algorithms and property queries"
914 .PP
915 Implicit and Explicit Fetching is described in detail here
916 "ALGORITHM FETCHING" in \fBcrypto\fR\|(7).
917 .PP
918 \fIMapping EVP controls and flags to provider \fR\f(BIOSSL_PARAM\fR\fI\|(3) parameters\fR
919 .IX Subsection "Mapping EVP controls and flags to provider OSSL_PARAM parameters"
920 .PP
921 The existing functions for controls (such as \fBEVP_CIPHER_CTX_ctrl\fR\|(3)) and
922 manipulating flags (such as \fBEVP_MD_CTX_set_flags\fR\|(3))internally use
923 \&\fBOSSL_PARAMS\fR to pass information to/from provider objects.
924 See \fBOSSL_PARAM\fR\|(3) for additional information related to parameters.
925 .PP
926 For ciphers see "CONTROLS" in \fBEVP_EncryptInit\fR\|(3), "FLAGS" in \fBEVP_EncryptInit\fR\|(3) and
927 "PARAMETERS" in \fBEVP_EncryptInit\fR\|(3).
928 .PP
929 For digests see "CONTROLS" in \fBEVP_DigestInit\fR\|(3), "FLAGS" in \fBEVP_DigestInit\fR\|(3) and
930 "PARAMETERS" in \fBEVP_DigestInit\fR\|(3).
931 .PP
932 \fIDeprecation of Low Level Functions\fR
933 .IX Subsection "Deprecation of Low Level Functions"
934 .PP
935 A significant number of APIs have been deprecated in OpenSSL 3.0.
936 This section describes some common categories of deprecations.
937 See "Deprecated function mappings" for the list of deprecated functions
938 that refer to these categories.
939 .PP
940 Providers are a replacement for engines and low-level method overrides
941 .IX Subsection "Providers are a replacement for engines and low-level method overrides"
942 .PP
943 Any accessor that uses an ENGINE is deprecated (such as \fBEVP_PKEY_set1_engine()\fR).
944 Applications using engines should instead use providers.
945 .PP
946 Before providers were added algorithms were overridden by changing the methods
947 used by algorithms. All these methods such as \fBRSA_new_method()\fR and \fBRSA_meth_new()\fR
948 are now deprecated and can be replaced by using providers instead.
949 .PP
950 Deprecated i2d and d2i functions for low-level key types
951 .IX Subsection "Deprecated i2d and d2i functions for low-level key types"
952 .PP
953 Any i2d and d2i functions such as \fBd2i_DHparams()\fR that take a low-level key type
954 have been deprecated. Applications should instead use the \fBOSSL_DECODER\fR\|(3) and
955 \&\fBOSSL_ENCODER\fR\|(3) APIs to read and write files.
956 See "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) for further details.
957 .PP
958 Deprecated low-level key object getters and setters
959 .IX Subsection "Deprecated low-level key object getters and setters"
960 .PP
961 Applications that set or get low-level key objects (such as \fBEVP_PKEY_set1_DH()\fR
962 or \fBEVP_PKEY_get0()\fR) should instead use the OSSL_ENCODER
963 (See \fBOSSL_ENCODER_to_bio\fR\|(3)) or OSSL_DECODER (See \fBOSSL_DECODER_from_bio\fR\|(3))
964 APIs, or alternatively use \fBEVP_PKEY_fromdata\fR\|(3) or \fBEVP_PKEY_todata\fR\|(3).
965 .PP
966 Deprecated low-level key parameter getters
967 .IX Subsection "Deprecated low-level key parameter getters"
968 .PP
969 Functions that access low-level objects directly such as \fBRSA_get0_n\fR\|(3) are now
970 deprecated. Applications should use one of:
971 \&\fBEVP_PKEY_get_bn_param\fR\|(3),
972 \&\fBEVP_PKEY_get_int_param\fR\|(3),
973 \&\fBEVP_PKEY_get_size_t_param\fR\|(3),
974 \&\fBEVP_PKEY_get_utf8_string_param\fR\|(3),
975 \&\fBEVP_PKEY_get_octet_string_param\fR\|(3), or
976 \&\fBEVP_PKEY_get_params\fR\|(3),
977 to access fields from an EVP_PKEY.
978 Gettable parameters are listed in:
979 "Common RSA parameters" in \fBEVP_PKEY\-RSA\fR\|(7),
980 "Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7),
981 "DSA parameters" in \fBEVP_PKEY\-DSA\fR\|(7),
982 "DH parameters" in \fBEVP_PKEY\-DH\fR\|(7),
983 "FFC parameters" in \fBEVP_PKEY\-FFC\fR\|(7),
984 "Common X25519, X448, ED25519 and ED448 parameters" in \fBEVP_PKEY\-X25519\fR\|(7),
985 "Common parameters" in \fBEVP_PKEY\-ML\-DSA\fR\|(7),
986 and
987 "Common parameters" in \fBEVP_PKEY\-ML\-KEM\fR\|(7).
988 Applications may also use \fBEVP_PKEY_todata\fR\|(3) to return all fields.
989 .PP
990 Deprecated low-level key parameter setters
991 .IX Subsection "Deprecated low-level key parameter setters"
992 .PP
993 Functions that access low-level objects directly such as \fBRSA_set0_crt_params\fR\|(3)
994 are now deprecated. Applications should use \fBEVP_PKEY_fromdata\fR\|(3) to create
995 new keys from user provided key data. Keys should be immutable once they are
996 created, so if required the user may use \fBEVP_PKEY_todata\fR\|(3), \fBOSSL_PARAM_merge\fR\|(3),
997 and \fBEVP_PKEY_fromdata\fR\|(3) to create a modified key.
998 See "Examples" in \fBEVP_PKEY\-DH\fR\|(7) for more information.
999 See "Deprecated low-level key generation functions" for information on
1000 generating a key using parameters.
1001 .PP
1002 Deprecated low-level object creation
1003 .IX Subsection "Deprecated low-level object creation"
1004 .PP
1005 Low-level objects were created using methods such as \fBRSA_new\fR\|(3),
1006 \&\fBRSA_up_ref\fR\|(3) and \fBRSA_free\fR\|(3). Applications should instead use the
1007 high-level EVP_PKEY APIs, e.g. \fBEVP_PKEY_new\fR\|(3), \fBEVP_PKEY_up_ref\fR\|(3) and
1008 \&\fBEVP_PKEY_free\fR\|(3).
1009 See also \fBEVP_PKEY_CTX_new_from_name\fR\|(3) and \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3).
1010 .PP
1011 EVP_PKEYs may be created in a variety of ways:
1012 See also "Deprecated low-level key generation functions",
1013 "Deprecated low-level key reading and writing functions" and
1014 "Deprecated low-level key parameter setters".
1015 .PP
1016 Deprecated low-level encryption functions
1017 .IX Subsection "Deprecated low-level encryption functions"
1018 .PP
1019 Low-level encryption functions such as \fBAES_encrypt\fR\|(3) and \fBAES_decrypt\fR\|(3)
1020 have been informally discouraged from use for a long time. Applications should
1021 instead use the high level EVP APIs \fBEVP_EncryptInit_ex\fR\|(3),
1022 \&\fBEVP_EncryptUpdate\fR\|(3), and \fBEVP_EncryptFinal_ex\fR\|(3) or
1023 \&\fBEVP_DecryptInit_ex\fR\|(3), \fBEVP_DecryptUpdate\fR\|(3) and \fBEVP_DecryptFinal_ex\fR\|(3).
1024 .PP
1025 Deprecated low-level digest functions
1026 .IX Subsection "Deprecated low-level digest functions"
1027 .PP
1028 Use of low-level digest functions such as \fBSHA1_Init\fR\|(3) have been
1029 informally discouraged from use for a long time. Applications should instead
1030 use the high level EVP APIs \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3)
1031 and \fBEVP_DigestFinal_ex\fR\|(3), or the quick one-shot \fBEVP_Q_digest\fR\|(3).
1032 .PP
1033 Note that the functions \fBSHA1\fR\|(3), \fBSHA224\fR\|(3), \fBSHA256\fR\|(3), \fBSHA384\fR\|(3)
1034 and \fBSHA512\fR\|(3) have changed to macros that use \fBEVP_Q_digest\fR\|(3).
1035 .PP
1036 Deprecated low-level signing functions
1037 .IX Subsection "Deprecated low-level signing functions"
1038 .PP
1039 Use of low-level signing functions such as \fBDSA_sign\fR\|(3) have been
1040 informally discouraged for a long time. Instead applications should use
1041 \&\fBEVP_DigestSign\fR\|(3) and \fBEVP_DigestVerify\fR\|(3).
1042 See also \fBEVP_SIGNATURE\-RSA\fR\|(7), \fBEVP_SIGNATURE\-DSA\fR\|(7),
1043 \&\fBEVP_SIGNATURE\-ECDSA\fR\|(7) and \fBEVP_SIGNATURE\-ED25519\fR\|(7).
1044 .PP
1045 Deprecated low-level MAC functions
1046 .IX Subsection "Deprecated low-level MAC functions"
1047 .PP
1048 Low-level mac functions such as \fBCMAC_Init\fR\|(3) are deprecated.
1049 Applications should instead use the new \fBEVP_MAC\fR\|(3) interface, using
1050 \&\fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), \fBEVP_MAC_init\fR\|(3),
1051 \&\fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3) or the single-shot MAC function
1052 \&\fBEVP_Q_mac\fR\|(3).
1053 See \fBEVP_MAC\fR\|(3), \fBEVP_MAC\-HMAC\fR\|(7), \fBEVP_MAC\-CMAC\fR\|(7), \fBEVP_MAC\-GMAC\fR\|(7),
1054 \&\fBEVP_MAC\-KMAC\fR\|(7), \fBEVP_MAC\-BLAKE2\fR\|(7), \fBEVP_MAC\-Poly1305\fR\|(7) and
1055 \&\fBEVP_MAC\-Siphash\fR\|(7) for additional information.
1056 .PP
1057 Note that the one-shot method \fBHMAC()\fR is still available for compatibility purposes,
1058 but this can also be replaced by using EVP_Q_MAC if a library context is required.
1059 .PP
1060 Deprecated low-level validation functions
1061 .IX Subsection "Deprecated low-level validation functions"
1062 .PP
1063 Low-level validation functions such as \fBDH_check\fR\|(3) have been informally
1064 discouraged from use for a long time. Applications should instead use the high-level
1065 EVP_PKEY APIs such as \fBEVP_PKEY_check\fR\|(3), \fBEVP_PKEY_param_check\fR\|(3),
1066 \&\fBEVP_PKEY_param_check_quick\fR\|(3), \fBEVP_PKEY_public_check\fR\|(3),
1067 \&\fBEVP_PKEY_public_check_quick\fR\|(3), \fBEVP_PKEY_private_check\fR\|(3),
1068 and \fBEVP_PKEY_pairwise_check\fR\|(3).
1069 .PP
1070 Deprecated low-level key exchange functions
1071 .IX Subsection "Deprecated low-level key exchange functions"
1072 .PP
1073 Many low-level functions have been informally discouraged from use for a long
1074 time. Applications should instead use \fBEVP_PKEY_derive\fR\|(3).
1075 See \fBEVP_KEYEXCH\-DH\fR\|(7), \fBEVP_KEYEXCH\-ECDH\fR\|(7) and \fBEVP_KEYEXCH\-X25519\fR\|(7).
1076 .PP
1077 Deprecated low-level key generation functions
1078 .IX Subsection "Deprecated low-level key generation functions"
1079 .PP
1080 Many low-level functions have been informally discouraged from use for a long
1081 time. Applications should instead use \fBEVP_PKEY_keygen_init\fR\|(3) and
1082 \&\fBEVP_PKEY_generate\fR\|(3) as described in \fBEVP_PKEY\-DSA\fR\|(7), \fBEVP_PKEY\-DH\fR\|(7),
1083 \&\fBEVP_PKEY\-RSA\fR\|(7), \fBEVP_PKEY\-EC\fR\|(7) and \fBEVP_PKEY\-X25519\fR\|(7).
1084 The 'quick' one-shot function \fBEVP_PKEY_Q_keygen\fR\|(3) and macros for the most
1085 common cases: <\fBEVP_RSA_gen\fR\|(3)> and \fBEVP_EC_gen\fR\|(3) may also be used.
1086 .PP
1087 Deprecated low-level key reading and writing functions
1088 .IX Subsection "Deprecated low-level key reading and writing functions"
1089 .PP
1090 Use of low-level objects (such as DSA) has been informally discouraged from use
1091 for a long time. Functions to read and write these low-level objects (such as
1092 \&\fBPEM_read_DSA_PUBKEY()\fR) should be replaced. Applications should instead use
1093 \&\fBOSSL_ENCODER_to_bio\fR\|(3) and \fBOSSL_DECODER_from_bio\fR\|(3).
1094 .PP
1095 Deprecated low-level key printing functions
1096 .IX Subsection "Deprecated low-level key printing functions"
1097 .PP
1098 Use of low-level objects (such as DSA) has been informally discouraged from use
1099 for a long time. Functions to print these low-level objects such as
1100 \&\fBDSA_print()\fR should be replaced with the equivalent EVP_PKEY functions.
1101 Application should use one of \fBEVP_PKEY_print_public\fR\|(3),
1102 \&\fBEVP_PKEY_print_private\fR\|(3), \fBEVP_PKEY_print_params\fR\|(3),
1103 \&\fBEVP_PKEY_print_public_fp\fR\|(3), \fBEVP_PKEY_print_private_fp\fR\|(3) or
1104 \&\fBEVP_PKEY_print_params_fp\fR\|(3). Note that internally these use
1105 \&\fBOSSL_ENCODER_to_bio\fR\|(3) and \fBOSSL_DECODER_from_bio\fR\|(3).
1106 .PP
1107 \fIDeprecated function mappings\fR
1108 .IX Subsection "Deprecated function mappings"
1109 .PP
1110 The following functions have been deprecated in 3.0.
1111 .IP \(bu 4
1112 \&\fBAES_bi_ige_encrypt()\fR and \fBAES_ige_encrypt()\fR
1113 .Sp
1114 There is no replacement for the IGE functions. New code should not use these modes.
1115 These undocumented functions were never integrated into the EVP layer.
1116 They implemented the AES Infinite Garble Extension (IGE) mode and AES
1117 Bi-directional IGE mode. These modes were never formally standardised and
1118 usage of these functions is believed to be very small. In particular
1119 \&\fBAES_bi_ige_encrypt()\fR has a known bug. It accepts 2 AES keys, but only one
1120 is ever used. The security implications are believed to be minimal, but
1121 this issue was never fixed for backwards compatibility reasons.
1122 .IP \(bu 4
1123 \&\fBAES_encrypt()\fR, \fBAES_decrypt()\fR, \fBAES_set_encrypt_key()\fR, \fBAES_set_decrypt_key()\fR,
1124 \&\fBAES_cbc_encrypt()\fR, \fBAES_cfb128_encrypt()\fR, \fBAES_cfb1_encrypt()\fR, \fBAES_cfb8_encrypt()\fR,
1125 \&\fBAES_ecb_encrypt()\fR, \fBAES_ofb128_encrypt()\fR
1126 .IP \(bu 4
1127 \&\fBAES_unwrap_key()\fR, \fBAES_wrap_key()\fR
1128 .Sp
1129 See "Deprecated low-level encryption functions"
1130 .IP \(bu 4
1131 \&\fBAES_options()\fR
1132 .Sp
1133 There is no replacement. It returned a string indicating if the AES code was unrolled.
1134 .IP \(bu 4
1135 \&\fBASN1_digest()\fR, \fBASN1_sign()\fR, \fBASN1_verify()\fR
1136 .Sp
1137 There are no replacements. These old functions are not used, and could be
1138 disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7.
1139 .IP \(bu 4
1140 \&\fBASN1_STRING_length_set()\fR
1141 .Sp
1142 Use \fBASN1_STRING_set\fR\|(3) or \fBASN1_STRING_set0\fR\|(3) instead.
1143 This was a potentially unsafe function that could change the bounds of a
1144 previously passed in pointer.
1145 .IP \(bu 4
1146 \&\fBBF_encrypt()\fR, \fBBF_decrypt()\fR, \fBBF_set_key()\fR, \fBBF_cbc_encrypt()\fR, \fBBF_cfb64_encrypt()\fR,
1147 \&\fBBF_ecb_encrypt()\fR, \fBBF_ofb64_encrypt()\fR
1148 .Sp
1149 See "Deprecated low-level encryption functions".
1150 The Blowfish algorithm has been moved to the Legacy Provider.
1151 .IP \(bu 4
1152 \&\fBBF_options()\fR
1153 .Sp
1154 There is no replacement. This option returned a constant string.
1155 .IP \(bu 4
1156 \&\fBBIO_get_callback()\fR, \fBBIO_set_callback()\fR, \fBBIO_debug_callback()\fR
1157 .Sp
1158 Use the respective non-deprecated \fB_ex()\fR functions.
1159 .IP \(bu 4
1160 \&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR
1161 .Sp
1162 Use \fBBN_check_prime\fR\|(3) which avoids possible misuse and always uses at least
1163 64 rounds of the Miller-Rabin primality test.
1164 .IP \(bu 4
1165 \&\fBBN_pseudo_rand()\fR, \fBBN_pseudo_rand_range()\fR
1166 .Sp
1167 Use \fBBN_rand\fR\|(3) and \fBBN_rand_range\fR\|(3).
1168 .IP \(bu 4
1169 \&\fBBN_X931_derive_prime_ex()\fR, \fBBN_X931_generate_prime_ex()\fR, \fBBN_X931_generate_Xpq()\fR
1170 .Sp
1171 There are no replacements for these low-level functions. They were used internally
1172 by \fBRSA_X931_derive_ex()\fR and \fBRSA_X931_generate_key_ex()\fR which are also deprecated.
1173 Use \fBEVP_PKEY_keygen\fR\|(3) instead.
1174 .IP \(bu 4
1175 \&\fBCamellia_encrypt()\fR, \fBCamellia_decrypt()\fR, \fBCamellia_set_key()\fR,
1176 \&\fBCamellia_cbc_encrypt()\fR, \fBCamellia_cfb128_encrypt()\fR, \fBCamellia_cfb1_encrypt()\fR,
1177 \&\fBCamellia_cfb8_encrypt()\fR, \fBCamellia_ctr128_encrypt()\fR, \fBCamellia_ecb_encrypt()\fR,
1178 \&\fBCamellia_ofb128_encrypt()\fR
1179 .Sp
1180 See "Deprecated low-level encryption functions".
1181 .IP \(bu 4
1182 \&\fBCAST_encrypt()\fR, \fBCAST_decrypt()\fR, \fBCAST_set_key()\fR, \fBCAST_cbc_encrypt()\fR,
1183 \&\fBCAST_cfb64_encrypt()\fR, \fBCAST_ecb_encrypt()\fR, \fBCAST_ofb64_encrypt()\fR
1184 .Sp
1185 See "Deprecated low-level encryption functions".
1186 The CAST algorithm has been moved to the Legacy Provider.
1187 .IP \(bu 4
1188 \&\fBCMAC_CTX_new()\fR, \fBCMAC_CTX_cleanup()\fR, \fBCMAC_CTX_copy()\fR, \fBCMAC_CTX_free()\fR,
1189 \&\fBCMAC_CTX_get0_cipher_ctx()\fR
1190 .Sp
1191 See "Deprecated low-level MAC functions".
1192 .IP \(bu 4
1193 \&\fBCMAC_Init()\fR, \fBCMAC_Update()\fR, \fBCMAC_Final()\fR, \fBCMAC_resume()\fR
1194 .Sp
1195 See "Deprecated low-level MAC functions".
1196 .IP \(bu 4
1197 \&\fBCRYPTO_mem_ctrl()\fR, \fBCRYPTO_mem_debug_free()\fR, \fBCRYPTO_mem_debug_malloc()\fR,
1198 \&\fBCRYPTO_mem_debug_pop()\fR, \fBCRYPTO_mem_debug_push()\fR, \fBCRYPTO_mem_debug_realloc()\fR,
1199 \&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_cb()\fR, \fBCRYPTO_mem_leaks_fp()\fR,
1200 \&\fBCRYPTO_set_mem_debug()\fR
1201 .Sp
1202 Memory-leak checking has been deprecated in favor of more modern development
1203 tools, such as compiler memory and leak sanitizers or Valgrind.
1204 .IP \(bu 4
1205 \&\fBCRYPTO_cts128_encrypt_block()\fR, \fBCRYPTO_cts128_encrypt()\fR,
1206 \&\fBCRYPTO_cts128_decrypt_block()\fR, \fBCRYPTO_cts128_decrypt()\fR,
1207 \&\fBCRYPTO_nistcts128_encrypt_block()\fR, \fBCRYPTO_nistcts128_encrypt()\fR,
1208 \&\fBCRYPTO_nistcts128_decrypt_block()\fR, \fBCRYPTO_nistcts128_decrypt()\fR
1209 .Sp
1210 Use the higher level functions \fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherUpdate()\fR and
1211 \&\fBEVP_CipherFinal_ex()\fR instead.
1212 See the "cts_mode" parameter in
1213 "Gettable and Settable EVP_CIPHER_CTX parameters" in \fBEVP_EncryptInit\fR\|(3).
1214 See "EXAMPLES" in \fBEVP_EncryptInit\fR\|(3) for a AES\-256\-CBC\-CTS example.
1215 .IP \(bu 4
1216 \&\fBd2i_DHparams()\fR, \fBd2i_DHxparams()\fR, \fBd2i_DSAparams()\fR, \fBd2i_DSAPrivateKey()\fR,
1217 \&\fBd2i_DSAPrivateKey_bio()\fR, \fBd2i_DSAPrivateKey_fp()\fR, \fBd2i_DSA_PUBKEY()\fR,
1218 \&\fBd2i_DSA_PUBKEY_bio()\fR, \fBd2i_DSA_PUBKEY_fp()\fR, \fBd2i_DSAPublicKey()\fR,
1219 \&\fBd2i_ECParameters()\fR, \fBd2i_ECPrivateKey()\fR, \fBd2i_ECPrivateKey_bio()\fR,
1220 \&\fBd2i_ECPrivateKey_fp()\fR, \fBd2i_EC_PUBKEY()\fR, \fBd2i_EC_PUBKEY_bio()\fR,
1221 \&\fBd2i_EC_PUBKEY_fp()\fR, \fBd2i_RSAPrivateKey()\fR,
1222 \&\fBd2i_RSAPrivateKey_bio()\fR, \fBd2i_RSAPrivateKey_fp()\fR, \fBd2i_RSA_PUBKEY()\fR,
1223 \&\fBd2i_RSA_PUBKEY_bio()\fR, \fBd2i_RSA_PUBKEY_fp()\fR, \fBd2i_RSAPublicKey()\fR,
1224 \&\fBd2i_RSAPublicKey_bio()\fR, \fBd2i_RSAPublicKey_fp()\fR
1225 .Sp
1226 See "Deprecated i2d and d2i functions for low-level key types"
1227 .IP \(bu 4
1228 \&\fBo2i_ECPublicKey()\fR
1229 .Sp
1230 Use \fBEVP_PKEY_set1_encoded_public_key\fR\|(3).
1231 See "Deprecated low-level key parameter setters"
1232 .IP \(bu 4
1233 \&\fBDES_crypt()\fR, \fBDES_fcrypt()\fR, \fBDES_encrypt1()\fR, \fBDES_encrypt2()\fR, \fBDES_encrypt3()\fR,
1234 \&\fBDES_decrypt3()\fR, \fBDES_ede3_cbc_encrypt()\fR, \fBDES_ede3_cfb64_encrypt()\fR,
1235 \&\fBDES_ede3_cfb_encrypt()\fR,\fBDES_ede3_ofb64_encrypt()\fR,
1236 \&\fBDES_ecb_encrypt()\fR, \fBDES_ecb3_encrypt()\fR, \fBDES_ofb64_encrypt()\fR, \fBDES_ofb_encrypt()\fR,
1237 DES_cfb64_encrypt \fBDES_cfb_encrypt()\fR, \fBDES_cbc_encrypt()\fR, \fBDES_ncbc_encrypt()\fR,
1238 \&\fBDES_pcbc_encrypt()\fR, \fBDES_xcbc_encrypt()\fR, \fBDES_cbc_cksum()\fR, \fBDES_quad_cksum()\fR,
1239 \&\fBDES_check_key_parity()\fR, \fBDES_is_weak_key()\fR, \fBDES_key_sched()\fR, \fBDES_options()\fR,
1240 \&\fBDES_random_key()\fR, \fBDES_set_key()\fR, \fBDES_set_key_checked()\fR, \fBDES_set_key_unchecked()\fR,
1241 \&\fBDES_set_odd_parity()\fR, \fBDES_string_to_2keys()\fR, \fBDES_string_to_key()\fR
1242 .Sp
1243 See "Deprecated low-level encryption functions".
1244 Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB",
1245 "DES\-CFB1" and "DES\-CFB8" have been moved to the Legacy Provider.
1246 .IP \(bu 4
1247 \&\fBDH_bits()\fR, \fBDH_security_bits()\fR, \fBDH_size()\fR
1248 .Sp
1249 Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and
1250 \&\fBEVP_PKEY_get_size\fR\|(3).
1251 .IP \(bu 4
1252 \&\fBDH_check()\fR, \fBDH_check_ex()\fR, \fBDH_check_params()\fR, \fBDH_check_params_ex()\fR,
1253 \&\fBDH_check_pub_key()\fR, \fBDH_check_pub_key_ex()\fR
1254 .Sp
1255 See "Deprecated low-level validation functions"
1256 .IP \(bu 4
1257 \&\fBDH_clear_flags()\fR, \fBDH_test_flags()\fR, \fBDH_set_flags()\fR
1258 .Sp
1259 The \fBDH_FLAG_CACHE_MONT_P\fR flag has been deprecated without replacement.
1260 The \fBDH_FLAG_TYPE_DH\fR and \fBDH_FLAG_TYPE_DHX\fR have been deprecated.
1261 Use \fBEVP_PKEY_is_a()\fR to determine the type of a key.
1262 There is no replacement for setting these flags.
1263 .IP \(bu 4
1264 \&\fBDH_compute_key()\fR \fBDH_compute_key_padded()\fR
1265 .Sp
1266 See "Deprecated low-level key exchange functions".
1267 .IP \(bu 4
1268 \&\fBDH_new()\fR, \fBDH_new_by_nid()\fR, \fBDH_free()\fR, \fBDH_up_ref()\fR
1269 .Sp
1270 See "Deprecated low-level object creation"
1271 .IP \(bu 4
1272 \&\fBDH_generate_key()\fR, \fBDH_generate_parameters_ex()\fR
1273 .Sp
1274 See "Deprecated low-level key generation functions".
1275 .IP \(bu 4
1276 \&\fBDH_get0_pqg()\fR, \fBDH_get0_p()\fR, \fBDH_get0_q()\fR, \fBDH_get0_g()\fR, \fBDH_get0_key()\fR,
1277 \&\fBDH_get0_priv_key()\fR, \fBDH_get0_pub_key()\fR, \fBDH_get_length()\fR, \fBDH_get_nid()\fR
1278 .Sp
1279 See "Deprecated low-level key parameter getters"
1280 .IP \(bu 4
1281 \&\fBDH_get_1024_160()\fR, \fBDH_get_2048_224()\fR, \fBDH_get_2048_256()\fR
1282 .Sp
1283 Applications should instead set the \fBOSSL_PKEY_PARAM_GROUP_NAME\fR as specified in
1284 "DH parameters" in \fBEVP_PKEY\-DH\fR\|(7)) to one of "dh_1024_160", "dh_2048_224" or
1285 "dh_2048_256" when generating a DH key.
1286 .IP \(bu 4
1287 \&\fBDH_KDF_X9_42()\fR
1288 .Sp
1289 Applications should use \fBEVP_PKEY_CTX_set_dh_kdf_type\fR\|(3) instead.
1290 .IP \(bu 4
1291 \&\fBDH_get_default_method()\fR, \fBDH_get0_engine()\fR, DH_meth_*(), \fBDH_new_method()\fR,
1292 \&\fBDH_OpenSSL()\fR, \fBDH_get_ex_data()\fR, \fBDH_set_default_method()\fR, \fBDH_set_method()\fR,
1293 \&\fBDH_set_ex_data()\fR
1294 .Sp
1295 See "Providers are a replacement for engines and low-level method overrides"
1296 .IP \(bu 4
1297 \&\fBDHparams_print()\fR, \fBDHparams_print_fp()\fR
1298 .Sp
1299 See "Deprecated low-level key printing functions"
1300 .IP \(bu 4
1301 \&\fBDH_set0_key()\fR, \fBDH_set0_pqg()\fR, \fBDH_set_length()\fR
1302 .Sp
1303 See "Deprecated low-level key parameter setters"
1304 .IP \(bu 4
1305 \&\fBDSA_bits()\fR, \fBDSA_security_bits()\fR, \fBDSA_size()\fR
1306 .Sp
1307 Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and
1308 \&\fBEVP_PKEY_get_size\fR\|(3).
1309 .IP \(bu 4
1310 \&\fBDHparams_dup()\fR, \fBDSA_dup_DH()\fR
1311 .Sp
1312 There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3)
1313 and \fBEVP_PKEY_dup\fR\|(3) instead.
1314 .IP \(bu 4
1315 \&\fBDSA_generate_key()\fR, \fBDSA_generate_parameters_ex()\fR
1316 .Sp
1317 See "Deprecated low-level key generation functions".
1318 .IP \(bu 4
1319 \&\fBDSA_get0_engine()\fR, \fBDSA_get_default_method()\fR, \fBDSA_get_ex_data()\fR,
1320 \&\fBDSA_get_method()\fR, DSA_meth_*(), \fBDSA_new_method()\fR, \fBDSA_OpenSSL()\fR,
1321 \&\fBDSA_set_default_method()\fR, \fBDSA_set_ex_data()\fR, \fBDSA_set_method()\fR
1322 .Sp
1323 See "Providers are a replacement for engines and low-level method overrides".
1324 .IP \(bu 4
1325 \&\fBDSA_get0_p()\fR, \fBDSA_get0_q()\fR, \fBDSA_get0_g()\fR, \fBDSA_get0_pqg()\fR, \fBDSA_get0_key()\fR,
1326 \&\fBDSA_get0_priv_key()\fR, \fBDSA_get0_pub_key()\fR
1327 .Sp
1328 See "Deprecated low-level key parameter getters".
1329 .IP \(bu 4
1330 \&\fBDSA_new()\fR, \fBDSA_free()\fR, \fBDSA_up_ref()\fR
1331 .Sp
1332 See "Deprecated low-level object creation"
1333 .IP \(bu 4
1334 \&\fBDSAparams_dup()\fR
1335 .Sp
1336 There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3)
1337 and \fBEVP_PKEY_dup\fR\|(3) instead.
1338 .IP \(bu 4
1339 \&\fBDSAparams_print()\fR, \fBDSAparams_print_fp()\fR, \fBDSA_print()\fR, \fBDSA_print_fp()\fR
1340 .Sp
1341 See "Deprecated low-level key printing functions"
1342 .IP \(bu 4
1343 \&\fBDSA_set0_key()\fR, \fBDSA_set0_pqg()\fR
1344 .Sp
1345 See "Deprecated low-level key parameter setters"
1346 .IP \(bu 4
1347 \&\fBDSA_set_flags()\fR, \fBDSA_clear_flags()\fR, \fBDSA_test_flags()\fR
1348 .Sp
1349 The \fBDSA_FLAG_CACHE_MONT_P\fR flag has been deprecated without replacement.
1350 .IP \(bu 4
1351 \&\fBDSA_sign()\fR, \fBDSA_do_sign()\fR, \fBDSA_sign_setup()\fR, \fBDSA_verify()\fR, \fBDSA_do_verify()\fR
1352 .Sp
1353 See "Deprecated low-level signing functions".
1354 .IP \(bu 4
1355 \&\fBECDH_compute_key()\fR
1356 .Sp
1357 See "Deprecated low-level key exchange functions".
1358 .IP \(bu 4
1359 \&\fBECDH_KDF_X9_62()\fR
1360 .Sp
1361 Applications may either set this using the helper function
1362 \&\fBEVP_PKEY_CTX_set_ecdh_kdf_type\fR\|(3) or by setting an \fBOSSL_PARAM\fR\|(3) using the
1363 "kdf-type" as shown in "EXAMPLES" in \fBEVP_KEYEXCH\-ECDH\fR\|(7)
1364 .IP \(bu 4
1365 \&\fBECDSA_sign()\fR, \fBECDSA_sign_ex()\fR, \fBECDSA_sign_setup()\fR, \fBECDSA_do_sign()\fR,
1366 \&\fBECDSA_do_sign_ex()\fR, \fBECDSA_verify()\fR, \fBECDSA_do_verify()\fR
1367 .Sp
1368 See "Deprecated low-level signing functions".
1369 .IP \(bu 4
1370 \&\fBECDSA_size()\fR
1371 .Sp
1372 Applications should use \fBEVP_PKEY_get_size\fR\|(3).
1373 .IP \(bu 4
1374 \&\fBEC_GF2m_simple_method()\fR, \fBEC_GFp_mont_method()\fR, \fBEC_GFp_nist_method()\fR,
1375 \&\fBEC_GFp_nistp224_method()\fR, \fBEC_GFp_nistp256_method()\fR, \fBEC_GFp_nistp521_method()\fR,
1376 \&\fBEC_GFp_simple_method()\fR
1377 .Sp
1378 There are no replacements for these functions. Applications should rely on the
1379 library automatically assigning a suitable method internally when an EC_GROUP
1380 is constructed.
1381 .IP \(bu 4
1382 \&\fBEC_GROUP_clear_free()\fR
1383 .Sp
1384 Use \fBEC_GROUP_free\fR\|(3) instead.
1385 .IP \(bu 4
1386 \&\fBEC_GROUP_get_curve_GF2m()\fR, \fBEC_GROUP_get_curve_GFp()\fR, \fBEC_GROUP_set_curve_GF2m()\fR,
1387 \&\fBEC_GROUP_set_curve_GFp()\fR
1388 .Sp
1389 Applications should use \fBEC_GROUP_get_curve\fR\|(3) and \fBEC_GROUP_set_curve\fR\|(3).
1390 .IP \(bu 4
1391 \&\fBEC_GROUP_have_precompute_mult()\fR, \fBEC_GROUP_precompute_mult()\fR,
1392 \&\fBEC_KEY_precompute_mult()\fR
1393 .Sp
1394 These functions are not widely used. Applications should instead switch to
1395 named curves which OpenSSL has hardcoded lookup tables for.
1396 .IP \(bu 4
1397 \&\fBEC_GROUP_new()\fR, \fBEC_GROUP_method_of()\fR, \fBEC_POINT_method_of()\fR
1398 .Sp
1399 EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned
1400 internally without application intervention.
1401 Users of \fBEC_GROUP_new()\fR should switch to a different suitable constructor.
1402 .IP \(bu 4
1403 \&\fBEC_KEY_can_sign()\fR
1404 .Sp
1405 Applications should use \fBEVP_PKEY_can_sign\fR\|(3) instead.
1406 .IP \(bu 4
1407 \&\fBEC_KEY_check_key()\fR
1408 .Sp
1409 See "Deprecated low-level validation functions"
1410 .IP \(bu 4
1411 \&\fBEC_KEY_set_flags()\fR, \fBEC_KEY_get_flags()\fR, \fBEC_KEY_clear_flags()\fR
1412 .Sp
1413 See "Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7) which handles flags as separate
1414 parameters for \fBOSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\fR,
1415 \&\fBOSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\fR, \fBOSSL_PKEY_PARAM_EC_ENCODING\fR,
1416 \&\fBOSSL_PKEY_PARAM_USE_COFACTOR_ECDH\fR and
1417 \&\fBOSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\fR.
1418 See also "EXAMPLES" in \fBEVP_PKEY\-EC\fR\|(7)
1419 .IP \(bu 4
1420 \&\fBEC_KEY_dup()\fR, \fBEC_KEY_copy()\fR
1421 .Sp
1422 There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3)
1423 and \fBEVP_PKEY_dup\fR\|(3) instead.
1424 .IP \(bu 4
1425 \&\fBEC_KEY_decoded_from_explicit_params()\fR
1426 .Sp
1427 There is no replacement.
1428 .IP \(bu 4
1429 \&\fBEC_KEY_generate_key()\fR
1430 .Sp
1431 See "Deprecated low-level key generation functions".
1432 .IP \(bu 4
1433 \&\fBEC_KEY_get0_group()\fR, \fBEC_KEY_get0_private_key()\fR, \fBEC_KEY_get0_public_key()\fR,
1434 \&\fBEC_KEY_get_conv_form()\fR, \fBEC_KEY_get_enc_flags()\fR
1435 .Sp
1436 See "Deprecated low-level key parameter getters".
1437 .IP \(bu 4
1438 \&\fBEC_KEY_get0_engine()\fR, \fBEC_KEY_get_default_method()\fR, \fBEC_KEY_get_method()\fR,
1439 \&\fBEC_KEY_new_method()\fR, \fBEC_KEY_get_ex_data()\fR, \fBEC_KEY_OpenSSL()\fR,
1440 \&\fBEC_KEY_set_ex_data()\fR, \fBEC_KEY_set_default_method()\fR, EC_KEY_METHOD_*(),
1441 \&\fBEC_KEY_set_method()\fR
1442 .Sp
1443 See "Providers are a replacement for engines and low-level method overrides"
1444 .IP \(bu 4
1445 \&\fBEC_METHOD_get_field_type()\fR
1446 .Sp
1447 Use \fBEC_GROUP_get_field_type\fR\|(3) instead.
1448 See "Providers are a replacement for engines and low-level method overrides"
1449 .IP \(bu 4
1450 \&\fBEC_KEY_key2buf()\fR, \fBEC_KEY_oct2key()\fR, \fBEC_KEY_oct2priv()\fR, \fBEC_KEY_priv2buf()\fR,
1451 \&\fBEC_KEY_priv2oct()\fR
1452 .Sp
1453 There are no replacements for these.
1454 .IP \(bu 4
1455 \&\fBEC_KEY_new()\fR, \fBEC_KEY_new_by_curve_name()\fR, \fBEC_KEY_free()\fR, \fBEC_KEY_up_ref()\fR
1456 .Sp
1457 See "Deprecated low-level object creation"
1458 .IP \(bu 4
1459 \&\fBEC_KEY_print()\fR, \fBEC_KEY_print_fp()\fR
1460 .Sp
1461 See "Deprecated low-level key printing functions"
1462 .IP \(bu 4
1463 \&\fBEC_KEY_set_asn1_flag()\fR, \fBEC_KEY_set_conv_form()\fR, \fBEC_KEY_set_enc_flags()\fR
1464 .Sp
1465 See "Deprecated low-level key parameter setters".
1466 .IP \(bu 4
1467 \&\fBEC_KEY_set_group()\fR, \fBEC_KEY_set_private_key()\fR, \fBEC_KEY_set_public_key()\fR,
1468 \&\fBEC_KEY_set_public_key_affine_coordinates()\fR
1469 .Sp
1470 See "Deprecated low-level key parameter setters".
1471 .IP \(bu 4
1472 \&\fBECParameters_print()\fR, \fBECParameters_print_fp()\fR, \fBECPKParameters_print()\fR,
1473 \&\fBECPKParameters_print_fp()\fR
1474 .Sp
1475 See "Deprecated low-level key printing functions"
1476 .IP \(bu 4
1477 \&\fBEC_POINT_bn2point()\fR, \fBEC_POINT_point2bn()\fR
1478 .Sp
1479 These functions were not particularly useful, since EC point serialization
1480 formats are not individual big-endian integers.
1481 .IP \(bu 4
1482 \&\fBEC_POINT_get_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR,
1483 \&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_set_affine_coordinates_GFp()\fR
1484 .Sp
1485 Applications should use \fBEC_POINT_get_affine_coordinates\fR\|(3) and
1486 \&\fBEC_POINT_set_affine_coordinates\fR\|(3) instead.
1487 .IP \(bu 4
1488 \&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR, \fBEC_POINT_set_Jprojective_coordinates_GFp()\fR
1489 .Sp
1490 These functions are not widely used. Applications should instead use the
1491 \&\fBEC_POINT_set_affine_coordinates\fR\|(3) and \fBEC_POINT_get_affine_coordinates\fR\|(3)
1492 functions.
1493 .IP \(bu 4
1494 \&\fBEC_POINT_make_affine()\fR, \fBEC_POINTs_make_affine()\fR
1495 .Sp
1496 There is no replacement. These functions were not widely used, and OpenSSL
1497 automatically performs this conversion when needed.
1498 .IP \(bu 4
1499 \&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR, \fBEC_POINT_set_compressed_coordinates_GFp()\fR
1500 .Sp
1501 Applications should use \fBEC_POINT_set_compressed_coordinates\fR\|(3) instead.
1502 .IP \(bu 4
1503 \&\fBEC_POINTs_mul()\fR
1504 .Sp
1505 This function is not widely used. Applications should instead use the
1506 \&\fBEC_POINT_mul\fR\|(3) function.
1507 .IP \(bu 4
1508 \&\fBENGINE_*()\fR
1509 .Sp
1510 All engine functions are deprecated. An engine should be rewritten as a provider.
1511 See "Providers are a replacement for engines and low-level method overrides".
1512 .IP \(bu 4
1513 \&\fBERR_load_*()\fR, \fBERR_func_error_string()\fR, \fBERR_get_error_line()\fR,
1514 \&\fBERR_get_error_line_data()\fR, \fBERR_get_state()\fR
1515 .Sp
1516 OpenSSL now loads error strings automatically so these functions are not needed.
1517 .IP \(bu 4
1518 \&\fBERR_peek_error_line_data()\fR, \fBERR_peek_last_error_line_data()\fR
1519 .Sp
1520 The new functions are \fBERR_peek_error_func\fR\|(3), \fBERR_peek_last_error_func\fR\|(3),
1521 \&\fBERR_peek_error_data\fR\|(3), \fBERR_peek_last_error_data\fR\|(3), \fBERR_get_error_all\fR\|(3),
1522 \&\fBERR_peek_error_all\fR\|(3) and \fBERR_peek_last_error_all\fR\|(3).
1523 Applications should use \fBERR_get_error_all\fR\|(3), or pick information
1524 with ERR_peek functions and finish off with getting the error code by using
1525 \&\fBERR_get_error\fR\|(3).
1526 .IP \(bu 4
1527 \&\fBEVP_CIPHER_CTX_iv()\fR, \fBEVP_CIPHER_CTX_iv_noconst()\fR, \fBEVP_CIPHER_CTX_original_iv()\fR
1528 .Sp
1529 Applications should instead use \fBEVP_CIPHER_CTX_get_updated_iv\fR\|(3),
1530 \&\fBEVP_CIPHER_CTX_get_updated_iv\fR\|(3) and \fBEVP_CIPHER_CTX_get_original_iv\fR\|(3)
1531 respectively.
1532 See \fBEVP_CIPHER_CTX_get_original_iv\fR\|(3) for further information.
1533 .IP \(bu 4
1534 \&\fBEVP_CIPHER_meth_*()\fR, \fBEVP_MD_CTX_set_update_fn()\fR, \fBEVP_MD_CTX_update_fn()\fR,
1535 \&\fBEVP_MD_meth_*()\fR
1536 .Sp
1537 See "Providers are a replacement for engines and low-level method overrides".
1538 .IP \(bu 4
1539 \&\fBEVP_PKEY_CTRL_PKCS7_ENCRYPT()\fR, \fBEVP_PKEY_CTRL_PKCS7_DECRYPT()\fR,
1540 \&\fBEVP_PKEY_CTRL_PKCS7_SIGN()\fR, \fBEVP_PKEY_CTRL_CMS_ENCRYPT()\fR,
1541 \&\fBEVP_PKEY_CTRL_CMS_DECRYPT()\fR, and \fBEVP_PKEY_CTRL_CMS_SIGN()\fR
1542 .Sp
1543 These control operations are not invoked by the OpenSSL library anymore and
1544 are replaced by direct checks of the key operation against the key type
1545 when the operation is initialized.
1546 .IP \(bu 4
1547 \&\fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR, \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR
1548 .Sp
1549 See the "kdf-ukm" item in "DH key exchange parameters" in \fBEVP_KEYEXCH\-DH\fR\|(7) and
1550 "ECDH Key Exchange parameters" in \fBEVP_KEYEXCH\-ECDH\fR\|(7).
1551 These functions are obsolete and should not be required.
1552 .IP \(bu 4
1553 \&\fBEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR
1554 .Sp
1555 Applications should use \fBEVP_PKEY_CTX_set1_rsa_keygen_pubexp\fR\|(3) instead.
1556 .IP \(bu 4
1557 \&\fBEVP_PKEY_cmp()\fR, \fBEVP_PKEY_cmp_parameters()\fR
1558 .Sp
1559 Applications should use \fBEVP_PKEY_eq\fR\|(3) and \fBEVP_PKEY_parameters_eq\fR\|(3) instead.
1560 See \fBEVP_PKEY_copy_parameters\fR\|(3) for further details.
1561 .IP \(bu 4
1562 \&\fBEVP_PKEY_encrypt_old()\fR, \fBEVP_PKEY_decrypt_old()\fR,
1563 .Sp
1564 Applications should use \fBEVP_PKEY_encrypt_init\fR\|(3) and \fBEVP_PKEY_encrypt\fR\|(3) or
1565 \&\fBEVP_PKEY_decrypt_init\fR\|(3) and \fBEVP_PKEY_decrypt\fR\|(3) instead.
1566 .IP \(bu 4
1567 \&\fBEVP_PKEY_get0()\fR
1568 .Sp
1569 This function returns NULL if the key comes from a provider.
1570 .IP \(bu 4
1571 \&\fBEVP_PKEY_get0_DH()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_EC_KEY()\fR, \fBEVP_PKEY_get0_RSA()\fR,
1572 \&\fBEVP_PKEY_get1_DH()\fR, \fBEVP_PKEY_get1_DSA()\fR, EVP_PKEY_get1_EC_KEY and \fBEVP_PKEY_get1_RSA()\fR,
1573 \&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR
1574 .Sp
1575 See "Functions that return an internal key should be treated as read only".
1576 .IP \(bu 4
1577 \&\fBEVP_PKEY_meth_*()\fR
1578 .Sp
1579 See "Providers are a replacement for engines and low-level method overrides".
1580 .IP \(bu 4
1581 \&\fBEVP_PKEY_new_CMAC_key()\fR
1582 .Sp
1583 See "Deprecated low-level MAC functions".
1584 .IP \(bu 4
1585 \&\fBEVP_PKEY_assign()\fR, \fBEVP_PKEY_set1_DH()\fR, \fBEVP_PKEY_set1_DSA()\fR,
1586 \&\fBEVP_PKEY_set1_EC_KEY()\fR, \fBEVP_PKEY_set1_RSA()\fR
1587 .Sp
1588 See "Deprecated low-level key object getters and setters"
1589 .IP \(bu 4
1590 \&\fBEVP_PKEY_set1_tls_encodedpoint()\fR \fBEVP_PKEY_get1_tls_encodedpoint()\fR
1591 .Sp
1592 These functions were previously used by libssl to set or get an encoded public
1593 key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more
1594 generic functions \fBEVP_PKEY_set1_encoded_public_key\fR\|(3) and
1595 \&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3).
1596 The old versions have been converted to deprecated macros that just call the
1597 new functions.
1598 .IP \(bu 4
1599 \&\fBEVP_PKEY_set1_engine()\fR, \fBEVP_PKEY_get0_engine()\fR
1600 .Sp
1601 See "Providers are a replacement for engines and low-level method overrides".
1602 .IP \(bu 4
1603 \&\fBEVP_PKEY_set_alias_type()\fR
1604 .Sp
1605 This function has been removed. There is no replacement.
1606 See "\fBEVP_PKEY_set_alias_type()\fR method has been removed"
1607 .IP \(bu 4
1608 \&\fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR, \fBHMAC_Final()\fR, \fBHMAC_size()\fR
1609 .Sp
1610 See "Deprecated low-level MAC functions".
1611 .IP \(bu 4
1612 \&\fBHMAC_CTX_new()\fR, \fBHMAC_CTX_free()\fR, \fBHMAC_CTX_copy()\fR, \fBHMAC_CTX_reset()\fR,
1613 \&\fBHMAC_CTX_set_flags()\fR, \fBHMAC_CTX_get_md()\fR
1614 .Sp
1615 See "Deprecated low-level MAC functions".
1616 .IP \(bu 4
1617 \&\fBi2d_DHparams()\fR, \fBi2d_DHxparams()\fR
1618 .Sp
1619 See "Deprecated low-level key reading and writing functions"
1620 and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3)
1621 .IP \(bu 4
1622 \&\fBi2d_DSAparams()\fR, \fBi2d_DSAPrivateKey()\fR, \fBi2d_DSAPrivateKey_bio()\fR,
1623 \&\fBi2d_DSAPrivateKey_fp()\fR, \fBi2d_DSA_PUBKEY()\fR, \fBi2d_DSA_PUBKEY_bio()\fR,
1624 \&\fBi2d_DSA_PUBKEY_fp()\fR, \fBi2d_DSAPublicKey()\fR
1625 .Sp
1626 See "Deprecated low-level key reading and writing functions"
1627 and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3)
1628 .IP \(bu 4
1629 \&\fBi2d_ECParameters()\fR, \fBi2d_ECPrivateKey()\fR, \fBi2d_ECPrivateKey_bio()\fR,
1630 \&\fBi2d_ECPrivateKey_fp()\fR, \fBi2d_EC_PUBKEY()\fR, \fBi2d_EC_PUBKEY_bio()\fR,
1631 \&\fBi2d_EC_PUBKEY_fp()\fR
1632 .Sp
1633 See "Deprecated low-level key reading and writing functions"
1634 and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3)
1635 .IP \(bu 4
1636 \&\fBi2o_ECPublicKey()\fR
1637 .Sp
1638 Use \fBEVP_PKEY_get1_encoded_public_key\fR\|(3).
1639 See "Deprecated low-level key parameter getters"
1640 .IP \(bu 4
1641 \&\fBi2d_RSAPrivateKey()\fR, \fBi2d_RSAPrivateKey_bio()\fR, \fBi2d_RSAPrivateKey_fp()\fR,
1642 \&\fBi2d_RSA_PUBKEY()\fR, \fBi2d_RSA_PUBKEY_bio()\fR, \fBi2d_RSA_PUBKEY_fp()\fR,
1643 \&\fBi2d_RSAPublicKey()\fR, \fBi2d_RSAPublicKey_bio()\fR, \fBi2d_RSAPublicKey_fp()\fR
1644 .Sp
1645 See "Deprecated low-level key reading and writing functions"
1646 and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3)
1647 .IP \(bu 4
1648 \&\fBIDEA_encrypt()\fR, \fBIDEA_set_decrypt_key()\fR, \fBIDEA_set_encrypt_key()\fR,
1649 \&\fBIDEA_cbc_encrypt()\fR, \fBIDEA_cfb64_encrypt()\fR, \fBIDEA_ecb_encrypt()\fR,
1650 \&\fBIDEA_ofb64_encrypt()\fR
1651 .Sp
1652 See "Deprecated low-level encryption functions".
1653 IDEA has been moved to the Legacy Provider.
1654 .IP \(bu 4
1655 \&\fBIDEA_options()\fR
1656 .Sp
1657 There is no replacement. This function returned a constant string.
1658 .IP \(bu 4
1659 \&\fBMD2()\fR, \fBMD2_Init()\fR, \fBMD2_Update()\fR, \fBMD2_Final()\fR
1660 .Sp
1661 See "Deprecated low-level encryption functions".
1662 MD2 has been moved to the Legacy Provider.
1663 .IP \(bu 4
1664 \&\fBMD2_options()\fR
1665 .Sp
1666 There is no replacement. This function returned a constant string.
1667 .IP \(bu 4
1668 \&\fBMD4()\fR, \fBMD4_Init()\fR, \fBMD4_Update()\fR, \fBMD4_Final()\fR, \fBMD4_Transform()\fR
1669 .Sp
1670 See "Deprecated low-level encryption functions".
1671 MD4 has been moved to the Legacy Provider.
1672 .IP \(bu 4
1673 \&\fBMDC2()\fR, \fBMDC2_Init()\fR, \fBMDC2_Update()\fR, \fBMDC2_Final()\fR
1674 .Sp
1675 See "Deprecated low-level encryption functions".
1676 MDC2 has been moved to the Legacy Provider.
1677 .IP \(bu 4
1678 \&\fBMD5()\fR, \fBMD5_Init()\fR, \fBMD5_Update()\fR, \fBMD5_Final()\fR, \fBMD5_Transform()\fR
1679 .Sp
1680 See "Deprecated low-level encryption functions".
1681 .IP \(bu 4
1682 \&\fBNCONF_WIN32()\fR
1683 .Sp
1684 This undocumented function has no replacement.
1685 See "HISTORY" in \fBconfig\fR\|(5) for more details.
1686 .IP \(bu 4
1687 \&\fBOCSP_parse_url()\fR
1688 .Sp
1689 Use \fBOSSL_HTTP_parse_url\fR\|(3) instead.
1690 .IP \(bu 4
1691 \&\fBOCSP_REQ_CTX\fR type and \fBOCSP_REQ_CTX_*()\fR functions
1692 .Sp
1693 These methods were used to collect all necessary data to form a HTTP request,
1694 and to perform the HTTP transfer with that request. With OpenSSL 3.0, the
1695 type is \fBOSSL_HTTP_REQ_CTX\fR, and the deprecated functions are replaced
1696 with \fBOSSL_HTTP_REQ_CTX_*()\fR. See \fBOSSL_HTTP_REQ_CTX\fR\|(3) for additional
1697 details.
1698 .IP \(bu 4
1699 \&\fBOPENSSL_fork_child()\fR, \fBOPENSSL_fork_parent()\fR, \fBOPENSSL_fork_prepare()\fR
1700 .Sp
1701 There is no replacement for these functions. These pthread fork support methods
1702 were unused by OpenSSL.
1703 .IP \(bu 4
1704 \&\fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_do_all_loaders()\fR, \fBOSSL_STORE_LOADER_get0_engine()\fR,
1705 \&\fBOSSL_STORE_LOADER_get0_scheme()\fR, \fBOSSL_STORE_LOADER_new()\fR,
1706 \&\fBOSSL_STORE_LOADER_set_attach()\fR, \fBOSSL_STORE_LOADER_set_close()\fR,
1707 \&\fBOSSL_STORE_LOADER_set_ctrl()\fR, \fBOSSL_STORE_LOADER_set_eof()\fR,
1708 \&\fBOSSL_STORE_LOADER_set_error()\fR, \fBOSSL_STORE_LOADER_set_expect()\fR,
1709 \&\fBOSSL_STORE_LOADER_set_find()\fR, \fBOSSL_STORE_LOADER_set_load()\fR,
1710 \&\fBOSSL_STORE_LOADER_set_open()\fR, \fBOSSL_STORE_LOADER_set_open_ex()\fR,
1711 \&\fBOSSL_STORE_register_loader()\fR, \fBOSSL_STORE_unregister_loader()\fR,
1712 \&\fBOSSL_STORE_vctrl()\fR
1713 .Sp
1714 These functions helped applications and engines create loaders for
1715 schemes they supported. These are all deprecated and discouraged in favour of
1716 provider implementations, see \fBprovider\-storemgmt\fR\|(7).
1717 .IP \(bu 4
1718 \&\fBPEM_read_DHparams()\fR, \fBPEM_read_bio_DHparams()\fR,
1719 \&\fBPEM_read_DSAparams()\fR, \fBPEM_read_bio_DSAparams()\fR,
1720 \&\fBPEM_read_DSAPrivateKey()\fR, \fBPEM_read_DSA_PUBKEY()\fR,
1721 PEM_read_bio_DSAPrivateKey and \fBPEM_read_bio_DSA_PUBKEY()\fR,
1722 \&\fBPEM_read_ECPKParameters()\fR, \fBPEM_read_ECPrivateKey()\fR, \fBPEM_read_EC_PUBKEY()\fR,
1723 \&\fBPEM_read_bio_ECPKParameters()\fR, \fBPEM_read_bio_ECPrivateKey()\fR, \fBPEM_read_bio_EC_PUBKEY()\fR,
1724 \&\fBPEM_read_RSAPrivateKey()\fR, \fBPEM_read_RSA_PUBKEY()\fR, \fBPEM_read_RSAPublicKey()\fR,
1725 \&\fBPEM_read_bio_RSAPrivateKey()\fR, \fBPEM_read_bio_RSA_PUBKEY()\fR, \fBPEM_read_bio_RSAPublicKey()\fR,
1726 \&\fBPEM_write_bio_DHparams()\fR, \fBPEM_write_bio_DHxparams()\fR, \fBPEM_write_DHparams()\fR, \fBPEM_write_DHxparams()\fR,
1727 \&\fBPEM_write_DSAparams()\fR, \fBPEM_write_DSAPrivateKey()\fR, \fBPEM_write_DSA_PUBKEY()\fR,
1728 \&\fBPEM_write_bio_DSAparams()\fR, \fBPEM_write_bio_DSAPrivateKey()\fR, \fBPEM_write_bio_DSA_PUBKEY()\fR,
1729 \&\fBPEM_write_ECPKParameters()\fR, \fBPEM_write_ECPrivateKey()\fR, \fBPEM_write_EC_PUBKEY()\fR,
1730 \&\fBPEM_write_bio_ECPKParameters()\fR, \fBPEM_write_bio_ECPrivateKey()\fR, \fBPEM_write_bio_EC_PUBKEY()\fR,
1731 \&\fBPEM_write_RSAPrivateKey()\fR, \fBPEM_write_RSA_PUBKEY()\fR, \fBPEM_write_RSAPublicKey()\fR,
1732 \&\fBPEM_write_bio_RSAPrivateKey()\fR, \fBPEM_write_bio_RSA_PUBKEY()\fR,
1733 \&\fBPEM_write_bio_RSAPublicKey()\fR,
1734 .Sp
1735 See "Deprecated low-level key reading and writing functions"
1736 .IP \(bu 4
1737 \&\fBPKCS1_MGF1()\fR
1738 .Sp
1739 See "Deprecated low-level encryption functions".
1740 .IP \(bu 4
1741 \&\fBRAND_get_rand_method()\fR, \fBRAND_set_rand_method()\fR, \fBRAND_OpenSSL()\fR,
1742 \&\fBRAND_set_rand_engine()\fR
1743 .Sp
1744 Applications should instead use \fBRAND_set_DRBG_type\fR\|(3),
1745 \&\fBEVP_RAND\fR\|(3) and \fBEVP_RAND\fR\|(7).
1746 See \fBRAND_set_rand_method\fR\|(3) for more details.
1747 .IP \(bu 4
1748 \&\fBRC2_encrypt()\fR, \fBRC2_decrypt()\fR, \fBRC2_set_key()\fR, \fBRC2_cbc_encrypt()\fR, \fBRC2_cfb64_encrypt()\fR,
1749 \&\fBRC2_ecb_encrypt()\fR, \fBRC2_ofb64_encrypt()\fR,
1750 \&\fBRC4()\fR, \fBRC4_set_key()\fR, \fBRC4_options()\fR,
1751 \&\fBRC5_32_encrypt()\fR, \fBRC5_32_set_key()\fR, \fBRC5_32_decrypt()\fR, \fBRC5_32_cbc_encrypt()\fR,
1752 \&\fBRC5_32_cfb64_encrypt()\fR, \fBRC5_32_ecb_encrypt()\fR, \fBRC5_32_ofb64_encrypt()\fR
1753 .Sp
1754 See "Deprecated low-level encryption functions".
1755 The Algorithms "RC2", "RC4" and "RC5" have been moved to the Legacy Provider.
1756 .IP \(bu 4
1757 \&\fBRIPEMD160()\fR, \fBRIPEMD160_Init()\fR, \fBRIPEMD160_Update()\fR, \fBRIPEMD160_Final()\fR,
1758 \&\fBRIPEMD160_Transform()\fR
1759 .Sp
1760 See "Deprecated low-level digest functions".
1761 The RIPE algorithm has been moved to the Legacy Provider.
1762 .IP \(bu 4
1763 \&\fBRSA_bits()\fR, \fBRSA_security_bits()\fR, \fBRSA_size()\fR
1764 .Sp
1765 Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and
1766 \&\fBEVP_PKEY_get_size\fR\|(3).
1767 .IP \(bu 4
1768 \&\fBRSA_check_key()\fR, \fBRSA_check_key_ex()\fR
1769 .Sp
1770 See "Deprecated low-level validation functions"
1771 .IP \(bu 4
1772 \&\fBRSA_clear_flags()\fR, \fBRSA_flags()\fR, \fBRSA_set_flags()\fR, \fBRSA_test_flags()\fR,
1773 \&\fBRSA_setup_blinding()\fR, \fBRSA_blinding_off()\fR, \fBRSA_blinding_on()\fR
1774 .Sp
1775 All of these RSA flags have been deprecated without replacement:
1776 .Sp
1777 \&\fBRSA_FLAG_BLINDING\fR, \fBRSA_FLAG_CACHE_PRIVATE\fR, \fBRSA_FLAG_CACHE_PUBLIC\fR,
1778 \&\fBRSA_FLAG_EXT_PKEY\fR, \fBRSA_FLAG_NO_BLINDING\fR, \fBRSA_FLAG_THREAD_SAFE\fR
1779 \&\fBRSA_METHOD_FLAG_NO_CHECK\fR
1780 .IP \(bu 4
1781 \&\fBRSA_generate_key_ex()\fR, \fBRSA_generate_multi_prime_key()\fR
1782 .Sp
1783 See "Deprecated low-level key generation functions".
1784 .IP \(bu 4
1785 \&\fBRSA_get0_engine()\fR
1786 .Sp
1787 See "Providers are a replacement for engines and low-level method overrides"
1788 .IP \(bu 4
1789 \&\fBRSA_get0_crt_params()\fR, \fBRSA_get0_d()\fR, \fBRSA_get0_dmp1()\fR, \fBRSA_get0_dmq1()\fR,
1790 \&\fBRSA_get0_e()\fR, \fBRSA_get0_factors()\fR, \fBRSA_get0_iqmp()\fR, \fBRSA_get0_key()\fR,
1791 \&\fBRSA_get0_multi_prime_crt_params()\fR, \fBRSA_get0_multi_prime_factors()\fR, \fBRSA_get0_n()\fR,
1792 \&\fBRSA_get0_p()\fR, \fBRSA_get0_pss_params()\fR, \fBRSA_get0_q()\fR,
1793 \&\fBRSA_get_multi_prime_extra_count()\fR
1794 .Sp
1795 See "Deprecated low-level key parameter getters"
1796 .IP \(bu 4
1797 \&\fBRSA_new()\fR, \fBRSA_free()\fR, \fBRSA_up_ref()\fR
1798 .Sp
1799 See "Deprecated low-level object creation".
1800 .IP \(bu 4
1801 \&\fBRSA_get_default_method()\fR, RSA_get_ex_data and \fBRSA_get_method()\fR
1802 .Sp
1803 See "Providers are a replacement for engines and low-level method overrides".
1804 .IP \(bu 4
1805 \&\fBRSA_get_version()\fR
1806 .Sp
1807 There is no replacement.
1808 .IP \(bu 4
1809 \&\fBRSA_meth_*()\fR, \fBRSA_new_method()\fR, RSA_null_method and \fBRSA_PKCS1_OpenSSL()\fR
1810 .Sp
1811 See "Providers are a replacement for engines and low-level method overrides".
1812 .IP \(bu 4
1813 \&\fBRSA_padding_add_*()\fR, \fBRSA_padding_check_*()\fR
1814 .Sp
1815 See "Deprecated low-level signing functions" and
1816 "Deprecated low-level encryption functions".
1817 .IP \(bu 4
1818 \&\fBRSA_print()\fR, \fBRSA_print_fp()\fR
1819 .Sp
1820 See "Deprecated low-level key printing functions"
1821 .IP \(bu 4
1822 \&\fBRSA_public_encrypt()\fR, \fBRSA_private_decrypt()\fR
1823 .Sp
1824 See "Deprecated low-level encryption functions"
1825 .IP \(bu 4
1826 \&\fBRSA_private_encrypt()\fR, \fBRSA_public_decrypt()\fR
1827 .Sp
1828 This is equivalent to doing sign and verify recover operations (with a padding
1829 mode of none). See "Deprecated low-level signing functions".
1830 .IP \(bu 4
1831 \&\fBRSAPrivateKey_dup()\fR, \fBRSAPublicKey_dup()\fR
1832 .Sp
1833 There is no direct replacement. Applications may use \fBEVP_PKEY_dup\fR\|(3).
1834 .IP \(bu 4
1835 \&\fBRSAPublicKey_it()\fR, \fBRSAPrivateKey_it()\fR
1836 .Sp
1837 See "Deprecated low-level key reading and writing functions"
1838 .IP \(bu 4
1839 \&\fBRSA_set0_crt_params()\fR, \fBRSA_set0_factors()\fR, \fBRSA_set0_key()\fR,
1840 \&\fBRSA_set0_multi_prime_params()\fR
1841 .Sp
1842 See "Deprecated low-level key parameter setters".
1843 .IP \(bu 4
1844 \&\fBRSA_set_default_method()\fR, \fBRSA_set_method()\fR, \fBRSA_set_ex_data()\fR
1845 .Sp
1846 See "Providers are a replacement for engines and low-level method overrides"
1847 .IP \(bu 4
1848 \&\fBRSA_sign()\fR, \fBRSA_sign_ASN1_OCTET_STRING()\fR, \fBRSA_verify()\fR,
1849 \&\fBRSA_verify_ASN1_OCTET_STRING()\fR, \fBRSA_verify_PKCS1_PSS()\fR,
1850 \&\fBRSA_verify_PKCS1_PSS_mgf1()\fR
1851 .Sp
1852 See "Deprecated low-level signing functions".
1853 .IP \(bu 4
1854 \&\fBRSA_X931_derive_ex()\fR, \fBRSA_X931_generate_key_ex()\fR, \fBRSA_X931_hash_id()\fR
1855 .Sp
1856 There are no replacements for these functions.
1857 X931 padding can be set using "Signature Parameters" in \fBEVP_SIGNATURE\-RSA\fR\|(7).
1858 See \fBOSSL_SIGNATURE_PARAM_PAD_MODE\fR.
1859 .IP \(bu 4
1860 \&\fBSEED_encrypt()\fR, \fBSEED_decrypt()\fR, \fBSEED_set_key()\fR, \fBSEED_cbc_encrypt()\fR,
1861 \&\fBSEED_cfb128_encrypt()\fR, \fBSEED_ecb_encrypt()\fR, \fBSEED_ofb128_encrypt()\fR
1862 .Sp
1863 See "Deprecated low-level encryption functions".
1864 The SEED algorithm has been moved to the Legacy Provider.
1865 .IP \(bu 4
1866 \&\fBSHA1_Init()\fR, \fBSHA1_Update()\fR, \fBSHA1_Final()\fR, \fBSHA1_Transform()\fR,
1867 \&\fBSHA224_Init()\fR, \fBSHA224_Update()\fR, \fBSHA224_Final()\fR,
1868 \&\fBSHA256_Init()\fR, \fBSHA256_Update()\fR, \fBSHA256_Final()\fR, \fBSHA256_Transform()\fR,
1869 \&\fBSHA384_Init()\fR, \fBSHA384_Update()\fR, \fBSHA384_Final()\fR,
1870 \&\fBSHA512_Init()\fR, \fBSHA512_Update()\fR, \fBSHA512_Final()\fR, \fBSHA512_Transform()\fR
1871 .Sp
1872 See "Deprecated low-level digest functions".
1873 .IP \(bu 4
1874 \&\fBSRP_Calc_A()\fR, \fBSRP_Calc_B()\fR, \fBSRP_Calc_client_key()\fR, \fBSRP_Calc_server_key()\fR,
1875 \&\fBSRP_Calc_u()\fR, \fBSRP_Calc_x()\fR, \fBSRP_check_known_gN_param()\fR, \fBSRP_create_verifier()\fR,
1876 \&\fBSRP_create_verifier_BN()\fR, \fBSRP_get_default_gN()\fR, \fBSRP_user_pwd_free()\fR, \fBSRP_user_pwd_new()\fR,
1877 \&\fBSRP_user_pwd_set0_sv()\fR, \fBSRP_user_pwd_set1_ids()\fR, \fBSRP_user_pwd_set_gN()\fR,
1878 \&\fBSRP_VBASE_add0_user()\fR, \fBSRP_VBASE_free()\fR, \fBSRP_VBASE_get1_by_user()\fR, \fBSRP_VBASE_init()\fR,
1879 \&\fBSRP_VBASE_new()\fR, \fBSRP_Verify_A_mod_N()\fR, \fBSRP_Verify_B_mod_N()\fR
1880 .Sp
1881 There are no replacements for the SRP functions.
1882 .IP \(bu 4
1883 \&\fBSSL_CTX_set_tmp_dh_callback()\fR, \fBSSL_set_tmp_dh_callback()\fR,
1884 \&\fBSSL_CTX_set_tmp_dh()\fR, \fBSSL_set_tmp_dh()\fR
1885 .Sp
1886 These are used to set the Diffie-Hellman (DH) parameters that are to be used by
1887 servers requiring ephemeral DH keys. Instead applications should consider using
1888 the built-in DH parameters that are available by calling \fBSSL_CTX_set_dh_auto\fR\|(3)
1889 or \fBSSL_set_dh_auto\fR\|(3). If custom parameters are necessary then applications can
1890 use the alternative functions \fBSSL_CTX_set0_tmp_dh_pkey\fR\|(3) and
1891 \&\fBSSL_set0_tmp_dh_pkey\fR\|(3). There is no direct replacement for the "callback"
1892 functions. The callback was originally useful in order to have different
1893 parameters for export and non-export ciphersuites. Export ciphersuites are no
1894 longer supported by OpenSSL. Use of the callback functions should be replaced
1895 by one of the other methods described above.
1896 .IP \(bu 4
1897 \&\fBSSL_CTX_set_tlsext_ticket_key_cb()\fR
1898 .Sp
1899 Use the new \fBSSL_CTX_set_tlsext_ticket_key_evp_cb\fR\|(3) function instead.
1900 .IP \(bu 4
1901 \&\fBWHIRLPOOL()\fR, \fBWHIRLPOOL_Init()\fR, \fBWHIRLPOOL_Update()\fR, \fBWHIRLPOOL_Final()\fR,
1902 \&\fBWHIRLPOOL_BitUpdate()\fR
1903 .Sp
1904 See "Deprecated low-level digest functions".
1905 The Whirlpool algorithm has been moved to the Legacy Provider.
1906 .IP \(bu 4
1907 \&\fBX509_certificate_type()\fR
1908 .Sp
1909 This was an undocumented function. Applications can use \fBX509_get0_pubkey\fR\|(3)
1910 and \fBX509_get0_signature\fR\|(3) instead.
1911 .IP \(bu 4
1912 \&\fBX509_http_nbio()\fR, \fBX509_CRL_http_nbio()\fR
1913 .Sp
1914 Use \fBX509_load_http\fR\|(3) and \fBX509_CRL_load_http\fR\|(3) instead.
1915 .PP
1916 \fINID handling for provided keys and algorithms\fR
1917 .IX Subsection "NID handling for provided keys and algorithms"
1918 .PP
1919 The following functions for NID (numeric id) handling have changed semantics.
1920 .IP \(bu 4
1921 \&\fBEVP_PKEY_id()\fR, \fBEVP_PKEY_get_id()\fR
1922 .Sp
1923 This function was previously used to reliably return the NID of
1924 an EVP_PKEY object, e.g., to look up the name of the algorithm of
1925 such EVP_PKEY by calling \fBOBJ_nid2sn\fR\|(3). With the introduction
1926 of \fBprovider\fR\|(7)s \fBEVP_PKEY_id()\fR or its new equivalent
1927 \&\fBEVP_PKEY_get_id\fR\|(3) might now also return the value \-1
1928 (\fBEVP_PKEY_KEYMGMT\fR) indicating the use of a provider to
1929 implement the EVP_PKEY object. Therefore, the use of
1930 \&\fBEVP_PKEY_get0_type_name\fR\|(3) is recommended for retrieving
1931 the name of the EVP_PKEY algorithm.
1932 .SS "Using the FIPS Module in applications"
1933 .IX Subsection "Using the FIPS Module in applications"
1934 See \fBfips_module\fR\|(7) and \fBOSSL_PROVIDER\-FIPS\fR\|(7) for details.
1935 .SS "OpenSSL command line application changes"
1936 .IX Subsection "OpenSSL command line application changes"
1937 \fINew applications\fR
1938 .IX Subsection "New applications"
1939 .PP
1940 \&\fBopenssl kdf\fR uses the new \fBEVP_KDF\fR\|(3) API.
1941 \&\fBopenssl kdf\fR uses the new \fBEVP_MAC\fR\|(3) API.
1942 .PP
1943 \fIAdded options\fR
1944 .IX Subsection "Added options"
1945 .PP
1946 \&\fB\-provider_path\fR and \fB\-provider\fR are available to all apps and can be used
1947 multiple times to load any providers, such as the 'legacy' provider or third
1948 party providers. If used then the 'default' provider would also need to be
1949 specified if required. The \fB\-provider_path\fR must be specified before the
1950 \&\fB\-provider\fR option.
1951 .PP
1952 The \fBlist\fR app has many new options. See \fBopenssl\-list\fR\|(1) for more
1953 information.
1954 .PP
1955 \&\fB\-crl_lastupdate\fR and \fB\-crl_nextupdate\fR used by \fBopenssl ca\fR allows
1956 explicit setting of fields in the generated CRL.
1957 .PP
1958 \fIRemoved options\fR
1959 .IX Subsection "Removed options"
1960 .PP
1961 Interactive mode is not longer available.
1962 .PP
1963 The \fB\-crypt\fR option used by \fBopenssl passwd\fR.
1964 The \fB\-c\fR option used by \fBopenssl x509\fR, \fBopenssl dhparam\fR,
1965 \&\fBopenssl dsaparam\fR, and \fBopenssl ecparam\fR.
1966 .PP
1967 \fIOther Changes\fR
1968 .IX Subsection "Other Changes"
1969 .PP
1970 The output of Command line applications may have minor changes.
1971 These are primarily changes in capitalisation and white space. However, in some
1972 cases, there are additional differences.
1973 For example, the DH parameters output from \fBopenssl dhparam\fR now lists 'P',
1974 \&'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and
1975 \&'counter' respectively.
1976 .PP
1977 The \fBopenssl\fR commands that read keys, certificates, and CRLs now
1978 automatically detect the PEM or DER format of the input files so it is not
1979 necessary to explicitly specify the input format anymore. However if the
1980 input format option is used the specified format will be required.
1981 .PP
1982 \&\fBopenssl speed\fR no longer uses low-level API calls.
1983 This implies some of the performance numbers might not be comparable with the
1984 previous releases due to higher overhead. This applies particularly to
1985 measuring performance on smaller data chunks.
1986 .PP
1987 b<openssl dhparam>, \fBopenssl dsa\fR, \fBopenssl gendsa\fR, \fBopenssl dsaparam\fR,
1988 \&\fBopenssl genrsa\fR and \fBopenssl rsa\fR have been modified to use PKEY APIs.
1989 \&\fBopenssl genrsa\fR and \fBopenssl rsa\fR now write PKCS #8 keys by default.
1990 .PP
1991 \fIDefault settings\fR
1992 .IX Subsection "Default settings"
1993 .PP
1994 "SHA256" is now the default digest for TS query used by \fBopenssl ts\fR.
1995 .PP
1996 \fIDeprecated apps\fR
1997 .IX Subsection "Deprecated apps"
1998 .PP
1999 \&\fBopenssl rsautl\fR is deprecated, use \fBopenssl pkeyutl\fR instead.
2000 \&\fBopenssl dhparam\fR, \fBopenssl dsa\fR, \fBopenssl gendsa\fR, \fBopenssl dsaparam\fR,
2001 \&\fBopenssl genrsa\fR, \fBopenssl rsa\fR, \fBopenssl genrsa\fR and \fBopenssl rsa\fR are
2002 now in maintenance mode and no new features will be added to them.
2003 .SS "TLS Changes"
2004 .IX Subsection "TLS Changes"
2005 .IP \(bu 4
2006 TLS 1.3 FFDHE key exchange support added
2007 .Sp
2008 This uses DH safe prime named groups.
2009 .IP \(bu 4
2010 Support for fully "pluggable" TLSv1.3 groups.
2011 .Sp
2012 This means that providers may supply their own group implementations (using
2013 either the "key exchange" or the "key encapsulation" methods) which will
2014 automatically be detected and used by libssl.
2015 .IP \(bu 4
2016 SSL and SSL_CTX options are now 64 bit instead of 32 bit.
2017 .Sp
2018 The signatures of the functions to get and set options on SSL and
2019 SSL_CTX objects changed from "unsigned long" to "uint64_t" type.
2020 .Sp
2021 This may require source code changes. For example it is no longer possible
2022 to use the \fBSSL_OP_\fR macro values in preprocessor \f(CW\*(C`#if\*(C'\fR conditions.
2023 However it is still possible to test whether these macros are defined or not.
2024 .Sp
2025 See \fBSSL_CTX_get_options\fR\|(3), \fBSSL_CTX_set_options\fR\|(3),
2026 \&\fBSSL_get_options\fR\|(3) and \fBSSL_set_options\fR\|(3).
2027 .IP \(bu 4
2028 \&\fBSSL_set1_host()\fR and \fBSSL_add1_host()\fR Changes
2029 .Sp
2030 These functions now take IP literal addresses as well as actual hostnames.
2031 .IP \(bu 4
2032 Added SSL option SSL_OP_CLEANSE_PLAINTEXT
2033 .Sp
2034 If the option is set, openssl cleanses (zeroizes) plaintext bytes from
2035 internal buffers after delivering them to the application. Note,
2036 the application is still responsible for cleansing other copies
2037 (e.g.: data received by \fBSSL_read\fR\|(3)).
2038 .IP \(bu 4
2039 Client-initiated renegotiation is disabled by default.
2040 .Sp
2041 To allow it, use the \fB\-client_renegotiation\fR option,
2042 the \fBSSL_OP_ALLOW_CLIENT_RENEGOTIATION\fR flag, or the \f(CW\*(C`ClientRenegotiation\*(C'\fR
2043 config parameter as appropriate.
2044 .IP \(bu 4
2045 Secure renegotiation is now required by default for TLS connections
2046 .Sp
2047 Support for RFC 5746 secure renegotiation is now required by default for
2048 SSL or TLS connections to succeed. Applications that require the ability
2049 to connect to legacy peers will need to explicitly set
2050 SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT
2051 is no longer set as part of SSL_OP_ALL.
2052 .IP \(bu 4
2053 Combining the Configure options no-ec and no-dh no longer disables TLSv1.3
2054 .Sp
2055 Typically if OpenSSL has no EC or DH algorithms then it cannot support
2056 connections with TLSv1.3. However OpenSSL now supports "pluggable" groups
2057 through providers. Therefore third party providers may supply group
2058 implementations even where there are no built-in ones. Attempting to create
2059 TLS connections in such a build without also disabling TLSv1.3 at run time or
2060 using third party provider groups may result in handshake failures. TLSv1.3
2061 can be disabled at compile time using the "no\-tls1_3" Configure option.
2062 .IP \(bu 4
2063 \&\fBSSL_CTX_set_ciphersuites()\fR and \fBSSL_set_ciphersuites()\fR changes.
2064 .Sp
2065 The methods now ignore unknown ciphers.
2066 .IP \(bu 4
2067 Security callback change.
2068 .Sp
2069 The security callback, which can be customised by application code, supports
2070 the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY
2071 in the "other" parameter. In most places this is what is passed. All these
2072 places occur server side. However there was one client side call of this
2073 security operation and it passed a DH object instead. This is incorrect
2074 according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all
2075 of the other locations. Therefore this client side call has been changed to
2076 pass an EVP_PKEY instead.
2077 .IP \(bu 4
2078 New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF
2079 .Sp
2080 The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option
2081 is set, an unexpected EOF is ignored, it pretends a close notify was received
2082 instead and so the returned error becomes SSL_ERROR_ZERO_RETURN.
2083 .IP \(bu 4
2084 The security strength of SHA1 and MD5 based signatures in TLS has been reduced.
2085 .Sp
2086 This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer
2087 working at the default security level of 1 and instead requires security
2088 level 0. The security level can be changed either using the cipher string
2089 with \f(CW@SECLEVEL\fR, or calling \fBSSL_CTX_set_security_level\fR\|(3). This also means
2090 that where the signature algorithms extension is missing from a ClientHello
2091 then the handshake will fail in TLS 1.2 at security level 1. This is because,
2092 although this extension is optional, failing to provide one means that
2093 OpenSSL will fallback to a default set of signature algorithms. This default
2094 set requires the availability of SHA1.
2095 .IP \(bu 4
2096 X509 certificates signed using SHA1 are no longer allowed at security level 1 and above.
2097 .Sp
2098 In TLS/SSL the default security level is 1. It can be set either using the cipher
2099 string with \f(CW@SECLEVEL\fR, or calling \fBSSL_CTX_set_security_level\fR\|(3). If the
2100 leaf certificate is signed with SHA\-1, a call to \fBSSL_CTX_use_certificate\fR\|(3)
2101 will fail if the security level is not lowered first.
2102 Outside TLS/SSL, the default security level is \-1 (effectively 0). It can
2103 be set using \fBX509_VERIFY_PARAM_set_auth_level\fR\|(3) or using the \fB\-auth_level\fR
2104 options of the commands.
2105 .SH "SEE ALSO"
2106 .IX Header "SEE ALSO"
2107 \&\fBfips_module\fR\|(7)
2108 .SH HISTORY
2109 .IX Header "HISTORY"
2110 The migration guide was created for OpenSSL 3.0.
2111 .SH COPYRIGHT
2112 .IX Header "COPYRIGHT"
2113 Copyright 2021\-2025 The OpenSSL Project Authors. All Rights Reserved.
2114 .PP
2115 Licensed under the Apache License 2.0 (the "License"). You may not use
2116 this file except in compliance with the License. You can obtain a copy
2117 in the file LICENSE in the source distribution or at
2118 <https://www.openssl.org/source/license.html>.