Debian Codegraph @

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