OpenSSL 3.0

THIS PAGE IS A WORK IN PROGRESS

OpenSSL 3.0 is the next release of OpenSSL that is currently in development. This page is intended as a collection of notes for people downloading the alpha/beta releases or who are planning to upgrade from a previous version of OpenSSL to 3.0.

Main Changes in OpenSSL 3.0 from OpenSSL 1.1.1

Major Release

OpenSSL 3.0 is a major release and consequently any application that currently uses an older version of OpenSSL will at the very least need to be recompiled in order to work with the new version. It is the intention that the large majority of applications will work unchanged with OpenSSL 3.0 if those applications previously worked with OpenSSL 1.1.1. However this is not guaranteed and some changes may be required in some cases. Changes may also be required if applications need to take advantage of some of the new features available in OpenSSL 3.0 such as the availability of the FIPS module.

Providers and FIPS support

One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider concept. Providers collect together and make available algorithm implementations. With OpenSSL 3.0 it is possible to specify, either programmatically or via a config file, which providers you want to use for any given application. OpenSSL 3.0 comes with 4 different providers as standard. Over time third parties may distribute additional providers that can be plugged into OpenSSL. All algorithm implementations available via providers are accessed through the "EVP" set of APIs. They cannot be accessed using the "low level" APIs (see below).

The standard providers are:

• The default provider. This collects together all of the standard built-in OpenSSL algorithm implementations. If an application doesn't specify anything else explicitly or via config, then this is the provider that will be used. This is a "built-in" provider which means that it is built into libcrypto and does not exist as a separate standalone module.

• The legacy provider. This is a collection of legacy algorithms that are either no longer in common use or strongly discouraged from use. However some applications may need to use these algorithms for backwards compatibility reasons. This provider is NOT loaded by default. This may mean that some applications upgrading from earlier versions of OpenSSL may find that some algorithms are no longer available unless they load the legacy provider explicitly. Algorithms in the legacy provider include MD2, MD4, MDC2, RMD160, CAST5, BF (Blowfish), IDEA, SEED, RC2, RC4, RC5 and DES (but not 3DES).

• The FIPS provider. This contains a sub-set of the algorithm implementations available from the default provider. Algorithms available in this provider conform to FIPS standards. It is intended that this provider will be FIPS140-2 validated. In some cases there maybe minor behavioural differences between algorithm implementations in this provider compared to the equivalent algorithm in the default provider. This is typically in order to conform to FIPS standards.

• The null provider. This provider is "built-in" to libcrypto and contains no algorithm implementations. It can be useful in some situations where you want to avoid the automatic loading of the default provider.

Low Level APIs

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "EVP" APIs and the "low level" APIs. The EVP APIs are typically designed to work across all algorithm types. The "low level" APIs are targeted at a specific algorithm implementation. For example, the EVP APIs provide the functions `EVP_EncryptInit_ex`, `EVP_EncryptUpdate` and `EVP_EncryptFinal` to perform symmetric encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc. On the other hand to do AES encryption using the low level APIs you would have to call AES specific functions such as `AES_set_encrypt_key`, `AES_encrypt`, and so on. The functions for 3DES are different.

Use of the low level APIs has been informally discouraged by the OpenSSL development team for a long time. However in OpenSSL 3.0 this is made more formal. All such low level APIs have been deprecated. You may still use them in your applications, but you may start to see deprecation warnings during compilation (dependent on compiler support for this). Deprecated APIs may be removed from future versions of OpenSSL so you are strongly encouraged to update your code to use the EVP APIs instead.

Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1

Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight forward in most cases. The most likely area where you will encounter problems is if you have used low level APIs in your code (as discussed above). In that case you are likely to start seeing deprecation warnings when compiling your application. If this happens you have 3 options:

1) 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.

2) Suppress the warnings. Refer to your compiler documentation on how to do this.

3) Remove your usage of the low level APIs. In this case you will need to rewrite your code to use the EVP APIs instead.

Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2

Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more difficult. The main things to be aware of are:

1) The build and installation procedure has changed significantly since OpenSSL 1.0.2. Check the file INSTALL.md in the top of the installation for instructions on how to build and install OpenSSL for your platform. Also checkout the various NOTES files in the same directory, as applicable for your platform.

2) Many structures have been made opaque in OpenSSL 3.0. The structure definitions have been removed from the public header files and moved to internal header files. In practice this means that you can no longer stack allocate some structures. Instead they must be heap allocated through some function call (typically those function names have a `_new` suffix to them). Additionally you must use "setter" or "getter" functions to access the fields within those structures.

For example code that previously looked like this:

EVP_MD_CTX md_ctx;

EVP_MD_CTX_init(&md_ctx);

/* Do something with the md_ctx */

will now generate compiler errors. For example:

md_ctx.c:6:16: error: storage size of ‘md_ctx’ isn’t known

The code needs to be amended to look like this:

EVP_MD_CTX *md_ctx;

md_ctx = EVP_MD_CTX_new();
if (md_ctx == NULL)
   /* Error */;

/* Do something with the md_ctx */

EVP_MD_CTX_free(md_ctx);

3) Support for TLSv1.3 has been added which has a number of implications for SSL/TLS applications. See the TLS1.3 page for further details.

Upgrading from the the OpenSSL 2.0 FIPS Object Module

The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built separately and then integrated into your main OpenSSL 1.0.2 build. In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of OpenSSL and is no longer a separate download. You do not need to take separate build steps to add the FIPS support - it is built by default. You do need to take steps to ensure that your application is using the FIPS module in OpenSSL 3.0. See the further notes below on configuring this.

Completing the installation of the FIPS Module

Once OpenSSL has been built and installed you will need to take explicit steps to complete the installation of the FIPS module. The OpenSSL 3.0 FIPS support is in the form of the FIPS provider which, on Unix, is in a `fips.so` file. On Windows this will be called `fips.dll`. Following installation of OpenSSL 3.0 the default location for this file is '/usr/local/lib/ossl-modules/fips.so' on Unix or 'C:\Program Files\OpenSSL\lib\fips.dll' on Windows. (Drafting note: need to check the locations are correct!)

To complete the installation you need to run the 'fipsinstall' command line application. For example:

$ openssl fipsinstall -out /usr/local/ssl/fipsinstall.cnf -module /usr/local/lib/ossl-modules/fips.so -provider_name fips -mac_name HMAC -macopt digest:SHA256 -macopt hexkey:00 -section_name fips_sect