OpenSSLWiki - User contributions [en]

Compilation and Installation

2025-01-15T12:53:41Z

Levitte: gcc knowns -rpath=DIR, clang does not.

The following page is a combination of the <tt>INSTALL</tt> file provided with the OpenSSL library and notes from the field. If you have questions about what you are doing or seeing, then you should consult <tt>INSTALL</tt> since it contains the commands and specifies the behavior by the development team.

OpenSSL uses a custom build system to configure the library. Configuration will allow the library to set up the recursive makefiles from <tt>makefile.org</tt>. Once configured, you use <tt>make</tt> to build the library. You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

You must use a C compiler to build the OpenSSL library. You cannot use a C++ compiler. Later, once the library is built, it is OK to create user programs with a C++ compiler. But the library proper must be built with a C compiler.

There are two generations of build system. First is the build system used in OpenSSL 1.0.2 and below. The instructions below apply to it. Second is the build system for OpenSSL 1.1.0 and above. The instructions are similar, but not the same. For example, the second generation abandons the monolithic <tt>Configure</tt> and places individual configurations in the <tt>Configurations</tt> directory. Also, the second generation is more platform agnostic and uses templates to produce a final, top level build file (<tt>Makefile</tt>, <tt>descrip.mms</tt>, what have you).

After you configure and build the library, you should always perform a <tt>make test</tt> to ensure the library performs as expected under its self tests. If you are building OpenSSL 1.1.0 and above, then you will also need PERL 5.10 or higher (see <tt>README.PERL</tt> for details).

OpenSSL's build system does not rely upon <tt>autotools</tt> or <tt>libtool</tt>. Also see [http://www.openssl.org/support/faq.html#MISC5 Why aren't tools like 'autoconf' and 'libtool' used?] in the OpenSSL FAQ.

== Retrieve source code ==

The OpenSSL source code can be downloaded from [http://www.openssl.org/source/ OpenSSL Source Tarballs] or any suitable [http://www.openssl.org/source/mirror.html ftp mirror]. There are various versions including stable as well as unstable versions.

The source code is managed via Git. It's referred to as Master. The repository is

: git://git.openssl.org/openssl.git

The source is also available via a [https://github.com/openssl/openssl GitHub] mirror. This repository is updated every 15 minutes.

* [[Use_of_Git|Accessing OpenSSL source code via Git]]

== Configuration ==

OpenSSL is configured for a particular platform with protocol and behavior options using <tt>Configure</tt> and <tt>config</tt>.

You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

=== Supported Platforms ===

You can run <tt>Configure LIST</tt> to see a list of available platforms.

<pre>$ ./Configure LIST
BC-32
BS2000-OSD
BSD-generic32
BSD-generic64
BSD-ia64
BSD-sparc64
BSD-sparcv8
BSD-x86
BSD-x86-elf
BSD-x86_64
Cygwin
Cygwin-x86_64
DJGPP
...</pre>

If your platform is not listed, then use a similar platform and tune the <tt>$cflags</tt> and <tt>$ldflags</tt> by making a copy of the configure line and giving it its own name. <tt>$cflags</tt> and <tt>$ldflags</tt> correspond to fields 2 and 6 in a configure line. An example of using a similar configure line is presented in [[Compilation_and_Installation#Using_RPATHs|Using RPATHs]].

=== Configure & Config ===

You use <tt>Configure</tt> and <tt>config</tt> to tune the compile and installation process through options and switches. The difference between is <tt>Configure</tt> properly handles the host-arch-compiler triplet, and <tt>config</tt> does not. <tt>config</tt> attempts to guess the triplet, so it's a lot like autotool's <tt>config.guess</tt>.

You can usually use <tt>config</tt> and it will do the right thing (from Ubuntu 13.04, x64):

<pre>$ ./config
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring for linux-x86_64
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

Mac OS X can have issues (it's often a neglected platform), and you will have to use <tt>Configure</tt>:

<pre> ./Configure darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

You can also configure on Darwin by exporting <tt>KERNEL_BITS</tt>:

<pre>$ export KERNEL_BITS=64
$ ./config shared no-ssl2 no-ssl3 enable-ec_nistp_64_gcc_128 --openssldir=/usr/local/ssl/macosx-x64/
Operating system: i686-apple-darwinDarwin Kernel Version 12.5.0: Sun Sep 29 13:33:47 PDT 2013; root:xnu-2050.48.12~1/RELEASE_X86_64
Configuring for darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

If you provide a option not known to configure or ask for help, then you get a brief help message:

<pre>$ ./Configure --help
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]</pre>

And if you supply an unknown triplet:

<pre>$ ./Configure darwin64-x86_64-clang
Configuring for darwin64-x86_64-clang
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]

pick os/compiler from:
BC-32 BS2000-OSD BSD-generic32 BSD-generic64 BSD-ia64 BSD-sparc64 BSD-sparcv8
BSD-x86 BSD-x86-elf BSD-x86_64 Cygwin Cygwin-pre1.3 DJGPP MPE/iX-gcc OS2-EMX
...

NOTE: If in doubt, on Unix-ish systems use './config'.</pre>

=== Dependencies ===

If you are prompted to run <tt>make depend</tt>, then you must do so. For OpenSSL 1.0.2 and below, it's required to update the standard distribution once configuration options change.

<pre>Since you've disabled or enabled at least one algorithm, you need to do
the following before building:

make depend
</pre>

OpenSSL 1.1.0 and above performs the dependency step for you, so you should not see the message. However, you should perform a <tt>make clean</tt> to ensure the list of objects files is accurate after a reconfiguration.

== Configure Options ==

OpenSSL has been around a long time, and it carries around a lot of cruft. For example, from above, SSLv2 is enabled by default. SSLv2 is completely broken, and you should disable it during configuration. You can disable protocols and provide other options through <tt>Configure</tt> and <tt>config</tt>, and the following lists some of them.

'''Note''': if you specify a non-existent option, then the configure scripts will proceed without warning. For example, if you inadvertently specify '''no-sslv2''' rather than '''no-ssl2 no-ssl3''', the script will configure ''with'' SSLv2 and ''without'' warning for the unknown no-sslv2.

'''Note''': when building a shared object, both the static archive and shared objects are built. You do not need to do anything special to build both when '''shared''' is specified.

{| class="wikitable sortable" border="1"
|+ OpenSSL Library Options
|-
! scope="col" width="150px" | Option
! scope="col" class="unsortable" | Description
|-
| --prefix=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| --openssldir=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| -d || Debug build of the library. Optimizations are disabled (no <tt>-O3</tt> or similar) and <tt>libefence</tt> is used (<tt>apt-get install electric-fence</tt> or <tt>yum install electric-fence</tt>). TODO: Any other features?
|-
| shared || Build a shared object in addition to the static archive. You probably need a [[#Using_RPATHs|RPATH]] when enabling <tt>shared</tt> to ensure <tt>openssl</tt> uses the correct <tt>libssl</tt> and <tt>libcrypto</tt> after installation.
|-
| enable-ec_nistp_64_gcc_128 || Use on little endian platforms when GCC supports <tt>__uint128_t</tt>. ECDH is about 2 to 4 times faster. Not enabled by default because <tt>Configure</tt> can't determine it. Enable it if your compiler defines <tt>__SIZEOF_INT128__</tt>, the CPU is little endian and it tolerates unaligned data access.
|-
| enable-capieng || Enables the Microsoft CAPI engine on Windows platforms. Used to access the Windows Certificate Store. Also see [http://openssl.6102.n7.nabble.com/Using-Windows-certificate-store-through-OpenSSL-td46788.html Using Windows certificate store through OpenSSL] on the OpenSSL developer list.
|-
| no-ssl2 || Disables SSLv2. <tt>OPENSSL_NO_SSL2</tt> will be defined in the OpenSSL headers.
|-
| no-ssl3 || Disables SSLv3. <tt>OPENSSL_NO_SSL3</tt> will be defined in the OpenSSL headers.
|-
| no-comp || Disables compression independent of <tt>zlib</tt>. <tt>OPENSSL_NO_COMP</tt> will be defined in the OpenSSL headers.
|-
| no-idea || Disables IDEA algorithm. Unlike RC5 and MDC2, IDEA is enabled by default
|-
| no-asm || Disables assembly language routines (and uses C routines)
|-
| no-dtls || Disables DTLS in OpenSSL 1.1.0 and above
|-
| no-dtls1 || Disables DTLS in OpenSSL 1.0.2 and below
|-
| no-shared || Disables shared objects (only a static library is created)
|-
| no-hw || Disables hardware support (useful on mobile devices)
|-
| no-engine || Disables hardware support (useful on mobile devices)
|-
| no-threads || Disables threading support.
|-
| no-dso || Disables the OpenSSL DSO API (the library offers a shared object abstraction layer). If you disable DSO, then you must disable Engines also
|-
| no-err || Removes all error function names and error reason text to reduce footprint
|-
| no-npn/no-nextprotoneg || Disables Next Protocol Negotiation (NPN). Use <tt>no-nextprotoneg</tt> for 1.1.0 and above; and <tt>no-npn</tt> otherwise
|-
| no-psk || Disables Preshared Key (PSK). PSK provides mutual authentication independent of trusted authorities, but it's rarely offered or used
|-
| no-srp || Disables Secure Remote Password (SRP). SRP provides mutual authentication independent of trusted authorities, but it's rarely offered or used
|-
| no-ec2m || Used when configuring FIPS Capable Library with a FIPS Object Module that only includes prime curves. That is, use this switch if you use <tt>openssl-fips-ecp-2.0.5</tt>.
|-
| no-weak-ssl-ciphers || Disables RC4. Available in OpenSSL 1.1.0 and above.
|-
| -DXXX || Defines XXX. For example, <tt>-DOPENSSL_NO_HEARTBEATS</tt>.
|-
| -DPEDANTIC || Defines PEDANTIC. The library will avoid some undefined behavior, like casting an unaligned byte array to a different pointer type. This define should be used if building OpenSSL with undefined behavior sanitizer (<tt>-fsanitize=undefined</tt>).
|-
| -DOPENSSL_USE_IPV6=0 || Disables IPv6. Useful if OpenSSL encounters incorrect or inconsistent platform headers and mistakenly enables IPv6. Must be passed to <tt>Configure</tt> manually.
|-
| -DNO_FORK || Defines NO_FORK. Disables calls to <tt>fork</tt>. Useful for operating systems like AppleTVOS, WatchOS, AppleTVSimulator and WatchSimulator.
|-
| -L''something'', -l''something'', -K''something'', -Wl,''something'' || Linker options, will become part of LDFLAGS.
|-
| -''anythingelse'', +''anythingelse'' || Compiler options, will become part of CFLAGS.
|}

'''''Note''''': on older OSes, like CentOS 5, BSD 5, and Windows XP or Vista, you will need to configure with <tt>no-async</tt> when building OpenSSL 1.1.0 and above. The configuration system does not detect lack of the Posix feature on the platforms.

'''''Note''''': you can verify compiler support for <tt>__uint128_t</tt> with the following:

<pre># gcc -dM -E - </dev/null | grep __SIZEOF_INT128__
#define __SIZEOF_INT128__ 16</pre>

=== PREFIX and OPENSSLDIR ===

<tt>--prefix</tt> and <tt>--openssldir</tt> control the configuration of installed components. The behavior and interactions of <tt>--prefix</tt> and <tt>--openssldir</tt> are slightly different between OpenSSL 1.0.2 and below, and OpenSSL 1.1.0 and above.

The '''''rule of thumb''''' to use when you want something that "just works" for all recent versions of OpenSSL, including OpenSSL 1.0.2 and 1.1.0, is:

* specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>
* set <tt>--prefix</tt> and <tt>--openssldir</tt> to the same location

One word of caution is ''avoid'' <tt>--prefix=/usr</tt> when OpenSSL versions are '''''not''''' [[Binary_Compatibility|binary compatible]]. You will replace the distro's version of OpenSSL with your version of OpenSSL. It will most likely break everything, including the package management system.

'''OpenSSL 1.0.2 and below'''

It is usually ''not'' necessary to specify <tt>--prefix</tt>. If <tt>--prefix</tt> is ''not'' specified, then <tt>--openssldir</tt> is used. However, specifying ''only'' <tt>--prefix</tt> may result in broken builds because the 1.0.2 build system attempts to build in a FIPS configuration.

You can ''omit'' If <tt>--prefix</tt> and use <tt>--openssldir</tt>. In this case, the paths for <tt>--openssldir</tt> will be used during configuration. If <tt>--openssldir</tt> is not specified, the the default <tt>/usr/local/ssl</tt> is used.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

'''OpenSSL 1.1.0 and above'''

OpenSSL 1.1.0 changed the behavior of install rules. You should specify both <tt>--prefix</tt> and <tt>--openssldir</tt> to ensure <tt>make install</tt> works as expected.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

=== Debug Configuration ===

From the list above, it's possible to quickly configure a "debug" build with <tt>./config -d</tt>. However, you can often get into a more amicable state ''without'' the [http://en.wikipedia.org/wiki/Electric_Fence Electric Fence] dependency by issuing:

<pre>$ ./config no-asm -g3 -O0 -fno-omit-frame-pointer -fno-inline-functions
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring OpenSSL version 1.1.0-pre5-dev (0x0x10100005L)
no-asm [option] OPENSSL_NO_ASM
...
Configuring for linux-x86_64
IsMK1MF =no
CC =gcc
CFLAG =-Wall -O3 -pthread -m64 -DL_ENDIAN -g3 -O0 -fno-omit-frame-pointer
...</pre>

Don't be alarmed about both <tt>-O3</tt> and <tt>-O0</tt>. The last setting ''"sticks"'', and that's the <tt>-O0</tt>.

If you are working in Visual Studio and you can't step into library calls, then see [http://stackoverflow.com/q/38249235 Step into not working, but can force stepping after some asm steps] on Stack Overflow.

=== Modifying Build Settings ===

Sometimes you need to work around OpenSSL's selections for building the library. For example, you might want to use <tt>-Os</tt> for a mobile device (rather than <tt>-O3</tt>), or you might want to use the <tt>clang</tt> compiler (rather than <tt>gcc</tt>).

In case like these, its' often easier to modify <tt>Configure</tt> and <tt>Makefile.org</tt> rather than trying to add targets to the configure scripts. Below is a patch that modifies <tt>Configure</tt> and <tt>Makefile.org</tt> for use under the iOS 7.0 SDK (which lacks <tt>gcc</tt> in <tt>/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/</tt>):

* Modifies <tt>Configure</tt> to use <tt>clang</tt>
* Modifies <tt>Makefile.org</tt> to use <tt>clang</tt>
* Modifies <tt>CFLAG</tt> to use <tt>-Os</tt>
* Modifies <tt>MAKEDEPPROG</tt> to use <tt>$(CC) -M</tt>

Setting and resetting of <tt>LANG</tt> is required on Mac OSX to work around a <tt>sed</tt> bug or limitation.

<pre>OLD_LANG=$LANG
unset LANG

sed -i "" 's|\"iphoneos-cross\"\,\"llvm-gcc\:-O3|\"iphoneos-cross\"\,\"clang\:-Os|g' Configure
sed -i "" 's/CC= cc/CC= clang/g' Makefile.org
sed -i "" 's/CFLAG= -O/CFLAG= -Os/g' Makefile.org
sed -i "" 's/MAKEDEPPROG=makedepend/MAKEDEPPROG=$(CC) -M/g' Makefile.org

export LANG=$OLD_LANG</pre>

After modification, be sure to dclean and configure again so the new settings are picked up:

<pre>make dclean

./config
make depend
make all
...</pre>

=== Using RPATHs ===

<tt>RPATH</tt>'s are supported by default on the BSD platforms, but not others. If you are working on Linux and compatibles, then you have to manually add an RPATH. One of the easiest ways to add a <tt>RPATH</tt> is to configure with it as shown below.

<pre>./config -Wl,-rpath,/usr/local/ssl/lib</pre>

For modern Linux you should also use <tt>-Wl,--enable-new-dtags</tt>. The linker option sets a <tt>RUNPATH</tt> as opposed to a <tt>RPATH</tt>. A <tt>RUNPATH</tt> allows library path overrides at runtime, while a <tt>RPATH</tt> does not.

<pre>./config -Wl,-rpath,/usr/local/ssl/lib -Wl,--enable-new-dtags</pre>

'''''Note well''''': you should use a <tt>RPATH</tt> or <tt>RUNPATH</tt> when building both OpenSSL and your program. If you don't add a <tt>RPATH</tt> or <tt>RUNPATH</tt> to both, then your program could runtime-link to the wrong version of OpenSSL. Linking against random versions of a security library is ''not'' a good idea.

You can also add an <tt>RPATH</tt> or <tt>RUNPATH</tt> by hard coding the <tt>RPATH</tt> into a configure line. For example, on Debian x86_64 open the file <tt>Configure</tt> in an editor, copy <tt>linux-x86_64</tt>, name it <tt>linux-x86_64-rpath</tt>, and make the following change to add the <tt>-rpath</tt> option. Notice the addition of <tt>-Wl,-rpath,...</tt> in two places.

<pre>"linux-x86_64-rpath", "gcc:-m64 -DL_ENDIAN -O3 -Wall -Wl,-rpath,/usr/local/ssl/lib::
-D_REENTRANT::-Wl,-rpath,/usr/local/ssl/lib -ldl:SIXTY_FOUR_BIT_LONG RC4_CHUNK DES_INT DES_UNROLL:
${x86_64_asm}:elf:dlfcn:linux-shared:-fPIC:-m64:.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR):::64",</pre>

Above, fields 2 and 6 were changed. They correspond to <tt>$cflag</tt> and <tt>$ldflag</tt> in OpenSSL's builds system.

Then, Configure with the new configuration:

<pre>$ ./Configure linux-x86_64-rpath shared no-ssl2 no-ssl3 no-comp \
--openssldir=/usr/local/ssl enable-ec_nistp_64_gcc_128</pre>

Finally, after <tt>make</tt>, verify the settings stuck:

<pre>$ readelf -d ./libssl.so | grep -i -E 'rpath|runpath'
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./libcrypto.so | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./apps/openssl | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]</pre>

Once you perform <tt>make install</tt>, then <tt>ldd</tt> will produce expected results:

<pre>$ ldd /usr/local/ssl/lib/libssl.so
linux-vdso.so.1 => (0x00007ffceff6c000)
ibcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007ff5eff96000)
...

$ ldd /usr/local/ssl/bin/openssl
linux-vdso.so.1 => (0x00007ffc30d3a000)
libssl.so.1.0.0 => /usr/local/ssl/lib/libssl.so.1.0.0 (0x00007f9e8372e000)
libcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007f9e832c0000)
...</pre>

=== FIPS Capable Library ===

If you want to use FIPS validated cryptography, you download, build and install the FIPS Object Module (<tt>openssl-fips-2.0.5.tar.gz</tt>) according to the [https://www.openssl.org/docs/fips/UserGuide-2.0.pdf FIPS User Guide 2.0] and [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.pdf FIPS 140-2 Security Policy]. You then download, build and install the FIPS Capable Library (<tt>openssl-1.0.1e.tar.gz</tt>).

When configuring the FIPS Capable Library, you must use <tt>fips</tt> as an option:

<pre>./config fips <other options ...></pre>

If you are configuring the FIPS Capable Library with only prime curves (<tt>openssl-fips-ecp-2.0.5.tar.gz</tt>), then you must configure with <tt>no-ec2m</tt>:

<pre>./config fips no-ec2m <other options ...></pre>

=== Compile Time Checking ===

If you disable an option during configure, you can check if it's available through <tt>OPENSSL_NO_*</tt> defines. OpenSSL writes the configure options to <tt><openssl/opensslconf.h></tt>. For example, if you want to know if SSLv3 is available, then you would perform the following in your code:

<pre>#include <openssl/opensslconf.h>
...

#if !defined(OPENSSL_NO_SSL3)
/* SSLv3 is available */
#endif</pre>

== Compilation ==

After configuring the library, you should run <tt>make</tt>. If prompted, there's usually no need to <tt>make depend</tt> since you are building from a clean download.

==== Quick ====

<pre>./config <nowiki><options ...> --openssldir=/usr/local/ssl</nowiki>
make
make test
sudo make install</pre>

Various options can be found examining the <tt>Configure</tt> file (there is a well commented block at its top). OpenSSL ships with SSLv2, SSLv3 and Compression enabled by default (see <tt>my $disabled</tt>), so you might want to use <tt>no-ssl2 no-ssl3</tt>, <tt>no-ssl3</tt>, and <tt>no-comp</tt>.

== Platfom specific ==

=== Linux ===

==== Intel ====

==== ARM ====

==== X32 (ILP32) ====

X32 uses the 32-bit data model (ILP32) on x86_64/amd64. To properly configure for X32 under current OpenSSL distributions, you must use <tt>Configure</tt> and use the x32 triplet:

<pre># ./Configure LIST | grep x32
linux-x32
...</pre>

Then:

<pre># ./Configure linux-x32
Configuring OpenSSL version 1.1.0-pre6-dev (0x0x10100006L)
no-asan [default] OPENSSL_NO_ASAN (skip dir)
...
Configuring for linux-x32
CC =gcc
CFLAG =-Wall -O3 -pthread -mx32 -DL_ENDIAN
SHARED_CFLAG =-fPIC
...</pre>

If using an amd64-compatible processor and GCC with that supports <tt>__uint128_t</tt>, then you usually add <tt>enable-ec_nistp_64_gcc_128 </tt> in addition to your other flags.

=== Windows ===
3noch wrote a VERY good guide in 2012 [https://web.archive.org/web/20161123004257/http://developer.covenanteyes.com/building-openssl-for-visual-studio// here] (PLEASE NOTE: the guide was written in 2012 and is no longer available at the original location; the link now points to an archived version at the Internet Archive Wayback Machine).

Like he said in his article, make absolutely sure to create separate directories for 32 and 64 bit versions.

==== W32 / Windows NT - Windows 9x ====

type INSTALL.W32

* you need Perl for Win32. Unless you will build on Cygwin, you will need ActiveState Perl, available from http://www.activestate.com/ActivePerl.
* one of the following C compilers:
** Visual C++
** Borland C
** GNU C (Cygwin or MinGW)
* Netwide Assembler, a.k.a. NASM, available from http://nasm.sourceforge.net/ is required if you intend to utilize assembler modules. Note that NASM is now the only supported assembler.

==== W64 ====

Read first the INSTALL.W64 documentation note containing some specific 64bits information.
See also INSTALL.W32 that still provides additonnal build information common to both the 64 and 32 bit versions.

You may be surprised: the 64bit artefacts are indeed output in the out32* sub-directories and bear names ending *32.dll. Fact is the 64 bit compile target is so far an incremental change over the legacy 32bit windows target. Numerous compile flags are still labelled "32" although those do apply to both 32 and 64bit targets.

The important pre-requisites are to have PERL available (for essential file processing so as to prepare sources and scripts for the target OS) and of course a C compiler like Microsoft Visual Studio for C/C++. Also note the procedure changed at OpenSSL 1.1.0 and is more streamlined. Also see [https://stackoverflow.com/q/39076244/608639 Why there is no ms\do_ms.bat after perl Configure VC-WIN64A] on Stack Overflow.

=== OpenSSL 1.1.0 ===

For OpenSSL 1.1.0 and above perform these steps:

# Ensure you have perl installed on your machine (e.g. ActiveState or Strawberry), and available on your %PATH%
# Ensure you have NASM installed on your machine, and available on your %PATH%
# Extract the source files to your folder, here <code>cd c:\myPath\openssl</code>
# Launch Visual Studio tool x64 Cross Tools Command prompt
# Goto your defined folder <code>cd c:\myPath\openssl</code>
# Configure for the target OS with <code>perl Configure VC-WIN64A</code> or other configurations to be found in the INSTALL file (e.g. UNIX targets).
## For instance: <code>perl Configure VC-WIN64A</code>.
# (''Optional'') In case you compiled before on 32 or 64-bits, make sure you run <code>nmake clean</code> to prevent trouble across 32 and 64-bits which share output folder.
# Now build with: <code>nmake</code>
# Output can be found in the '''root''' of your folder as '''libcrypto-1_1x64.dll''' and '''libssl-1_1-x64.dll''' (with all the build additionals such as .pdb .lik or static .lib). You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers libcrypto-1_1x64.dll | more</code>, and look at the FILE HEADER section.
# Test the code using the 'test' make target, by running <code>nmake test</code>.
# Reminder, clean your code to prevent issues the next time you compile for a different target. See step 7.

==== Windows CE ====
'' Not specified ''

=== OpenSSL 1.0.2 ===

For OpenSSL 1.0.2 and earlier the procedure is as follows.

# Ensure you have perl installed on your machine (e.g. ActiveState or Strawberry), and available on your %PATH%
# Ensure you have NASM installed on your machine, and available on your %PATH%
# launch a Visual Studio tool x64 Cross Tools Command prompt
# change to the directory where you have copied openssl sources <code>cd c:\myPath\openssl</code>
# configure for the target OS with the command <code>perl Configure VC-WIN64A</code>. You may also be interested to set more configuration options as documented in the general INSTALL note (for UNIX targets). For instance: <code>perl Configure VC-WIN64A</code>.
# prepare the target environment with the command: <code>ms\do_win64a</code>
# ensure you start afresh and notably without linkable products from a previous 32bit compile (as 32 and 64 bits compiling still share common directories) with the command: <code>nmake -f ms\ntdll.mak clean</code> for the DLL target and <code>nmake -f ms\nt.mak clean</code> for static libraries.
# build the code with: <code>nmake -f ms\ntdll.mak</code> (respectively <code>nmake -f ms\nt.mak</code> )
# the artefacts will be found in sub directories out32dll and out32dll.dbg (respectively out32 and out32.dbg for static libraries). The libcrypto and ssl libraries are still named libeay32.lib and ssleay32.lib, and associated includes in inc32 ! You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers out32dll/libeay32.lib | more</code>, and look at the FILE HEADER section.
# test the code using the various *test.exe programs in out32dll. Use the 'test' make target to run all tests as in <code>nmake -f ms\ntdll.mak test</code>
# we recommend that you move/copy needed includes and libraries from the "32" directories under a new explicit directory tree for 64bit applications from where you will import and link your target applications, similar to that explained in INSTALL.W32.

==== Windows CE ====

=== OS X ===

The earlier discussion presented a lot of information (and some of it had OS X information). Here are the TLDR versions to configure, build and install the library.

If configuring for 64-bit OS X, then use a command similar to:

<pre>./Configure darwin64-x86_64-cc shared enable-ec_nistp_64_gcc_128 no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macos-x86_64
make depend
sudo make install</pre>

If configuring for 32-bit OS X, then use a command similar to:

<pre>./Configure darwin-i386-cc shared no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macosx-i386
make depend
sudo make install</pre>

If you want to build a multiarch OpenSSL library, then see this answer on Stack Overflow: [http://stackoverflow.com/a/25531033/608639 Build Multiarch OpenSSL on OS X].

=== iOS ===

The following builds OpenSSL for iOS using the iPhoneOS SDK. The configuration avoids the dynamic library the DSO interface and engines.

If you run <tt>make install</tt>, then the headers will be installed in <tt>/usr/local/openssl-ios/include</tt> and libraries will be installed in <tt>/usr/local/openssl-ios/lib</tt>.

==== 32-bit ====

For OpenSSL 1.1.0 and above, a 32-bit iOS cross-compiles uses the <tt>ios-cross</tt> target, and options similar to <tt>--prefix=/usr/local/openssl-ios</tt>.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT OPENSSL_BN_ASM_GF2m SHA1_ASM SHA256_ASM SHA512_ASM AES_ASM BSAES_ASM GHASH_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

If you are working with OpenSSL 1.0.2 or below, then use the <tt>iphoneos-cross</tt> target.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure iphoneos-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios
Configuring for iphoneos-cross
no-dso [option]
no-engine [option] OPENSSL_NO_ENGINE (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-hw [option] OPENSSL_NO_HW
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS (skip dir)
no-zlib [default]
no-zlib-dynamic [default]
IsMK1MF=0
CC =clang
CFLAG =-DOPENSSL_THREADS -D_REENTRANT -O3 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fomit-frame-pointer -fno-common
...</pre>

==== 64-bit ====

For OpenSSL 1.1.0 , a 64-bit iOS cross-compiles uses the <tt>ios64-cross</tt> target, and <tt>--prefix=/usr/local/openssl-ios64</tt>. <tt>ios64-cross</tt>. There is no built-in 64-bit iOS support for OpenSSL 1.0.2 or below.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios64-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios64

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios64-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT SHA1_ASM SHA256_ASM SHA512_ASM VPAES_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

=== Android ===

Visit [[Android]] and [[FIPS Library and Android]].

=== More ===

==== VAX/VMS ====

I you wonder what are files ending with .com like test/testca.com those are VAX/VMX scripts.
This code is still maintained.

==== OS/2 ====

==== NetWare ====
5.x 6.x

==== HP-UX ====
[[HP-UX Itanium FIPS and OpenSSL build]]

==Autoconf==

OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be useful to detect either <tt>OPENSSL_init_ssl</tt> or <tt>SSL_library_init</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt>, you can use the following.

<pre>if test "$with_openssl" = yes ; then
dnl Order matters!
if test "$PORTNAME" != "win32"; then
AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], [AC_MSG_ERROR([library 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_CHECK_LIB(ssl, OPENSSL_init_ssl, [FOUND_SSL_LIB="yes"])
AC_CHECK_LIB(ssl, SSL_library_init, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssl' is required for OpenSSL])])
else
AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], [AC_MSG_ERROR([library 'eay32' or 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssleay32' or 'ssl' is required for OpenSSL])])
fi
fi</pre>

Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

[[Category:Shell level]]
[[Category:Installation]]
[[Category:Compilation]]

How to Integrate a Symmetric Cipher

2021-04-18T07:22:10Z

Levitte: /* Changes to Configure */

This page serves to provide a guideline on how to integrate a symmetric block cipher into OpenSSL 1.1.1. This integration procedure will cover all aspects of integration for both [[Libcrypto API|libcrypto]] and [[Libssl API|libssl]]. ARIA will be used as the example cipher throughout. ARIA is a basic C implementation without the extra complexity of assembly optimization and lacking support for some of the more complex chaining modes.

== Create the Cipher ==
All cryptographic functions are stored within the crypto/ directory and this is where ARIA's cipher will be implemented. To begin, create the directory.

mkdir crypto/aria

Now that the directory is created, the creation of the cipher can begin by opening:

vi crypto/aria/aria.c

You need to define two functions to do the lowest level encryption and decryption, although for ARIA they are both the same and only the first was actually defined:

void ARIA_encrypt(const unsigned char *in, unsigned char *out,
const ARIA_KEY *key)
void ARIA_decrypt(const unsigned char *in, unsigned char *out,
const ARIA_KEY *key)

Secondly, in the case of ARIA, you must also provide functions to set the encryption and decryption keys:

int ARIA_set_encrypt_key(const unsigned char *userKey, const int bits,
ARIA_KEY *key)
int ARIA_set_decrypt_key(const unsigned char *userKey, const int bits,
ARIA_KEY *key)

To prototype these functions you may create an aria_locl.h within crypto/aria/, however, the current preferred method is to prototype these functions in crypto/include/internal/aria.h. The prototyped functions contained within crypto/include/internal/aria.h can then be included by:

#include "internal/aria.h"

The last step in ARIA's low level implementation is to create a build.info file. This tells the Configure file in the root directory of OpenSSL on how to compile the files in ARIA's directory and configure the OpenSSL's library Makefile. The following is a simple example:

LIBS=../../libcrypto
SOURCE[../../libcrypto]=\
aria.c

In short, this tells Configure that the code contained within aria.c, relies on code contained within the rest of the [[Libcrypto API|libcrypto]] library and include ARIA in [[Libcrypto API|libcrypto]]. For further guidance on creating more complex build.info files please view the README file contained within the Configurations directory or view other cipher's implementations. For assembly optimized versions, there is a lot more involved and is beyond the scope of this guide. This impacts not only the cryptographic implementation but also the EVP layer.

== Changes to the Configuration ==
At this point the low level interface for ARIA has been implemented but we still need to modify the config and Configure files. This is necessary to have Configure recognize the build.info file previously created and the ability to detect an enable-aria flag.

=== Changes to config ===
The config file requires the ability to detect an enable-aria flag which is done by adding aria to the argument of a for loop:

for i in aes aria bf camellia cast des dh dsa ec hmac idea md2 md5 mdc2 rc2 rc4 rc5 ripemd rsa seed sha
do
if [ ! -d $THERE/crypto/$i ]
then
options="$options no-$i"
fi
done

=== Changes to Configure ===
The following will include ARIA when Configure searches for a build.info file.

$config{sdirs} = [
"objects",
"md2", "md4", "md5", "sha", "mdc2", "hmac", "ripemd", "whrlpool", "poly1305", "blake2", "siphash",
"des", "aes", "rc2", "rc4", "rc5", "idea", "aria", "bf", "cast", "camellia", "seed", "chacha", "modes",
"bn", "ec", "rsa", "dsa", "dh", "dso", "engine",
"buffer", "bio", "stack", "lhash", "rand", "err",
"evp", "asn1", "pem", "x509", "x509v3", "conf", "txt_db", "pkcs7", "pkcs12", "comp", "ocsp", "ui",
"cms", "ts", "srp", "cmac", "ct", "async", "kdf"
];

The following steps are optional if you would like to have the cipher be enabled or disabled, should someone compiling choose to do so. Start by including ARIA to the disablables table.

my @disablables = (
"afalgeng",
"aria",
"asan",
"asm",
"async",

Then, have ARIA disabled by default:
our %disabled = ( # "what" => "comment"
"aria" => "default",
"asan" => "default",
"crypto-mdebug" => "default",

== EVP Interface Integration ==
In short, the [[EVP]] provides a programmer with a high level interface to easily interact with low level OpenSSL cryptographic functions. A crypto/evp/e_aria.c file must be created to branch the gap between the high level EVP and the newly created ARIA cipher. At the bare minimum the file will include:
* Key struct
* EVP_CIPHER struct
* Naming the EVP_CIPHER
* Key Initialization Function
* Cipher Initialization Function

=== Key Structure ===
The structure of the key is up to the developer implementing the cipher.

/* ARIA subkey Structure */
typedef struct {
ARIA_KEY ks;
} EVP_ARIA_KEY;

This is a very simple example but this structure will include all necessary key material for both the encrypt and decrypt functions. It is also possible to include a function pointer in this struct to control whether the key is being used for encryption or decryption. This will be further explained below.

=== EVP_CIPHER struct ===
The following is the definition of an EVP_CIPHER struct found in crypto/crypto/include/internal/evp_int.h:

struct evp_cipher_st {
int nid;
int block_size;
/* Default value for variable length ciphers */
int key_len;
int iv_len;
/* Various flags */
unsigned long flags;
/* init key */
int (*init) (EVP_CIPHER_CTX *ctx, const unsigned char *key,
const unsigned char *iv, int enc);
/* encrypt/decrypt data */
int (*do_cipher) (EVP_CIPHER_CTX *ctx, unsigned char *out,
const unsigned char *in, size_t inl);
/* cleanup ctx */
int (*cleanup) (EVP_CIPHER_CTX *);
/* how big ctx->cipher_data needs to be */
int ctx_size;
/* Populate a ASN1_TYPE with parameters */
int (*set_asn1_parameters) (EVP_CIPHER_CTX *, ASN1_TYPE *);
/* Get parameters from a ASN1_TYPE */
int (*get_asn1_parameters) (EVP_CIPHER_CTX *, ASN1_TYPE *);
/* Miscellaneous operations */
int (*ctrl) (EVP_CIPHER_CTX *, int type, int arg, void *ptr);
/* Application data */
void *app_data;
} /* EVP_CIPHER */ ;

The ARIA EVP_CIPHER struct uses C preprocessor techniques to dynamically create the EVP_CIPHER struct and is outside the scope of this guide. Instead, the RC4 EVP_CIPHER struct is much easier to follow and mimic.

static const EVP_CIPHER r4_cipher = {
NID_rc4,
1, EVP_RC4_KEY_SIZE, 0,
EVP_CIPH_VARIABLE_LENGTH,
rc4_init_key,
rc4_cipher,
NULL,
sizeof(EVP_RC4_KEY),
NULL,
NULL,
NULL,
NULL
};

Notice the function pointers rc4_init_key and rc4_cipher as these are the functions to create the key and run the cipher respectively.

=== Naming the EVP_CIPHER ===
Again, since ARIA uses C preprocessor techniques to dynamically create the names of each of the modes of operation, we will take a look at RC4's implmentation as it is very easy to understand.

const EVP_CIPHER *EVP_rc4(void)
{
return (&r4_cipher);
}

Notice the name in this example is EVP_rc4() and r4_cipher is the name of the cipher initialization function.

=== Key Initialization Function ===

The following initializes the key for ARIA depending on the mode the user requests through the EVP interface.

static int aria_init_key(EVP_CIPHER_CTX *ctx, const unsigned char *key,
const unsigned char *iv, int enc)
{
int ret;
int mode = EVP_CIPHER_CTX_mode(ctx);
if (mode==EVP_CIPH_CFB_MODE||mode==EVP_CIPH_OFB_MODE||enc)
ret = ARIA_set_encrypt_key(key, EVP_CIPHER_CTX_key_length(ctx) * 8,
EVP_CIPHER_CTX_get_cipher_data(ctx));
else
ret = ARIA_set_decrypt_key(key, EVP_CIPHER_CTX_key_length(ctx) * 8,
EVP_CIPHER_CTX_get_cipher_data(ctx));
if(ret < 0) {
EVPerr(EVP_F_ARIA_INIT_KEY,EVP_R_ARIA_KEY_SETUP_FAILED);
return 0;
}
return 1;
}

An alternative approach is to use the enc parameter to determine whether the key is being used for encryption or decryption. The value of 1 for enc is encryption and 0 for decryption.

=== Cipher Initialization Function ===
Once the key has been created, the EVP will then call the cipher initialization function assigned in the EVP_CIPHER struct. This function will pass the parameters to the low level implementation of ARIA.

static void aria_cbc_encrypt(const unsigned char *in, unsigned char *out,
size_t len, const ARIA_KEY *key,
unsigned char *ivec, const int enc)
{
if (enc)
CRYPTO_cbc128_encrypt(in, out, len, key, ivec,
(block128_f) aria_encrypt);
else
CRYPTO_cbc128_decrypt(in, out, len, key, ivec,
(block128_f) aria_encrypt);
}

Another approach is to assign a function pointer in the creation of the key as to whether an encrypt or decrypt routine is about to happen using the enc parameter.

/* EVP_CIPHER struct */
typedef struct {
MYKEY k;
union {
void (*cipher) (MYKEY *k, size_t len, const unsigned char *in,
unsigned char *out);
} stream;
} EVP_MYCIPHER_KEY;

/* Key Initialization Function */
static int mycipher_init_key(EVP_CIPHER_CTX *ctx, const unsigned char *key,
const unsigned char *iv, int enc)
{
enc ? mycipher_enc_set_key(&data(ctx)->k) :
mycipher_dec_set_key(&data(ctx)->k);
data(ctx)->stream.cipher = enc ? encrypt_mycipher : decrypt_mycipher;
return 1;
}

/* Cipher Initialization Function */
static int mycipher(EVP_CIPHER_CTX *ctx, unsigned char *out,
const unsigned char *in, size_t inl)
{
(*data(ctx)->stream.cipher) (&data(ctx)->k, inl, in, out);
return 1;
}

Once completed, add e_aria.c into crypto/evp's build.info file.

LIBS=../../libcrypto
SOURCE[../../libcrypto]=\
encode.c digest.c evp_enc.c evp_key.c evp_cnf.c \
e_des.c e_bf.c e_idea.c e_des3.c e_camellia.c\
e_rc4.c e_aes.c names.c e_seed.c e_aria.c \

Now that e_aria.c has been built, we have to register it with the EVP subsystem. Modify crypto/evp/c_allc.c to register ARIA.

#ifndef OPENSSL_NO_ARIA
EVP_add_cipher(EVP_aria_128_ecb());
EVP_add_cipher(EVP_aria_128_cbc());
EVP_add_cipher(EVP_aria_128_cfb());
EVP_add_cipher(EVP_aria_128_cfb1());
EVP_add_cipher(EVP_aria_128_cfb8());
EVP_add_cipher(EVP_aria_128_ofb());
EVP_add_cipher_alias(SN_aria_128_cbc, "ARIA128");
EVP_add_cipher_alias(SN_aria_128_cbc, "aria128");
EVP_add_cipher(EVP_aria_192_ecb());
EVP_add_cipher(EVP_aria_192_cbc());
EVP_add_cipher(EVP_aria_192_cfb());
EVP_add_cipher(EVP_aria_192_cfb1());
EVP_add_cipher(EVP_aria_192_cfb8());
EVP_add_cipher(EVP_aria_192_ofb());
EVP_add_cipher_alias(SN_aria_192_cbc,
EVP_add_cipher_alias(SN_aria_192_cbc,
EVP_add_cipher(EVP_aria_256_ecb());
EVP_add_cipher(EVP_aria_256_cbc());
EVP_add_cipher(EVP_aria_256_cfb());
EVP_add_cipher(EVP_aria_256_cfb1());
EVP_add_cipher(EVP_aria_256_cfb8());
EVP_add_cipher(EVP_aria_256_ofb());
EVP_add_cipher_alias(SN_aria_256_cbc,
EVP_add_cipher_alias(SN_aria_256_cbc,
#endif

This adds all of the cipher chaining modes that were provided by the e_aria.c files except for CTR mode. It also includes some aliases for the CBC modes.

=== Error/Reason Codes ===

Error codes are handled dynamically in OpenSSL by using make update. make update will, in part, call make errors which will later execute util/mkerr.pl recursively on crypto/*.c, crypto/*/*.c, ssl/*.c, and apps/*.c. This script will scan for error and function codes and automatically add them as error/reason codes in the library. Essentially, it will look for strings that "look like" function or reason codes: basically anything consisting of all upper case and numerics which has _F_ or _R_ in it and which has the name of an error library at the start. For example, EVP_F_ARIA_INIT_KEY and EVP_R_ARIA_KEY_SETUP_FAILED. For more detailed documentation please view crypto/err/README and util/mkerr.pl.

== Crypto Objects ==
Crypto object IDs are used to map a name to a given ARIA cipher mode. To add object Ids for the ARIA suite, the crypto/objects/objects.txt file must be modified:

!Alias aria 1 2 410 200046 1 1
aria 1 : ARIA-128-ECB : aria-128-ecb
aria 2 : ARIA-128-CBC : aria-128-cbc
!Cname aria-128-cfb128
aria 3 : ARIA-128-CFB : aria-128-cfb
!Cname aria-128-ofb128
aria 4 : ARIA-128-OFB : aria-128-ofb
aria 5 : ARIA-128-CTR : aria-128-ctr

aria 6 : ARIA-192-ECB : aria-192-ecb
aria 7 : ARIA-192-CBC : aria-192-cbc
!Cname aria-192-cfb128
aria 8 : ARIA-192-CFB : aria-192-cfb
!Cname aria-192-ofb128
aria 9 : ARIA-192-OFB : aria-192-ofb
aria 10 : ARIA-192-CTR : aria-192-ctr

aria 11 : ARIA-256-ECB : aria-256-ecb
aria 12 : ARIA-256-CBC : aria-256-cbc
!Cname aria-256-cfb128
aria 13 : ARIA-256-CFB : aria-256-cfb
!Cname aria-256-ofb128
aria 14 : ARIA-256-OFB : aria-256-ofb
aria 15 : ARIA-256-CTR : aria-256-ctr

# There are no OIDs for these ARIA modes...
: ARIA-128-CFB1 : aria-128-cfb1
: ARIA-192-CFB1 : aria-192-cfb1
: ARIA-256-CFB1 : aria-256-cfb1
: ARIA-128-CFB8 : aria-128-cfb8
: ARIA-192-CFB8 : aria-192-cfb8
: ARIA-256-CFB8 : aria-256-cfb8

For more elaborate documentation inserting entries into crypto/objects/objects.txt, view the README file under crypto/objects/. Note that you must also run make update to automatically generate crypto/objects/obj_dat.h and crypto/objects/obj_mac.num.

== Update Headers ==
=== evp.h ===
To begin, the include/openssl/evp.h header requires three changes. Firstly, ARIA's modes must be added:

# ifndef OPENSSL_NO_ARIA
const EVP_CIPHER *EVP_aria_128_ecb(void);
const EVP_CIPHER *EVP_aria_128_cbc(void);
const EVP_CIPHER *EVP_aria_128_cfb1(void);
const EVP_CIPHER *EVP_aria_128_cfb8(void);
const EVP_CIPHER *EVP_aria_128_cfb128(void);
# define EVP_aria_128_cfb EVP_aria_128_cfb128
const EVP_CIPHER *EVP_aria_128_ofb(void);

...

const EVP_CIPHER *EVP_aria_256_ofb(void);
# endif

This is the name of the EVP_CIPHER created in e_aria.c. Secondly, we must add in the optional but recommended failure and reason codes:

# define EVP_F_ARIA_INIT_KEY 168

and

# define EVP_R_ARIA_KEY_SETUP_FAILED 163

== Utilities ==
In util/mkdir.pl ARIA must be added to the list of known_algorithms and the include path to the ARIA header file added (unless no_aria) is defined:

$crypto.=" include/openssl/aria.h" ; # unless $no_aria;

== TLS ==

At this point the cipher has now been implemented into the OpenSSL library and the following TLS section is optional. This section is only necessary if the cipher must be implemented as a TLS ciphersuite.

=== tls1.h ===
/include/openssl/tls1.h is where ARIA's cipher suite signatures will be defined. These come directly from RFC6209:

/* ARIA based ciphersuites from RFC6209 */
# define TLS1_CK_RSA_WITH_ARIA_128_CBC_SHA256 0x0300C03C
# define TLS1_CK_RSA_WITH_ARIA_256_CBC_SHA384 0x0300C03D

...

# define TLS1_CK_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 0x0300C071

It is important to note that this is where the key exchange, authentication, and MAC algorithms can be chosen by name and later implemented in s3_lib.c. Once the signatures are defined, the text representations need to be defined:

/* ARIA based ciphersuites from RFC6209 */
# define TLS1_TXT_RSA_WITH_ARIA_128_CBC_SHA256 "ARIA128-CBC-SHA256"
# define TLS1_TXT_RSA_WITH_ARIA_256_CBC_SHA384 "ARIA256-CBC-SHA384"

...

# define TLS1_TXT_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 "ECDHE-PSK-ARIA256-CBC-SHA384"

=== ssl.h ===
/include/openssl/ssl.h needs the string names to be later used in the ARIA cipher suites.

# define SSL_TXT_ARIA128 "ARIA128"
# define SSL_TXT_ARIA256 "ARIA256"
# define SSL_TXT_ARIA "ARIA"

=== s3_lib.c ===
To use ARIA with TLS, it is necessary to define the suite combinations that are legal as per the various standards. These are defined in the ssl/s3_lib.c file. In all cases the security level is considered high, the suite is not a default, and is supported only in TLS 1.2.

#ifndef OPENSSL_NO_ARIA
{
1,
TLS1_TXT_RSA_WITH_ARIA_128_CBC_SHA256,
TLS1_CK_RSA_WITH_ARIA_128_CBC_SHA256,
SSL_kRSA,
SSL_aRSA,
SSL_ARIA128,
SSL_SHA256,
TLS1_2_VERSION, TLS1_2_VERSION,
DTLS1_2_VERSION, DTLS1_2_VERSION,
SSL_NOT_DEFAULT | SSL_HIGH,
SSL_HANDSHAKE_MAC_SHA256 | TLS1_PRF_SHA256,
128,
128,
},
{
1,
TLS1_TXT_RSA_WITH_ARIA_256_CBC_SHA384,
TLS1_CK_RSA_WITH_ARIA_256_CBC_SHA384,
SSL_kRSA,
SSL_aRSA,
SSL_ARIA256,
SSL_SHA384,
TLS1_2_VERSION, TLS1_2_VERSION,
DTLS1_2_VERSION, DTLS1_2_VERSION,
SSL_NOT_DEFAULT | SSL_HIGH,
SSL_HANDSHAKE_MAC_SHA384 | TLS1_PRF_SHA384,
256,
256,
},

...

{
1,
TLS1_TXT_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384,
TLS1_CK_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384,
SSL_kECDHEPSK,
SSL_aPSK,
SSL_ARIA256,
SSL_SHA384,
TLS1_2_VERSION, TLS1_2_VERSION,
DTLS1_2_VERSION, DTLS1_2_VERSION,
SSL_NOT_DEFAULT | SSL_HIGH,
SSL_HANDSHAKE_MAC_SHA384 | TLS1_PRF_SHA384,
256,
256,
},
# endif /* OPENSSL_NO_EC */
# endif /* OPENSSL_NO_PSK */
#endif /* OPENSSL_NO_ARIA */

It is critical to note that if the cipher suite implementation uses eliptical curve (EC) for instance, that the cipher suite implementation is inside the OPENSSL_NO_EC preprocessor directives.

=== ssl_ciph.c ===
The ssl/ssl_ciph.c file needs indices for the ARIA ciphers available from TLS. In the initial table of #defines:

#define SSL_ENC_ARIA128_IDX 20
#define SSL_ENC_ARIA256_IDX 21
#define SSL_ENC_NUM_IDX 22

Later in the ssl_cipher_table_cipher table of NIDs for each cipher:

{SSL_ARIA128, NID_aria_128_cbc}, /* SSL_ENC_ARIA128_IDX 20 */
{SSL_ARIA256, NID_aria_256_cbc} /* SSL_ENC_ARIA256_IDX 21 */

This maps libssl's request of ARIA to ARIA's respective NID value which will later be looked up to dive into ARIA's implementation within libcrypto. This can be seen as bridging the gap between libssl and libcrypto. To continue, alias's must be created for the cipher suite:

{0, SSL_TXT_ARIA128, 0, 0, 0, SSL_ARIA128, 0, 0, 0, 0, 0, 0},
{0, SSL_TXT_ARIA256, 0, 0, 0, SSL_ARIA256, 0, 0, 0, 0, 0, 0},
{0, SSL_TXT_ARIA, 0, 0, 0, SSL_ARIA128 | SSL_ARIA256, 0, 0, 0, 0, 0, 0},

Lastly, add ARIA's description into the switch statement within the SSL_CIPHER_description function:

case SSL_ARIA128:
enc = "ARIA(128)";
break;
case SSL_ARIA256:
enc = "ARIA(256)";
break;

=== ssl/ssl_init.c ===
The ssl/ssl_init.c function needs to conditionally register the ARIA ciphers and can be inserted along with the other ciphers:

#ifndef OPENSSL_NO_ARIA
EVP_add_cipher(EVP_aria_128_cbc());
EVP_add_cipher(EVP_aria_256_cbc());
#endif
#ifndef OPENSSL_NO_DES
EVP_add_cipher(EVP_des_cbc());
EVP_add_cipher(EVP_des_ede3_cbc());
#endif

=== ssl/ssl_locl.h ===
This file contains the bits for SSL_ARIA as well as the group definition:

# define SSL_ARIA128 0x00100000L
# define SSL_ARIA256 0x00200000L
# define SSL_ARIA (SSL_ARIA128|SSL_ARIA256)

=== ssl/t1_trce.c ===
Finally, the ssl/t1_trce.c file contains a table of the protocol numbers and text descriptions for all legal TLS protocols. If your cipher suites are not already present in this file, they should be added to it. This step proved unnecessary for ARIA because the required definitions were already present.

== Unit Testing ==
OpenSSL has a built in test suite that can be leveraged for ARIA. The test/evptests.txt unit test vectors for ARIA need to be added:

# ARIA test vectors from RFC5794
Cipher = ARIA-128-ECB
Key = 000102030405060708090a0b0c0d0e0f
Operation = ENCRYPT
Plaintext = 00112233445566778899aabbccddeeff
Ciphertext = d718fbd6ab644c739da95f3be6451778

Cipher = ARIA-128-ECB
Key = 000102030405060708090a0b0c0d0e0f
Operation = DECRYPT
Plaintext = 00112233445566778899aabbccddeeff
Ciphertext = d718fbd6ab644c739da95f3be6451778

Cipher = ARIA-192-ECB
Key = 000102030405060708090a0b0c0d0e0f1011121314151617
Operation = ENCRYPT
Plaintext = 00112233445566778899aabbccddeeff
Ciphertext = 26449c1805dbe7aa25a468ce263a9e79

Cipher = ARIA-192-ECB
Key = 000102030405060708090a0b0c0d0e0f1011121314151617
Operation = DECRYPT
Plaintext = 00112233445566778899aabbccddeeff
Ciphertext = 26449c1805dbe7aa25a468ce263a9e79

Cipher = ARIA-256-ECB
Key = 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
Operation = ENCRYPT
Plaintext = 00112233445566778899aabbccddeeff
Ciphertext = f92bd7c79fb72e2f2b8f80c1972d24fc

Cipher = ARIA-256-ECB
Key = 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
Operation = DECRYPT
Plaintext = 00112233445566778899aabbccddeeff
Ciphertext = f92bd7c79fb72e2f2b8f80c1972d24fc

These values are pulled from ARIA'a RFC and others can be added if desired. Once the integration is complete with the remaining steps below, the test suite can be ran with make test.

== Applications ==
The apps/openssl.c needs to be able to print that it does not support ARIA via the list_disabled function:

#ifdef OPENSSL_NO_ARIA
BIO_puts(bio_out, "ARIA\n");
#endif

The apps/progs.h needs the available cipher definitions included in the functions array:

#ifndef OPENSSL_NO_ARIA
{ FT_cipher, "aria-128-cbc", enc_main, enc_options },
#endif
#ifndef OPENSSL_NO_ARIA
{ FT_cipher, "aria-128-ecb", enc_main, enc_options },
#endif
#ifndef OPENSSL_NO_ARIA
{ FT_cipher, "aria-192-cbc", enc_main, enc_options },
#endif
#ifndef OPENSSL_NO_ARIA
{ FT_cipher, "aria-192-ecb", enc_main, enc_options },
#endif
#ifndef OPENSSL_NO_ARIA
{ FT_cipher, "aria-256-cbc", enc_main, enc_options },
#endif
#ifndef OPENSSL_NO_ARIA
{ FT_cipher, "aria-256-ecb", enc_main, enc_options },
#endif

The apps/progs.pl program needs to know about the ARIA cipher:

"aria-128-cbc", "aria-128-ecb",
"aria-192-cbc", "aria-192-ecb",
"aria-256-cbc", "aria-256-ecb",

=== Speed Test ===
Just as it was explained in the TLS section, the speed test integration is optional and only needs to be implemented if desired. That being said, it is possible to natively integrate ARIA into OpenSSL's built in speed test, however, once a cipher is integrated into the EVP the speed test can access the cipher using the -evp flag. For completeness sake, the following steps are necessary to manually integrated ARIA into OpenSSL's speedtest.

First the ARIA header file needs to be conditionally included:

#ifndef OPENSSL_NO_ARIA
# include <openssl/aria.h>
#endif

The number of algorithms increased:

#define ALGOR_NUM 33

The algorithms themselves defined in the names array:

"aria-128 cbc", "aria-192 cbc", "aria-256 cbc"

The speed_options indicies defined:

#define D_CBC_128_ARIA 30
#define D_CBC_192_ARIA 31
#define D_CBC_256_ARIA 32

The doit_choices text mapping defined:

#ifndef OPENSSL_NO_ARIA
{"aria-128-cbc", D_CBC_128_ARIA},
{"aria-192-cbc", D_CBC_192_ARIA},
{"aria-256-cbc", D_CBC_256_ARIA},
#endif

The initialisation key vectors defined:

#ifndef OPENSSL_NO_ARIA
static const unsigned char akey24[24] = {
0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0,
0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0, 0x12,
0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0, 0x12, 0x34
};
static const unsigned char akey32[32] = {
0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0,
0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0, 0x12,
0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0, 0x12, 0x34,
0x78, 0x9a, 0xbc, 0xde, 0xf0, 0x12, 0x34, 0x56
};
ARIA_KEY aria_ks1, aria_ks2, aria_ks3;
#endif

The command line processing adjusted:

# ifndef OPENSSL_NO_ARIA
if (strcmp(*argv, "aria") == 0) {
doit[D_CBC_128_ARIA] = doit[D_CBC_192_ARIA] =
doit[D_CBC_256_ARIA] = 1;
continue;
}
# endif

Keys are set:

# ifndef OPENSSL_NO_ARIA
ARIA_set_encrypt_key(key16, 128, &aria_ks1);
ARIA_set_encrypt_key(akey24, 192, &aria_ks2);
ARIA_set_encrypt_key(akey32, 256, &aria_ks3);
# endif

Counts initialized:

c[D_CBC_128_ARIA][0] = count;
c[D_CBC_192_ARIA][0] = count;
c[D_CBC_256_ARIA][0] = count;

and adjusted:

c[D_CBC_128_ARIA][i] = c[D_CBC_128_ARIA][i - 1] * l0 / l1;
c[D_CBC_192_ARIA][i] = c[D_CBC_192_ARIA][i - 1] * l0 / l1;
c[D_CBC_256_ARIA][i] = c[D_CBC_256_ARIA][i - 1] * l0 / l1;

Finally, the actual speed testing code:

#ifndef OPENSSL_NO_ARIA
if (doit[D_CBC_128_ARIA]) {
if (async_jobs > 0) {
BIO_printf(bio_err, "Async mode is not supported with %s\n",
names[D_CBC_128_ARIA]);
doit[D_CBC_128_ARIA] = 0;
}
for (testnum = 0; testnum < SIZE_NUM&&async_init == 0; testnum++) {
print_message(names[D_CBC_128_ARIA], c[D_CBC_128_ARIA][testnum],
lengths[testnum]);
Time_F(START);
for (count = 0, run = 1; COND(c[D_CBC_128_ARIA][testnum]); count++)
ARIA_cbc_encrypt(loopargs[0].buf, loopargs[0].buf,
(size_t)lengths[testnum], &aria_ks1,
iv, ARIA_ENCRYPT);
d = Time_F(STOP);
print_result(D_CBC_128_ARIA, testnum, count, d);
}
}
if (doit[D_CBC_192_ARIA]) {
if (async_jobs > 0) {
BIO_printf(bio_err, "Async mode is not supported with %s\n",
names[D_CBC_192_ARIA]);
doit[D_CBC_192_ARIA] = 0;
}
for (testnum = 0; testnum < SIZE_NUM&&async_init == 0; testnum++) {
print_message(names[D_CBC_192_ARIA], c[D_CBC_192_ARIA][testnum],
lengths[testnum]);
if (async_jobs > 0) {
BIO_printf(bio_err, "Async mode is not supported, exiting...");
exit(1);
}
Time_F(START);
for (count = 0, run = 1; COND(c[D_CBC_192_ARIA][testnum]); count++)
ARIA_cbc_encrypt(loopargs[0].buf, loopargs[0].buf,
(size_t)lengths[testnum], &aria_ks2,
iv, ARIA_ENCRYPT);
d = Time_F(STOP);
print_result(D_CBC_192_ARIA, testnum, count, d);
}
}
if (doit[D_CBC_256_ARIA]) {
if (async_jobs > 0) {
BIO_printf(bio_err, "Async mode is not supported with %s\n",
names[D_CBC_256_ARIA]);
doit[D_CBC_256_ARIA] = 0;
}
for (testnum = 0; testnum < SIZE_NUM&&async_init == 0; testnum++) {
print_message(names[D_CBC_256_ARIA], c[D_CBC_256_ARIA][testnum],
lengths[testnum]);
Time_F(START);
for (count = 0, run = 1; COND(c[D_CBC_256_ARIA][testnum]); count++)
ARIA_cbc_encrypt(loopargs[0].buf, loopargs[0].buf,
(size_t)lengths[testnum], &aria_ks3,
iv, ARIA_ENCRYPT);
d = Time_F(STOP);
print_result(D_CBC_256_ARIA, testnum, count, d);

}
}
#endif

== Manual Pages ==
OpenSSL has the strong philosophy of containing documentation and manual pages for all code. The relevant manual pages require updating because they will gain automatic support for ARIA. Many of these pages require the same automatic change. These are doc/man1/dsa.pod, doc/man1/gendsa.pod, doc/man1/genrsa.pod and doc/man1/rsa.pod. The new command line options need to be added to the documentation:

[B<-aria128>]
[B<-aria192>]
[B<-aria256>]

and updating the brief description line:

=item B<-aes128|-aes192|-aes256|-aria128|-aria192|-aria256|-camellia128|- camellia192|-camellia256|-des|-des3|-idea>

The doc/man1/pkcs12.pod requires that the new ciphers are added to the command line options:

[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -aria128 | -aria192 | -aria256 | -camellia128 | -camellia192 | -camellia256 | -nodes>]

and a description is added in the body of the text:

=item B<-aria128>, B<-aria192>, B<-aria256>

use ARIA to encrypt private keys before outputting.

The doc/man1/ciphers.pod file requires a section describing the new cipher:

=item B<ARIA128>, B<ARIA256>, B<ARIA>

cipher suites using 128 bit ARIA, 256 bit ARIA or either 128 or 256 bit ARIA.

And an update to the cipher suites that are supported:

=head2 ARIA cipher suites from RFC6209, extending TLS v1.2

TLS_RSA_WITH_ARIA_128_CBC_SHA256 ARIA128-CBC-SHA256
TLS_RSA_WITH_ARIA_256_CBC_SHA384 ARIA256-CBC-SHA384
TLS_DHE_DSS_WITH_ARIA_128_CBC_SHA256 DHE-DSS-ARIA128-CBC-SHA256
TLS_DHE_DSS_WITH_ARIA_256_CBC_SHA384 DHE-DSS-ARIA256-CBC-SHA384
TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256 DHE-RSA-ARIA128-CBC-SHA256
TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384 DHE-RSA-ARIA256-CBC-SHA384
TLS_DH_anon_WITH_ARIA_128_CBC_SHA256 DH-anon-ARIA128-CBC-SHA256
TLS_DH_anon_WITH_ARIA_256_CBC_SHA384 DH-anon-ARIA256-CBC-SHA384
TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 ECDHE-ECDSA-ARIA128-CBC-SHA256
TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 ECDHE-ECDSA-ARIA256-CBC-SHA384
TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 ECDHE-RSA-ARIA128-CBC-SHA256
TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 ECDHE-RSA-ARIA256-CBC-SHA384

== Building ==
There are a number of commands to build and test everything. Note the enable-aria to include it in the building of OpenSSL:

./config enable-aria &&
make &&
make update &&
make test &&
LD_LIBRARY_PATH=. apps/openssl speed aria

Also try a build with aria disabled:

./config no-aria &&
make &&
make test &&

Both sequences should work and the tests should all pass.

Diffie Hellman

2020-10-09T03:42:37Z

Levitte: /* Diffie-Hellman Standards */

The Diffie-Hellman algorithm provides the capability for two communicating parties to agree upon a shared secret between them. Its an agreement scheme because both parties add material used to derive the key (as opposed to transport, where one party selects the key). The shared secret can then be used as the basis for some encryption key to be used for further communication.

If Alice and Bob wish to communicate with each other, they first agree between them a large prime number p, and a generator (or base) g (where 0 < g < p).

Alice chooses a secret integer a (her private key) and then calculates ga mod p (which is her public key).
Bob chooses his private key b, and calculates his public key in the same way.

Alice and Bob then send each other their public keys. Alice now knows a and Bob's public key gb mod p. She is not able to calculate the value b from Bob's public key as this is a hard mathematical problem (known as the discrete logarithm problem). She can however calculate (gb)a mod p = gab mod p.

Bob knows b and ga, so he can calculate (ga)b mod p = gab mod p. Therefore both Alice and Bob know a shared secret gab mod p. Eve who was listening in on the communication knows p, g, Alice's public key (ga mod p) and Bob's public key (gb mod p). She is unable to calculate the shared secret from these values.

In static-static mode both Alice and Bob retain their private/public keys over multiple communications. Therefore the resulting shared secret will be the same every time. In ephemeral-static mode one party will generate a new private/public key every time, thus a new shared secret will be generated.

==Diffie-Hellman Standards==

There are a number of standards relevant to Diffie-Hellman key agreement. Some of the key ones are:

* [ftp://ftp.rsasecurity.com/pub/pkcs/ascii/pkcs-3.asc PKCS 3] defines the basic algorithm and data formats to be used.
* ANSI X9.42 is a later standard than PKCS 3 and provides further guidance on its use (note OpenSSL does not support ANSI X9.42 in the released versions - support is available in the as yet unreleased 1.0.2 and 1.1.0)
* [http://www.ietf.org/rfc/rfc2631.txt RFC 2631] summarizes the key points of ANSI X9.42
* [http://www.ietf.org/rfc/rfc5114.txt RFC 5114] defines 3 standard sets of parameters for use with Diffie-Hellman (OpenSSL will have built-in support for these parameters from OpenSSL 1.0.2 - not yet released)
* [http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf NIST SP 800-56A] is a NIST publication that provides recommendations on the implementation of X9.42

==Diffie-Hellman in SSL/TLS==

There are three versions of Diffie-Hellman used in SSL/TLS.

* Anonymous Diffie-Hellman
* Fixed Diffie-Hellman
* Ephemeral Diffie-Hellman

'''Anonymous Diffie-Hellman''' uses Diffie-Hellman, but without authentication. Because the keys used in the exchange are not authenticated, the protocol is susceptible to Man-in-the-Middle attacks. Note: if you use this scheme, a call to <tt>SSL_get_peer_certificate</tt> will return <tt>NULL</tt> because you have selected an anonymous protocol. This is the only time <tt>SSL_get_peer_certificate</tt> is allowed to return <tt>NULL</tt> under normal circumstances.

You should not use Anonymous Diffie-Hellman. You can prohibit its use in your code by using <tt>"!ADH"</tt> in your call to <tt>SSL_set_cipher_list</tt>.

'''Fixed Diffie-Hellman''' embeds the server's public parameter in the certificate, and the CA then signs the certificate. That is, the certificate contains the Diffie-Hellman public-key parameters, and those parameters never change.

'''Ephemeral Diffie-Hellman''' uses temporary, public keys. Each instance or run of the protocol uses a different public key. The authenticity of the server's temporary key can be verified by checking the signature on the key. Because the public keys are temporary, a compromise of the server's long term signing key ''does not'' jeopardize the privacy of past sessions. This is known as ''Perfect Forward Secrecy (PFS)''.

You should always use Ephemeral Diffie-Hellman because it provides PFS. You can specify ephemeral methods by providing <tt>"kEECDH:kEDH"</tt> in your call to <tt>SSL_set_cipher_list</tt>.

==Working with Parameters and Generating Keys==

The first step with the Diffie-Hellman algorithm is to ensure that both parties are using the same set of parameters (i.e. the same values for p and g). Since parameter generation can be an expensive process this is normally done once in advance and then the same set of parameters are used over many key exchanges. A new set of parameters can be generated by OpenSSL, or alternatively there is support for built-in standard sets of parameters.

<pre>/* Use built-in parameters */
if(NULL == (params = EVP_PKEY_new())) handleErrors();
if(1 != EVP_PKEY_set1_DH(params,DH_get_2048_256())) handleErrors();

/* Create context for the key generation */
if(!(kctx = EVP_PKEY_CTX_new(params, NULL))) handleErrors();

/* Generate a new key */
if(1 != EVP_PKEY_keygen_init(kctx)) handleErrors();
if(1 != EVP_PKEY_keygen(kctx, &dhkey)) handleErrors();</pre>

To generate your own parameters refer to [[EVP Key and Parameter Generation]].

Note: The function <code>DH_get_2048_256</code> is scheduled for release in OpenSSL 1.0.2; it is not available in 1.0.1e or earlier.

==Generating a Shared Secret==

Having obtained a private/public key pair you need to also obtain the public key of the other communicating party. Refer to [[EVP Key Agreement]] for information on how to agree a shared secret.

==Using the Low Level APIs==

Users of the OpenSSL library are expected to normally use the EVP method for working with Diffie Hellman as described above and on the [[EVP Key Agreement]] page. The EVP api is implemented by a lower level Diffie Hellman API. In some circumstances, expert users may need to use the low level api. '''This is not recommended for most users'''. However, if you need to use this then an example of use is shown below. The manual page for the low level API is available here: [[Manual:dh(3)]]

<pre>DH *privkey;
int codes;
int secret_size;

/* Generate the parameters to be used */
if(NULL == (privkey = DH_new())) handleErrors();
if(1 != DH_generate_parameters_ex(privkey, 2048, DH_GENERATOR_2, NULL)) handleErrors();

if(1 != DH_check(privkey, &codes)) handleErrors();
if(codes != 0)
{
/* Problems have been found with the generated parameters */
/* Handle these here - we'll just abort for this example */
printf("DH_check failed\n");
abort();
}

/* Generate the public and private key pair */
if(1 != DH_generate_key(privkey)) handleErrors();

/* Send the public key to the peer.
* How this occurs will be specific to your situation (see main text below) */

/* Receive the public key from the peer. In this example we're just hard coding a value */
BIGNUM *pubkey = NULL;
if(0 == (BN_dec2bn(&pubkey, "01234567890123456789012345678901234567890123456789"))) handleErrors();

/* Compute the shared secret */
unsigned char *secret;
if(NULL == (secret = OPENSSL_malloc(sizeof(unsigned char) * (DH_size(privkey))))) handleErrors();

if(0 > (secret_size = DH_compute_key(secret, pubkey, privkey))) handleErrors();

/* Do something with the shared secret */
/* Note secret_size may be less than DH_size(privkey) */
printf("The shared secret is:\n");
BIO_dump_fp(stdout, secret, secret_size);

/* Clean up */
OPENSSL_free(secret);
BN_free(pubkey);
DH_free(privkey);

</pre>

There are (currently) no DH_ level routines to read and write
a public OR private key, but the generic PUBKEY and
PrivateKey routines do so as an X.509 SubjectPublickKeyInfo structure (aka SPKI or PKCS#8). This includes the parameters plus the public key (and the private key for the PrivateKey routines) (see [[Manual:Pem(3)]]).

There are three possible cases:
* ephemeral parameters: A must send new parameters AND the public key to the peer (B), who needs to send back only their public key (although it may be convenient to embed it in an SPKI structure)
* static but undistributed parameters: effectively the same
* pre-distributed parameters: A only needs to send their public key, but may embed in an SPKI structure; B doesn't need to wait for A to get parameters but may wait anyway, and only needs to send B's public key but may embed it in an SPKI structure.

==See also==
* [[EVP Key Agreement]]
* [[Elliptic Curve Diffie Hellman]]
* [[EVP]]
* [[Libcrypto API]]

[[Category:Cryptographic Algorithm]]
[[Category:C level]]
[[Category:Examples]]
[[Category:Public Key Algorithm]]

OpenSSL 3.0

2020-05-05T03:38:39Z

Levitte: /* Installation and Compilation of OpenSSL 3.0 */

__NUMBEREDHEADINGS__ 

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

=== Engines and "METHOD" APIs ===

The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or modifies custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely bypass provider selection and configuration, with unintended consequences. This is particularly relevant for applications written to use the OpenSSL 3.0 FIPS module, as detailed below.
Authors and maintainers of external engines are strongly encouraged to refactor their code transforming engines into providers using the new Provider API and avoiding deprecated methods.

=== Versioning Scheme ===

The OpenSSL versioning scheme has changed with the 3.0 release. The new versioning scheme has this format:

MAJOR.MINOR.PATCH

For version 1.1.1 and below different patch levels were indicated by a letter at the end of the release version number. This will no longer be used and instead the patch level is indicated by the final number in the version. A change in the second (MINOR) number indicates that new features may have been added. OpenSSL versions with the same major number are API and ABI compatible. If the major number changes then API and ABI compatibility is not guaranteed.

=== Other major new features ===

* Implementation of the Certificate Management Protocol (CMP, RFC 4210) also covering CRMF (RFC 4211) and HTTP transfer (RFC 6712)
* A proper HTTP(S) client in libcrypto supporting GET and POST, redirection, plain and ASN.1-encoded contents, proxies, and timeouts
* EVP_KDF APIs have been introduced for working with Key Derivation Functions
* EVP_MAC APIs have been introduced for working with MACs
* Support for Linux Kernel TLS

=== Other notable deprecations and changes ===

* The function code part of an OpenSSL error code is no longer relevant and is always set to zero. Related functions are deprecated.

* The STACK and HASH macro's have been cleaned up, so that the type-safe wrappers are declared everywhere and implemented once. See the manpage at https://www.openssl.org/docs/manmaster/man3/DEFINE_STACK_OF.html for stack, and hopefully soon once the PR is merged, https://www.openssl.org/docs/manmaster/man3/DECLARE_LHASH_OF.html (but not yet as of this writing).

== Installation and Compilation of OpenSSL 3.0 ==

Please refer to the INSTALL.md file in the top of the distribution for instructions on how to build and install OpenSSL 3.0. Please also refer to the various platform specific NOTES files for your specific platform.

NOTE: The OpenSSL 3.0 alpha 1 release contains an error introduced during the release process which results in a failed compilation. There are two workarounds to choose between:

* apply [https://github.com/openssl/openssl/pull/11624/files the patch from github PR #11624].
* edit the VERSION file in the top of the distribution to remove the quotes around the date on the RELEASE_DATE line, i.e. make that line look like this:

RELEASE_DATE=23 Apr 2020

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0 can be found on the [[OpenSSL_1.1.0_Changes|OpenSSL 1.1.0 Changes]] page.

=== Upgrading from 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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\ossl-modules\fips.dll' on Windows.

To complete the installation you need to run the 'fipsinstall' command line application. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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 (e.g. in the application or via config), then this is the provider that will be used. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. If another provider has already been loaded then it won't be loaded automatically. Therefore if you want to use it in conjunction with other providers then you must load it explicitly. 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 may be 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. In order to guarantee that the default provider is not automatically loaded, the null provider can be loaded instead. This can be useful if you are using non-default library contexts and want to ensure that the default library context is never used "by accident".

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them.
This is a minimal config file example to load and activate both the legacy and the default provider in the default library context.

openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
legacy = legacy_sect

[default_sect]
activate = 1

[legacy_sect]
activate = 1

It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

/* Load Multiple providers into the default (NULL) library context */
legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;

/*
* Setting the library ctx to NULL here fetches the algorithm from the providers loaded
* into the default library context
*/
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

/* Explicit fetches return a dynamic object that must be freed */
EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

If no specific property query is required then NULL can be passed for the last argument. In any case any supplied property query is combined with the default property query. If nothing else is specified then the default property query is empty. However this can be changed so that every fetch automatically inherits these default properties. Default properties can either be set programmatically or via a config file. See the section [[OpenSSL 3.0#Loading the FIPS module at the same time as other providers|Loading the FIPS module at the same time as other providers]] for an example of how to do this.

Note that default properties are not currently functional in the OpenSSL 3.0 alpha 1 release.

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve. Note that the old functions FIPS_mode() and FIPS_mode_set() are present, but always fail in OpenSSL 3.0 so you should not use them.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

NOTE: Default properties are currently not functional in the OpenSSL 3.0 alpha 1 release - see the known issues below

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

In addition to using properties to separate usage of the FIPS module from other usages this can also be achieved using library contexts. In this example we create two library contexts. In one we assume the existence of a config file called "openssl-fips.cnf" that automatically loads and configures the FIPS provider. The other library context will just use the default provider.

OPENSSL_CTX *fipslibctx, *nonfipslibctx;
OSSL_PROVIDER *defctxnull = NULL;
EVP_MD *fipssha256 = NULL, *nonfipssha256 = NULL;
int ret = 1;

/*
* Create two non-default library contexts. One for fips usage and one for
* non-fips usage
*/
fipslibctx = OPENSSL_CTX_new();
nonfipslibctx = OPENSSL_CTX_new();
if (fipslibctx == NULL || nonfipslibctx == NULL)
goto err;

/* Prevent anything from using the default library context */
defctxnull = OSSL_PROVIDER_load(NULL, "null");

/*
* Load config file for the FIPS library context. We assume that this
* config file will automatically activate the FIPS provider so we don't
* need to explicitly load it here.
*/
if (!OPENSSL_CTX_load_config(fipslibctx, "openssl-fips.cnf"))
goto err;

/*
* We don't need to do anything special to load the default provider into
* nonfipslibctx. This happens automatically if no other providers are
* loaded. Because we don't call OPENSSL_CTX_load_config() explicitly for
* nonfipslibctx it will just use the default config file.
*/

/* As an example get some digests */

/* Get a FIPS validated digest */
fipssha256 = EVP_MD_fetch(fipslibctx, "SHA2-256", NULL);
if (fipssha256 == NULL)
goto err;

/* Get a non-FIPS validated digest */
nonfipssha256 = EVP_MD_fetch(nonfipslibctx, "SHA2-256", NULL);
if (nonfipssha256 == NULL)
goto err;

/* Use the digests */

printf("Success\n");
ret = 0;
err:
EVP_MD_free(fipssha256);
EVP_MD_free(nonfipssha256);
OPENSSL_CTX_free(fipslibctx);
OPENSSL_CTX_free(nonfipslibctx);
OSSL_PROVIDER_unload(defctxnull);

return ret;

Note that we have made use of the special "null" provider here which we load into the default library context. We could have chosen to use the default library context for FIPS usage, and just create one additional library context for other usages - or vice versa. However if code has not been converted to use library contexts then the default library context will be automatically used. This could be the case for your own existing applications as well as certain parts of OpenSSL itself. Not all parts of OpenSSL are library context aware. If this happens then you could "accidentally" use the wrong library context for a particular operation. To be sure this doesn't happen you can load the "null" provider into the default library context. Because a provider has been explicitly loaded, the default provider will not automatically load. This means code using the default context by accident will fail because no algorithms will be available.

=== Using Serializers with the FIPS module ===

Serializers are used to read and write keys or parameters from or to some external format (for example a PEM file). In the OpenSSL 3.0 alpha 1 release only the "write" serializers have been implemented. Reading will come in a later alpha release. If your application generates keys or parameters that then need to be written into PEM or DER format then it is likely that you will need to use a serializer to do this. In most cases this will be invisible to you if you are using APIs that existed in OpenSSL 1.1.1 or earlier such as i2d_PrivateKey. However the appropriate serializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers are implemented in the default provider and are not in the FIPS module boundary. However since they are not cryptographic algorithms themselves it is still possible to use them in conjunction with the FIPS module, and therefore these serializers have the "fips=yes" property against them. You must ensure that the default provider is loaded into the library context in this case.

=== Using the FIPS module in SSL/TLS ===

Writing an application that uses libssl in conjunction with the FIPS module is much the same as writing a normal libssl application. If you are using global properties to specify usage of FIPS validated algorithms then this will happen automatically for all cryptographic algorithms in libssl. If you are using a non-default library context to load the FIPS provider then you can supply this to libssl using the function SSL_CTX_new_with_libctx(). This works as a drop in replacement for the function SSL_CTX_new() except it provides you with the capability to specify the library context to be used. You can also use this same function to specify libssl specific properties to use.

In this first example we create two SSL_CTX object using two different library contexts.

/*
* We assume that a non-default library context with the FIPS provider loaded has been
* created called fips_libctx.
/
SSL_CTX *fips_ssl_ctx = SSL_CTX_new_with_libctx(fips_libctx, NULL, TLS_method());
/*
* We assume that a non-default library context with the default provider loaded has been
* created called non_fips_libctx.
/
SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_with_libctx(non_fips_libctx, NULL, TLS_method());

In this second example we create two SSL_CTX objects using different properties to specify FIPS usage:

/*
* The "fips=yes" property includes all FIPS approved algorithms as well as serializers from the
* default provider that are allowed to be used. The NULL below indicates that we are using the
* default library context.
*/
SSL_CTX *fips_ssl_ctx = SSL_CTX_new_with_libctx(NULL, "fips=yes", TLS_method());
/*
* The "provider!=fips" property allows algorithms from any provider except the FIPS provider
*/
SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_with_libctx(NULL, "provider!=fips", TLS_method());

Note that in the OpenSSL alpha1 release OpenSSL does not automatically detect what signature algorithms are available within the currently loaded providers. If signature algorithms in the default set are not available, then an OpenSSL endpoint will offer them anyway. This could result in a handshake failure if the peer decides to use that signature algorithm. As a workaround until this is implemented applications can set the supported signature algorithms manually using a function such as SSL_CTX_set1_sigalgs_list() or similar. See the man page [[https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_sigalgs.html here]]

== Openssl command line application changes ==

The following additional command line arguments have been added

'''-provider_path''' path_name - Provider load path
'''-provider''' provider_name - Provider to load

These options can be used multiple times to load any providers, such as the 'legacy' provider or third party providers.
If used then the 'default' provider would also need to be specified if required.
The -provider_path must be specified before the -provider option.

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

==== Building and testing ====

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

==== Integration ====

(these issues are tracked in [[#Provider implementation support in other OpenSSL APIs|a table further down]])

* PKCS#7, CMS, SSL/TLS don't work with asymmetric keys implemented by a provider. There's a temporary hack in place that "downgrades" such keys to work with legacy methods (<tt>EVP_PKEY_METHOD</tt> and <tt>EVP_PKEY_ASN1_METHOD</tt>)
* CMP/CRMF, PKCS#7, TS, CMS, PKCS#12 and OSSL_STORE currently have no library context support
* OCSP, PEM, ASN.1 have some very limited library context support
* It is not yet possible to "fetch" a RAND algorithm

==== Programming ====

* EVP_set_default_properties() does not work (see [https://github.com/openssl/openssl/issues/11594 github #11594])

==== SSL/TLS ====

* libssl does not currently detect what signature algorithms are available within the currently loaded providers. Unless explicitly configured differently endpoints will advertise to peers the default list of signature algorithms that are supported - even if those are not available in the currently loaded providers. This could result in handshake failures. As a workaround until this is fixed you should explicitly configure signature algorithms that are consistent with the loaded providers.

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

The percentages in the tables below represent the amount of work done to convert legacy implementations to a provider based ones. Algorithms for which the conversion hasn't been completed (or ever started) remain full functional via the legacy code paths.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For the FIPS provider, only SHAKE-256 is available, not SHAKE-128.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| CMAC || default || 100% || ??
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC || default || 100% || ??
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || Vendor affirmed for FIPS, they cannot yet be validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA || default, FIPS || 80% || ??
|-
| RSAES-OAEP || default || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || In the FIPS provider, these are vendor affirmed.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || In the FIPS provider, these are vendor affirmed.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Library Context/Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| ASN1 || 5% || 5%
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OCSP || 20% || 20% || All changes needed to pass the libssl test suite have been done. We need to investigate if further changes are required
|-
| OSSL_STORE || 0% || 0%
|-
| PEM || 50% || 50% || Integrated with provider serializers for writing out keys and parameters
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| PKCS#12 || 0% || 0%
|-
| SSL / TLS || 80% || 100% || There are hacks in place that downgrade a key to legacy in some situations. Some processing happens in libssl that should be moved to a provider. Presence of signature algorithms is not correctly detected
|-
| TS || 0% || 0%
|-
| X509 || 80% || 80% || All changes needed to pass the libssl test suite have been done. We need to investigate if further changes are required
|}

OpenSSL 3.0

2020-05-05T03:37:56Z

Levitte: /* Installation and Compilation of OpenSSL 3.0 */

__NUMBEREDHEADINGS__ 

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

=== Engines and "METHOD" APIs ===

The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or modifies custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely bypass provider selection and configuration, with unintended consequences. This is particularly relevant for applications written to use the OpenSSL 3.0 FIPS module, as detailed below.
Authors and maintainers of external engines are strongly encouraged to refactor their code transforming engines into providers using the new Provider API and avoiding deprecated methods.

=== Versioning Scheme ===

The OpenSSL versioning scheme has changed with the 3.0 release. The new versioning scheme has this format:

MAJOR.MINOR.PATCH

For version 1.1.1 and below different patch levels were indicated by a letter at the end of the release version number. This will no longer be used and instead the patch level is indicated by the final number in the version. A change in the second (MINOR) number indicates that new features may have been added. OpenSSL versions with the same major number are API and ABI compatible. If the major number changes then API and ABI compatibility is not guaranteed.

=== Other major new features ===

* Implementation of the Certificate Management Protocol (CMP, RFC 4210) also covering CRMF (RFC 4211) and HTTP transfer (RFC 6712)
* A proper HTTP(S) client in libcrypto supporting GET and POST, redirection, plain and ASN.1-encoded contents, proxies, and timeouts
* EVP_KDF APIs have been introduced for working with Key Derivation Functions
* EVP_MAC APIs have been introduced for working with MACs
* Support for Linux Kernel TLS

=== Other notable deprecations and changes ===

* The function code part of an OpenSSL error code is no longer relevant and is always set to zero. Related functions are deprecated.

* The STACK and HASH macro's have been cleaned up, so that the type-safe wrappers are declared everywhere and implemented once. See the manpage at https://www.openssl.org/docs/manmaster/man3/DEFINE_STACK_OF.html for stack, and hopefully soon once the PR is merged, https://www.openssl.org/docs/manmaster/man3/DECLARE_LHASH_OF.html (but not yet as of this writing).

== Installation and Compilation of OpenSSL 3.0 ==

Please refer to the INSTALL.md file in the top of the distribution for instructions on how to build and install OpenSSL 3.0. Please also refer to the various platform specific NOTES files for your specific platform.

NOTE: The OpenSSL 3.0 alpha 1 release contains an error introduced during the release process which results in a failed compilation. There are two workarounds:

* apply [https://github.com/openssl/openssl/pull/11624/files the patch from github PR #11624].
* edit the VERSION file in the top of the distribution to remove the quotes around the date on the RELEASE_DATE line, i.e. make that line look like this:

RELEASE_DATE=23 Apr 2020

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0 can be found on the [[OpenSSL_1.1.0_Changes|OpenSSL 1.1.0 Changes]] page.

=== Upgrading from 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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\ossl-modules\fips.dll' on Windows.

To complete the installation you need to run the 'fipsinstall' command line application. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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 (e.g. in the application or via config), then this is the provider that will be used. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. If another provider has already been loaded then it won't be loaded automatically. Therefore if you want to use it in conjunction with other providers then you must load it explicitly. 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 may be 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. In order to guarantee that the default provider is not automatically loaded, the null provider can be loaded instead. This can be useful if you are using non-default library contexts and want to ensure that the default library context is never used "by accident".

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them.
This is a minimal config file example to load and activate both the legacy and the default provider in the default library context.

openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
legacy = legacy_sect

[default_sect]
activate = 1

[legacy_sect]
activate = 1

It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

/* Load Multiple providers into the default (NULL) library context */
legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;

/*
* Setting the library ctx to NULL here fetches the algorithm from the providers loaded
* into the default library context
*/
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

/* Explicit fetches return a dynamic object that must be freed */
EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

If no specific property query is required then NULL can be passed for the last argument. In any case any supplied property query is combined with the default property query. If nothing else is specified then the default property query is empty. However this can be changed so that every fetch automatically inherits these default properties. Default properties can either be set programmatically or via a config file. See the section [[OpenSSL 3.0#Loading the FIPS module at the same time as other providers|Loading the FIPS module at the same time as other providers]] for an example of how to do this.

Note that default properties are not currently functional in the OpenSSL 3.0 alpha 1 release.

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve. Note that the old functions FIPS_mode() and FIPS_mode_set() are present, but always fail in OpenSSL 3.0 so you should not use them.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

NOTE: Default properties are currently not functional in the OpenSSL 3.0 alpha 1 release - see the known issues below

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

In addition to using properties to separate usage of the FIPS module from other usages this can also be achieved using library contexts. In this example we create two library contexts. In one we assume the existence of a config file called "openssl-fips.cnf" that automatically loads and configures the FIPS provider. The other library context will just use the default provider.

OPENSSL_CTX *fipslibctx, *nonfipslibctx;
OSSL_PROVIDER *defctxnull = NULL;
EVP_MD *fipssha256 = NULL, *nonfipssha256 = NULL;
int ret = 1;

/*
* Create two non-default library contexts. One for fips usage and one for
* non-fips usage
*/
fipslibctx = OPENSSL_CTX_new();
nonfipslibctx = OPENSSL_CTX_new();
if (fipslibctx == NULL || nonfipslibctx == NULL)
goto err;

/* Prevent anything from using the default library context */
defctxnull = OSSL_PROVIDER_load(NULL, "null");

/*
* Load config file for the FIPS library context. We assume that this
* config file will automatically activate the FIPS provider so we don't
* need to explicitly load it here.
*/
if (!OPENSSL_CTX_load_config(fipslibctx, "openssl-fips.cnf"))
goto err;

/*
* We don't need to do anything special to load the default provider into
* nonfipslibctx. This happens automatically if no other providers are
* loaded. Because we don't call OPENSSL_CTX_load_config() explicitly for
* nonfipslibctx it will just use the default config file.
*/

/* As an example get some digests */

/* Get a FIPS validated digest */
fipssha256 = EVP_MD_fetch(fipslibctx, "SHA2-256", NULL);
if (fipssha256 == NULL)
goto err;

/* Get a non-FIPS validated digest */
nonfipssha256 = EVP_MD_fetch(nonfipslibctx, "SHA2-256", NULL);
if (nonfipssha256 == NULL)
goto err;

/* Use the digests */

printf("Success\n");
ret = 0;
err:
EVP_MD_free(fipssha256);
EVP_MD_free(nonfipssha256);
OPENSSL_CTX_free(fipslibctx);
OPENSSL_CTX_free(nonfipslibctx);
OSSL_PROVIDER_unload(defctxnull);

return ret;

Note that we have made use of the special "null" provider here which we load into the default library context. We could have chosen to use the default library context for FIPS usage, and just create one additional library context for other usages - or vice versa. However if code has not been converted to use library contexts then the default library context will be automatically used. This could be the case for your own existing applications as well as certain parts of OpenSSL itself. Not all parts of OpenSSL are library context aware. If this happens then you could "accidentally" use the wrong library context for a particular operation. To be sure this doesn't happen you can load the "null" provider into the default library context. Because a provider has been explicitly loaded, the default provider will not automatically load. This means code using the default context by accident will fail because no algorithms will be available.

=== Using Serializers with the FIPS module ===

Serializers are used to read and write keys or parameters from or to some external format (for example a PEM file). In the OpenSSL 3.0 alpha 1 release only the "write" serializers have been implemented. Reading will come in a later alpha release. If your application generates keys or parameters that then need to be written into PEM or DER format then it is likely that you will need to use a serializer to do this. In most cases this will be invisible to you if you are using APIs that existed in OpenSSL 1.1.1 or earlier such as i2d_PrivateKey. However the appropriate serializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers are implemented in the default provider and are not in the FIPS module boundary. However since they are not cryptographic algorithms themselves it is still possible to use them in conjunction with the FIPS module, and therefore these serializers have the "fips=yes" property against them. You must ensure that the default provider is loaded into the library context in this case.

=== Using the FIPS module in SSL/TLS ===

Writing an application that uses libssl in conjunction with the FIPS module is much the same as writing a normal libssl application. If you are using global properties to specify usage of FIPS validated algorithms then this will happen automatically for all cryptographic algorithms in libssl. If you are using a non-default library context to load the FIPS provider then you can supply this to libssl using the function SSL_CTX_new_with_libctx(). This works as a drop in replacement for the function SSL_CTX_new() except it provides you with the capability to specify the library context to be used. You can also use this same function to specify libssl specific properties to use.

In this first example we create two SSL_CTX object using two different library contexts.

/*
* We assume that a non-default library context with the FIPS provider loaded has been
* created called fips_libctx.
/
SSL_CTX *fips_ssl_ctx = SSL_CTX_new_with_libctx(fips_libctx, NULL, TLS_method());
/*
* We assume that a non-default library context with the default provider loaded has been
* created called non_fips_libctx.
/
SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_with_libctx(non_fips_libctx, NULL, TLS_method());

In this second example we create two SSL_CTX objects using different properties to specify FIPS usage:

/*
* The "fips=yes" property includes all FIPS approved algorithms as well as serializers from the
* default provider that are allowed to be used. The NULL below indicates that we are using the
* default library context.
*/
SSL_CTX *fips_ssl_ctx = SSL_CTX_new_with_libctx(NULL, "fips=yes", TLS_method());
/*
* The "provider!=fips" property allows algorithms from any provider except the FIPS provider
*/
SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_with_libctx(NULL, "provider!=fips", TLS_method());

Note that in the OpenSSL alpha1 release OpenSSL does not automatically detect what signature algorithms are available within the currently loaded providers. If signature algorithms in the default set are not available, then an OpenSSL endpoint will offer them anyway. This could result in a handshake failure if the peer decides to use that signature algorithm. As a workaround until this is implemented applications can set the supported signature algorithms manually using a function such as SSL_CTX_set1_sigalgs_list() or similar. See the man page [[https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_sigalgs.html here]]

== Openssl command line application changes ==

The following additional command line arguments have been added

'''-provider_path''' path_name - Provider load path
'''-provider''' provider_name - Provider to load

These options can be used multiple times to load any providers, such as the 'legacy' provider or third party providers.
If used then the 'default' provider would also need to be specified if required.
The -provider_path must be specified before the -provider option.

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

==== Building and testing ====

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

==== Integration ====

(these issues are tracked in [[#Provider implementation support in other OpenSSL APIs|a table further down]])

* PKCS#7, CMS, SSL/TLS don't work with asymmetric keys implemented by a provider. There's a temporary hack in place that "downgrades" such keys to work with legacy methods (<tt>EVP_PKEY_METHOD</tt> and <tt>EVP_PKEY_ASN1_METHOD</tt>)
* CMP/CRMF, PKCS#7, TS, CMS, PKCS#12 and OSSL_STORE currently have no library context support
* OCSP, PEM, ASN.1 have some very limited library context support
* It is not yet possible to "fetch" a RAND algorithm

==== Programming ====

* EVP_set_default_properties() does not work (see [https://github.com/openssl/openssl/issues/11594 github #11594])

==== SSL/TLS ====

* libssl does not currently detect what signature algorithms are available within the currently loaded providers. Unless explicitly configured differently endpoints will advertise to peers the default list of signature algorithms that are supported - even if those are not available in the currently loaded providers. This could result in handshake failures. As a workaround until this is fixed you should explicitly configure signature algorithms that are consistent with the loaded providers.

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

The percentages in the tables below represent the amount of work done to convert legacy implementations to a provider based ones. Algorithms for which the conversion hasn't been completed (or ever started) remain full functional via the legacy code paths.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For the FIPS provider, only SHAKE-256 is available, not SHAKE-128.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| CMAC || default || 100% || ??
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC || default || 100% || ??
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || Vendor affirmed for FIPS, they cannot yet be validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA || default, FIPS || 80% || ??
|-
| RSAES-OAEP || default || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || In the FIPS provider, these are vendor affirmed.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || In the FIPS provider, these are vendor affirmed.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Library Context/Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| ASN1 || 5% || 5%
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OCSP || 20% || 20% || All changes needed to pass the libssl test suite have been done. We need to investigate if further changes are required
|-
| OSSL_STORE || 0% || 0%
|-
| PEM || 50% || 50% || Integrated with provider serializers for writing out keys and parameters
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| PKCS#12 || 0% || 0%
|-
| SSL / TLS || 80% || 100% || There are hacks in place that downgrade a key to legacy in some situations. Some processing happens in libssl that should be moved to a provider. Presence of signature algorithms is not correctly detected
|-
| TS || 0% || 0%
|-
| X509 || 80% || 80% || All changes needed to pass the libssl test suite have been done. We need to investigate if further changes are required
|}

OpenSSL 3.0

2020-05-05T03:33:51Z

Levitte: /* Installation and Compilation of OpenSSL 3.0 */

__NUMBEREDHEADINGS__ 

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

=== Engines and "METHOD" APIs ===

The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or modifies custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely bypass provider selection and configuration, with unintended consequences. This is particularly relevant for applications written to use the OpenSSL 3.0 FIPS module, as detailed below.
Authors and maintainers of external engines are strongly encouraged to refactor their code transforming engines into providers using the new Provider API and avoiding deprecated methods.

=== Versioning Scheme ===

The OpenSSL versioning scheme has changed with the 3.0 release. The new versioning scheme has this format:

MAJOR.MINOR.PATCH

For version 1.1.1 and below different patch levels were indicated by a letter at the end of the release version number. This will no longer be used and instead the patch level is indicated by the final number in the version. A change in the second (MINOR) number indicates that new features may have been added. OpenSSL versions with the same major number are API and ABI compatible. If the major number changes then API and ABI compatibility is not guaranteed.

=== Other major new features ===

* Implementation of the Certificate Management Protocol (CMP, RFC 4210) also covering CRMF (RFC 4211) and HTTP transfer (RFC 6712)
* A proper HTTP(S) client in libcrypto supporting GET and POST, redirection, plain and ASN.1-encoded contents, proxies, and timeouts
* EVP_KDF APIs have been introduced for working with Key Derivation Functions
* EVP_MAC APIs have been introduced for working with MACs
* Support for Linux Kernel TLS

=== Other notable deprecations and changes ===

* The function code part of an OpenSSL error code is no longer relevant and is always set to zero. Related functions are deprecated.

* The STACK and HASH macro's have been cleaned up, so that the type-safe wrappers are declared everywhere and implemented once. See the manpage at https://www.openssl.org/docs/manmaster/man3/DEFINE_STACK_OF.html for stack, and hopefully soon once the PR is merged, https://www.openssl.org/docs/manmaster/man3/DECLARE_LHASH_OF.html (but not yet as of this writing).

== Installation and Compilation of OpenSSL 3.0 ==

Please refer to the INSTALL.md file in the top of the distribution for instructions on how to build and install OpenSSL 3.0. Please also refer to the various platform specific NOTES files for your specific platform.

NOTE: The OpenSSL 3.0 alpha 1 release contains an error introduced during the release process which results in a failed compilation. There are two workarounds:

# apply [https://github.com/openssl/openssl/pull/11624/files the patch from github PR #11624].
# edit the VERSION file in the top of the distribution to remove the quotes around the date on the RELEASE_DATE line, i.e. make that line look like this:
#:
#: RELEASE_DATE=23 Apr 2020

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0 can be found on the [[OpenSSL_1.1.0_Changes|OpenSSL 1.1.0 Changes]] page.

=== Upgrading from 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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\ossl-modules\fips.dll' on Windows.

To complete the installation you need to run the 'fipsinstall' command line application. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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 (e.g. in the application or via config), then this is the provider that will be used. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. If another provider has already been loaded then it won't be loaded automatically. Therefore if you want to use it in conjunction with other providers then you must load it explicitly. 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 may be 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. In order to guarantee that the default provider is not automatically loaded, the null provider can be loaded instead. This can be useful if you are using non-default library contexts and want to ensure that the default library context is never used "by accident".

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them.
This is a minimal config file example to load and activate both the legacy and the default provider in the default library context.

openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
legacy = legacy_sect

[default_sect]
activate = 1

[legacy_sect]
activate = 1

It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

/* Load Multiple providers into the default (NULL) library context */
legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;

/*
* Setting the library ctx to NULL here fetches the algorithm from the providers loaded
* into the default library context
*/
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

/* Explicit fetches return a dynamic object that must be freed */
EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

If no specific property query is required then NULL can be passed for the last argument. In any case any supplied property query is combined with the default property query. If nothing else is specified then the default property query is empty. However this can be changed so that every fetch automatically inherits these default properties. Default properties can either be set programmatically or via a config file. See the section [[OpenSSL 3.0#Loading the FIPS module at the same time as other providers|Loading the FIPS module at the same time as other providers]] for an example of how to do this.

Note that default properties are not currently functional in the OpenSSL 3.0 alpha 1 release.

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve. Note that the old functions FIPS_mode() and FIPS_mode_set() are present, but always fail in OpenSSL 3.0 so you should not use them.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

NOTE: Default properties are currently not functional in the OpenSSL 3.0 alpha 1 release - see the known issues below

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

In addition to using properties to separate usage of the FIPS module from other usages this can also be achieved using library contexts. In this example we create two library contexts. In one we assume the existence of a config file called "openssl-fips.cnf" that automatically loads and configures the FIPS provider. The other library context will just use the default provider.

OPENSSL_CTX *fipslibctx, *nonfipslibctx;
OSSL_PROVIDER *defctxnull = NULL;
EVP_MD *fipssha256 = NULL, *nonfipssha256 = NULL;
int ret = 1;

/*
* Create two non-default library contexts. One for fips usage and one for
* non-fips usage
*/
fipslibctx = OPENSSL_CTX_new();
nonfipslibctx = OPENSSL_CTX_new();
if (fipslibctx == NULL || nonfipslibctx == NULL)
goto err;

/* Prevent anything from using the default library context */
defctxnull = OSSL_PROVIDER_load(NULL, "null");

/*
* Load config file for the FIPS library context. We assume that this
* config file will automatically activate the FIPS provider so we don't
* need to explicitly load it here.
*/
if (!OPENSSL_CTX_load_config(fipslibctx, "openssl-fips.cnf"))
goto err;

/*
* We don't need to do anything special to load the default provider into
* nonfipslibctx. This happens automatically if no other providers are
* loaded. Because we don't call OPENSSL_CTX_load_config() explicitly for
* nonfipslibctx it will just use the default config file.
*/

/* As an example get some digests */

/* Get a FIPS validated digest */
fipssha256 = EVP_MD_fetch(fipslibctx, "SHA2-256", NULL);
if (fipssha256 == NULL)
goto err;

/* Get a non-FIPS validated digest */
nonfipssha256 = EVP_MD_fetch(nonfipslibctx, "SHA2-256", NULL);
if (nonfipssha256 == NULL)
goto err;

/* Use the digests */

printf("Success\n");
ret = 0;
err:
EVP_MD_free(fipssha256);
EVP_MD_free(nonfipssha256);
OPENSSL_CTX_free(fipslibctx);
OPENSSL_CTX_free(nonfipslibctx);
OSSL_PROVIDER_unload(defctxnull);

return ret;

Note that we have made use of the special "null" provider here which we load into the default library context. We could have chosen to use the default library context for FIPS usage, and just create one additional library context for other usages - or vice versa. However if code has not been converted to use library contexts then the default library context will be automatically used. This could be the case for your own existing applications as well as certain parts of OpenSSL itself. Not all parts of OpenSSL are library context aware. If this happens then you could "accidentally" use the wrong library context for a particular operation. To be sure this doesn't happen you can load the "null" provider into the default library context. Because a provider has been explicitly loaded, the default provider will not automatically load. This means code using the default context by accident will fail because no algorithms will be available.

=== Using Serializers with the FIPS module ===

Serializers are used to read and write keys or parameters from or to some external format (for example a PEM file). In the OpenSSL 3.0 alpha 1 release only the "write" serializers have been implemented. Reading will come in a later alpha release. If your application generates keys or parameters that then need to be written into PEM or DER format then it is likely that you will need to use a serializer to do this. In most cases this will be invisible to you if you are using APIs that existed in OpenSSL 1.1.1 or earlier such as i2d_PrivateKey. However the appropriate serializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers are implemented in the default provider and are not in the FIPS module boundary. However since they are not cryptographic algorithms themselves it is still possible to use them in conjunction with the FIPS module, and therefore these serializers have the "fips=yes" property against them. You must ensure that the default provider is loaded into the library context in this case.

=== Using the FIPS module in SSL/TLS ===

Writing an application that uses libssl in conjunction with the FIPS module is much the same as writing a normal libssl application. If you are using global properties to specify usage of FIPS validated algorithms then this will happen automatically for all cryptographic algorithms in libssl. If you are using a non-default library context to load the FIPS provider then you can supply this to libssl using the function SSL_CTX_new_with_libctx(). This works as a drop in replacement for the function SSL_CTX_new() except it provides you with the capability to specify the library context to be used. You can also use this same function to specify libssl specific properties to use.

In this first example we create two SSL_CTX object using two different library contexts.

/*
* We assume that a non-default library context with the FIPS provider loaded has been
* created called fips_libctx.
/
SSL_CTX *fips_ssl_ctx = SSL_CTX_new_with_libctx(fips_libctx, NULL, TLS_method());
/*
* We assume that a non-default library context with the default provider loaded has been
* created called non_fips_libctx.
/
SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_with_libctx(non_fips_libctx, NULL, TLS_method());

In this second example we create two SSL_CTX objects using different properties to specify FIPS usage:

/*
* The "fips=yes" property includes all FIPS approved algorithms as well as serializers from the
* default provider that are allowed to be used. The NULL below indicates that we are using the
* default library context.
*/
SSL_CTX *fips_ssl_ctx = SSL_CTX_new_with_libctx(NULL, "fips=yes", TLS_method());
/*
* The "provider!=fips" property allows algorithms from any provider except the FIPS provider
*/
SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_with_libctx(NULL, "provider!=fips", TLS_method());

Note that in the OpenSSL alpha1 release OpenSSL does not automatically detect what signature algorithms are available within the currently loaded providers. If signature algorithms in the default set are not available, then an OpenSSL endpoint will offer them anyway. This could result in a handshake failure if the peer decides to use that signature algorithm. As a workaround until this is implemented applications can set the supported signature algorithms manually using a function such as SSL_CTX_set1_sigalgs_list() or similar. See the man page [[https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_sigalgs.html here]]

== Openssl command line application changes ==

The following additional command line arguments have been added

'''-provider_path''' path_name - Provider load path
'''-provider''' provider_name - Provider to load

These options can be used multiple times to load any providers, such as the 'legacy' provider or third party providers.
If used then the 'default' provider would also need to be specified if required.
The -provider_path must be specified before the -provider option.

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

==== Building and testing ====

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

==== Integration ====

(these issues are tracked in [[#Provider implementation support in other OpenSSL APIs|a table further down]])

* PKCS#7, CMS, SSL/TLS don't work with asymmetric keys implemented by a provider. There's a temporary hack in place that "downgrades" such keys to work with legacy methods (<tt>EVP_PKEY_METHOD</tt> and <tt>EVP_PKEY_ASN1_METHOD</tt>)
* CMP/CRMF, PKCS#7, TS, CMS, PKCS#12 and OSSL_STORE currently have no library context support
* OCSP, PEM, ASN.1 have some very limited library context support
* It is not yet possible to "fetch" a RAND algorithm

==== Programming ====

* EVP_set_default_properties() does not work (see [https://github.com/openssl/openssl/issues/11594 github #11594])

==== SSL/TLS ====

* libssl does not currently detect what signature algorithms are available within the currently loaded providers. Unless explicitly configured differently endpoints will advertise to peers the default list of signature algorithms that are supported - even if those are not available in the currently loaded providers. This could result in handshake failures. As a workaround until this is fixed you should explicitly configure signature algorithms that are consistent with the loaded providers.

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

The percentages in the tables below represent the amount of work done to convert legacy implementations to a provider based ones. Algorithms for which the conversion hasn't been completed (or ever started) remain full functional via the legacy code paths.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For the FIPS provider, only SHAKE-256 is available, not SHAKE-128.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| CMAC || default || 100% || ??
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC || default || 100% || ??
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || Vendor affirmed for FIPS, they cannot yet be validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA || default, FIPS || 80% || ??
|-
| RSAES-OAEP || default || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || In the FIPS provider, these are vendor affirmed.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || In the FIPS provider, these are vendor affirmed.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Library Context/Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| ASN1 || 5% || 5%
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OCSP || 20% || 20% || All changes needed to pass the libssl test suite have been done. We need to investigate if further changes are required
|-
| OSSL_STORE || 0% || 0%
|-
| PEM || 50% || 50% || Integrated with provider serializers for writing out keys and parameters
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| PKCS#12 || 0% || 0%
|-
| SSL / TLS || 80% || 100% || There are hacks in place that downgrade a key to legacy in some situations. Some processing happens in libssl that should be moved to a provider. Presence of signature algorithms is not correctly detected
|-
| TS || 0% || 0%
|-
| X509 || 80% || 80% || All changes needed to pass the libssl test suite have been done. We need to investigate if further changes are required
|}

OpenSSL 3.0

2020-04-22T08:48:11Z

Levitte: /* Known issues */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

=== Engines and "METHOD" APIs ===

The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or modifies custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely bypass provider selection and configuration, with unintended consequences. This is particularly relevant for applications written to use the OpenSSL 3.0 FIPS module, as detailed below.
Authors and maintainers of external engines are strongly encouraged to refactor their code transforming engines into providers using the new Provider API and avoiding deprecated methods.

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

==== Building and testing ====

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

==== Integration ====

(these issues are tracked in [[#Provider implementation support in other OpenSSL APIs|a table further down]])

* PKCS#7, CMS, SSL/TLS don't work with asymmetric keys implemented by a provider. There's a temporary hack in place that "downgrades" such keys to work with legacy methods (<tt>EVP_PKEY_METHOD</tt> and <tt>EVP_PKEY_ASN1_METHOD</tt>)
* OSSL_STORE currently has no provider support

==== Programming ====

* EVP_Digest{Sign,Verify}Init() does not handle no default digest (see [https://github.com/openssl/openssl/pull/11571 github #11571] and [https://github.com/openssl/openssl/pull/11576 github #11576])

* EVP_set_default_properties() does not work (see [https://github.com/openssl/openssl/issues/11594 github #11594])

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default || 100% || ??
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default || 100% || ??
|-
| KMAC-256 || default || 100% || ??
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 90% || 100% || There are hacks in place that downgrade a key to legacy in some situations
|}

OpenSSL 3.0

2020-04-22T08:41:57Z

Levitte: /* Programming */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

=== Engines and "METHOD" APIs ===

The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or modifies custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely bypass provider selection and configuration, with unintended consequences. This is particularly relevant for applications written to use the OpenSSL 3.0 FIPS module, as detailed below.
Authors and maintainers of external engines are strongly encouraged to refactor their code transforming engines into providers using the new Provider API and avoiding deprecated methods.

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

==== Building and testing ====

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

==== Programming ====

* EVP_Digest{Sign,Verify}Init() does not handle no default digest (see [https://github.com/openssl/openssl/pull/11571 github #11571] and [https://github.com/openssl/openssl/pull/11576 github #11576])

* EVP_set_default_properties() does not work (see [https://github.com/openssl/openssl/issues/11594 github #11594])

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default || 100% || ??
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default || 100% || ??
|-
| KMAC-256 || default || 100% || ??
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 90% || 100% || There are hacks in place that downgrade a key to legacy in some situations
|}

OpenSSL 3.0

2020-04-22T08:41:29Z

Levitte: /* Programming */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

=== Engines and "METHOD" APIs ===

The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or modifies custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely bypass provider selection and configuration, with unintended consequences. This is particularly relevant for applications written to use the OpenSSL 3.0 FIPS module, as detailed below.
Authors and maintainers of external engines are strongly encouraged to refactor their code transforming engines into providers using the new Provider API and avoiding deprecated methods.

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

==== Building and testing ====

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

==== Programming ====

* EVP_Digest{Sign,Verify}Init() does not handle no default digest (see [https://github.com/openssl/openssl/pull/11571 github #11571] and [https://github.com/openssl/openssl/pull/11576 github #11576])

* EVP_set_default_properties() does not work (see [https://github.com/openssl/openssl/issues/11594])

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default || 100% || ??
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default || 100% || ??
|-
| KMAC-256 || default || 100% || ??
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 90% || 100% || There are hacks in place that downgrade a key to legacy in some situations
|}

OpenSSL 3.0

2020-04-22T08:32:32Z

Levitte: Give us heading numbering!

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

=== Engines and "METHOD" APIs ===

The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or modifies custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely bypass provider selection and configuration, with unintended consequences. This is particularly relevant for applications written to use the OpenSSL 3.0 FIPS module, as detailed below.
Authors and maintainers of external engines are strongly encouraged to refactor their code transforming engines into providers using the new Provider API and avoiding deprecated methods.

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

==== Building and testing ====

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

==== Programming ====

* EVP: EVP_Digest{Sign,Verify}Init() does not handle no default digest (see [https://github.com/openssl/openssl/pull/11571 github #11571] and [https://github.com/openssl/openssl/pull/11576 github #11576])

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default || 100% || ??
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default || 100% || ??
|-
| KMAC-256 || default || 100% || ??
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 90% || 100% || There are hacks in place that downgrade a key to legacy in some situations
|}

OpenSSL 3.0

2020-04-22T07:47:51Z

Levitte: /* Known issues */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

=== Engines and "METHOD" APIs ===

The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or modifies custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely bypass provider selection and configuration, with unintended consequences. This is particularly relevant for applications written to use the OpenSSL 3.0 FIPS module, as detailed below.
Authors and maintainers of external engines are strongly encouraged to refactor their code transforming engines into providers using the new Provider API and avoiding deprecated methods.

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, RSA_meth_new, EC_KEY_METHOD_new, etc.)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

==== Building and testing ====

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

==== Programming ====

* EVP: EVP_Digest{Sign,Verify}Init() does not handle no default digest (see [https://github.com/openssl/openssl/pull/11571 github #11571] and [https://github.com/openssl/openssl/pull/11576 github #11576])

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T07:40:10Z

Levitte: /* Platforms */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Yes
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T07:39:35Z

Levitte: /* Known issues */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

* Doesn't build and test on all platforms on our watch list. See the list of [[#Platforms|platforms]] below 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T07:38:45Z

Levitte: /* Known issues */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

* Doesn't build and test on all platforms on our watch list. See [[#Platforms]] 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T07:37:41Z

Levitte: /* Known issues */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

* Doesn't build and test on all platforms on our watch list. See [[Platforms]] 
: ''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T07:37:02Z

Levitte: /* Known issues */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

* Doesn't build and test on all platforms on our watch list. See [[Platforms]] 
''To be noted that we can't pretend to build on everything and anything, but there are a number of platforms that we watch, either on our own or with community help and reporting''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T07:10:42Z

Levitte: /* Serializers */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

TO BE ADDED

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Deserializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T07:10:20Z

Levitte: /* Serializers */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

TO BE ADDED

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| SM2 to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T07:09:19Z

Levitte: /* Serializers */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

TO BE ADDED

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH to printable text, DER, PEM || default || 100% || ??
|-
| DSA to printable text, DER, PEM || default || 100% || ??
|-
| ED25519 to printable text, DER, PEM || default || 100% || ??
|-
| ED448 to printable text, DER, PEM || default || 100% || ??
|-
| EC to printable text, DER, PEM || default || 100% || ??
|-
| RSA to printable text, DER, PEM || default || 100% || ??
|-
| RSA-PSS to printable text, DER, PEM || default || 0% || ??
|-
| RSA-OAEP to printable text, DER, PEM || default || 0% ? || ??
|-
| X25519 to printable text, DER, PEM || default || 100% || ??
|-
| X448 to printable text, DER, PEM || default || 100% || ??
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T06:58:18Z

Levitte: /* Provider implemented OSSL_STORE URI schemes */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

TO BE ADDED

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2BMAC || default || 100% || ??
|-
| BLAKE2SMAC || default || 100% || ??
|-
| CMAC || default, FIPS || 100% || ??
|-
| GMAC || default, FIPS || 100% || ??
|-
| HMAC || default, FIPS || 100% || ??
|-
| KMAC-128 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KMAC-256 || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| POLY1305 || default || 100% || ??
|-
| SIPHASH || default || 100% || ??
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ?? || Not scheduled for FIPS validation
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default, FIPS || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on deserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T06:51:36Z

Levitte: /* Provider implemented OSSL_STORE URI schemes */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

TO BE ADDED

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default, FIPS || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? || This is pending on dedserializers
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T06:51:05Z

Levitte: /* Provider implemented OSSL_STORE URI schemes */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

TO BE ADDED

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| HKDF || default, FIPS || 100% || ??
|-
| KBKDF || default, FIPS || 100% || ??
|-
| KRB5KDF || default || 100% || ?? || Kerberos KDF
|-
| PBKDF2 || default, FIPS || 100% || ??
|-
| SCRYPT || default || 100% || ??
|-
| SSKDF || default, FIPS || 100% || ??
|-
| TLS1-PRF || default, FIPS || 100% || ?? || TLS 1.x PRF is treated as a KDF by OpenSSL
|-
| X942KDF || default || 100% || ??
|-
| X963KDF || default, FIPS || 100% || ??
|-
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| file: || default (?) || 0% || ?? ||
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-22T06:49:26Z

Levitte: /* STATUS of current development */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conform to FIPS standards you can specify the property query "fips=yes" like this:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

If no property query is specified, or more than one implementation matches the property query then it is undefined which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

EVP_MD *sha256;

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

EVP_set_default_properties(NULL, "fips=yes");

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. It is also possible for a locally specified property query to override the default properties.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS approved algorithms match against the property query "fips=yes". The FIPS module also has some non-approved algorithms contained within it (currently X25519, X448, Ed25519 and Ed448). These algorithms do not have the "fips=yes" property defined for them. There are also some non-cryptographic algorithms available in the default provider that also have the "fips=yes" property defined for them. These are the serializer algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The serializer algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and fips providers and sets the default property value to be "fips=yes":

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

=== Using the FIPS module in SSL/TLS ===

STUFF HERE

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Known issues ===

TO BE ADDED

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128. SHAKE-256 will not be undergoing FIPS validation.
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ?? || These cannot yet be FIPS validated.
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ?? || These cannot yet be FIPS validated.
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T12:15:17Z

Levitte: /* Platforms */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comment
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T12:14:54Z

Levitte: /* Platforms */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests !! Comments
|-
| Linux - x86 / x86_64 || Yes || Yes
|-
| Linux - s390x || Yes || Yes
|-
| Windows + Visual C - x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS - Alpha / Itanium || No || Unknown || New include directories need to be dealt with, and more elegantly than the 1.1.1 kludge
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:48:26Z

Levitte: /* Provider implemented asymmetric key types */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|-
| SM2 || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:46:14Z

Levitte: /* Provider implemented key exchange */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 70%  || ?? || We lack support for X9.42 DH, which is needed by CMS
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:45:16Z

Levitte: /* Provider implementation support in other OpenSSL APIs */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 100% || ??
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ?? || We need to investigate if we need to change anything
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:44:34Z

Levitte: /* Provider implementation support in other OpenSSL APIs */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 100% || ??
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with CMS
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0% || There are hacks in place that downgrade a key to legacy when used with PKCS#7
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:43:23Z

Levitte: /* Provider implementation support in other OpenSSL APIs */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 100% || ??
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| PKCS#7 || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:41:24Z

Levitte: /* Provider implemented digests */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 100% || ??
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:40:43Z

Levitte: /* Features */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| BLAKE2 || default || 100% || ??
|-
| SM3 || default || 100% || ??
|-
| MD2 || legacy || 100% || ??
|-
| MD4 || legacy || 100% || ??
|-
| MD5, MD5-SHA1 || default || 100% || ?? || MD5-SHA1 is a TLS special, not otherwise useful
|-
| MDC2 || legacy || 100% || ??
|-
| SHA1 || default, FIPS || 100% || ??
|-
| SHA2 || default, FIPS || 100% || ??
|-
| SHA3 || default, FIPS || 100% || ??
|-
| SHAKE || default, FIPS || 100% || ?? || For FIPS, only SHAKE-256, not SHAKE-128
|-
| RIPEMD-160 || leagcy || 100% || ??
|-
| WHIRLPOOL || legacy || 100% || ??
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 100% || ??
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:23:31Z

Levitte: /* Provider implemented serializers / deserializers */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 100% || ??
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T06:23:17Z

Levitte: /* Serializers */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 100% || ??
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

TO BE ADDED

===== Serializers =====

TO BE ADDED

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T04:51:07Z

Levitte: /* Features */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented MACs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented KDFs ====

TO BE ADDED

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| RSA, RSAES-OAEP || default, FIPS || 80% || ??
|}

==== Provider implemented signature ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DSA || default, FIPS || 100% || ??
|-
| ECDSA || default, FIPS || 100% || ??
|-
| ED25519, ED448 || default, FIPS || 100% || ??
|-
| RSA, RSASSA-PSS || default || 80% || ?? || RSASSA-PSS support untested
|}

==== Provider implemented key exchange ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 100% || ??
|-
| ECDH || default, FIPS || 100% || ??
|-
| X25519, X448 || default, FIPS || 100% || ??
|}

==== Provider implemented serializers / deserializers ====

TO BE ADDED

===== Serializers =====

{| class="wikitable"
! Serializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

===== Serializers =====

{| class="wikitable"
! Deserializer !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

{| class="wikitable"
! URI scheme !! Providers !! Code completion % !! Documentation completion % !! Comment
|}

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T04:33:49Z

Levitte: /* Features */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented digests ====

{| class="wikitable"
! Algorithm !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

TO BE ADDED

==== Provider implemented MACs ====

TO BE ADDED

==== Provider implemented KDFs ====

TO BE ADDED

==== Provider implemented asymmetric key types ====

{| class="wikitable"
! Key type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| DH || default, FIPS || 95%  || ??
|-
| DSA || default, FIPS || 100%  || ??
|-
| EC || default, FIPS || 100%  || ??
|-
| ED25519, X25519, ED448, X448 || default, FIPS || 100%  || ??
|-
| RSA || default, FIPS || 100%  || ?? || RSA-PSS or RSA-OAEP are considered separate key types, although the RSA EVP_ASYM_CIPHER and EVP_SIGNATURE implementations carry some of the corresponding properties.
|-
| RSA-PSS || default || 0% || ?? || Scheduled for alpha 2
|-
| RSA-OAEP || default || 0% || ??
|}

==== Provider implemented asymmetric ciphers ====

TO BE ADDED

==== Provider implemented signature ====

TO BE ADDED

==== Provider implemented key exchange ====

TO BE ADDED

==== Provider implemented serializers / deserializers ====

TO BE ADDED

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-21T04:18:22Z

Levitte: /* Provider implemented digests */

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented digests ====

{| class="wikitable"
! Operation type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ?? || For FIPS, only DES-EDE3-ECB and DES-EDE3-CBC
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

TO BE ADDED

==== Provider implemented MACs ====

TO BE ADDED

==== Provider implemented KDFs ====

TO BE ADDED

==== Provider implemented asymmetric key types ====

TO BE ADDED

==== Provider implemented asymmetric ciphers ====

TO BE ADDED

==== Provider implemented signature ====

TO BE ADDED

==== Provider implemented key exchange ====

TO BE ADDED

==== Provider implemented serializers / deserializers ====

TO BE ADDED

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

OpenSSL 3.0

2020-04-20T21:00:32Z

Levitte: Start on a STATUS section

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

=== 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.

=== Legacy Algorithms ===

Some cryptographic algorithms that were available via the EVP APIs are now considered legacy and their use is strongly discouraged. These legacy EVP algorithms are still available in OpenSSL 3.0 but not by default. If you want to use them then you must load the legacy provider. This can be as simple as a config file change, or can be done programmatically (see below).

== 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. In addition to the issues discussed above in the section about upgrading from 1.1.1, 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.

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' are present in OpenSSL 3.0 but always fail. You should rewrite your application to not use them. See the sections below on how to write applications to use the FIPS Module in OpenSSL 3.0.

== 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. This does 2 things:

* Runs the FIPS module self tests
* Generates FIPS module config file output containing information about the module such as the self test status, and the module checksum

The FIPS module ''must'' have the self tests run, and the FIPS module config file output generated on ''every'' machine that it is to be used on. You '''must not''' copy the FIPS module config file output data from one machine to another.

For example, to install the module:

$ 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

== Programming in OpenSSL 3.0 ==

Applications written to work with OpenSSL 1.1.1 will mostly just work with OpenSSL 3.0. However changes will be required if you want to take advantage of some of the new features that OpenSSL 3.0 makes available. In order to do that you need to understand some new concepts introduced in OpenSSL 3.0.

=== Library Contexts ===

A library context can be thought of as a "scope" for OpenSSL operations. All functionality operates with the scope of a library context. Multiple library contexts may exist at the same time, and they each may be configured differently. A library context is represented by the newly introduced OPENSSL_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OPENSSL_CTX.html here].

Many new functions have been introduced into OpenSSL that take an OPENSSL_CTX parameter. In many cases these are variants of some other function that existed in 1.1.1 and work in much the same way - except that they now operate within the scope of the given library context.

All applications have available to them the "default library context". This library context always exists and, if you don't otherwise specify one, this is the library context that will be used. Any function that takes an OPENSSL_CTX value as a parameter will accept the value NULL for that parameter in order to refer to the default library context. You can also explicitly create new ones via the OPENSSL_CTX_new() function. See the man page for further details.

Config files affect a given library context. It is quite possible to have multiple library contexts in use, with each one having been configured with a different config file (see the OPENSSL_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the EVP APIs a provider is selected. It is that provider implementation that actually does the required work. There are four providers distributed with OpenSSL. In the future we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the man page [https://www.openssl.org/docs/manmaster/man7/provider.html here].

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. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. 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.

Providers to be loaded can be specified in the OpenSSL config file. See the man page [https://www.openssl.org/docs/manmaster/man5/config.html here]for information about how to configure providers via the config file, and how to automatically activate them. It is also possible to load them programmatically. For example you can load the legacy provider into the default library context as shown below. Note that once you have explicitly loaded a provider into the library context the default provider will no longer be automatically loaded. Therefore you will often also want to explicitly load the default provider, as is done here:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *legacy;
OSSL_PROVIDER *deflt;

legacy = OSSL_PROVIDER_load(NULL, "legacy");
if (legacy == NULL) {
printf("Failed to load Legacy provider\n");
exit(EXIT_FAILURE);
}
deflt = OSSL_PROVIDER_load(NULL, "default");
if (deflt == NULL) {
printf("Failed to load Default provider\n");
OSSL_PROVIDER_unload(legacy);
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(legacy);
OSSL_PROVIDER_unload(deflt);
exit(EXIT_SUCCESS);
}

=== Fetching algorithms and property queries ===

In order to use a cryptographic algorithm (such as AES) then an implementation for it must first be "fetched" from the available providers that have been loaded into the library context being used. This can be done either implicitly or explicitly.

With implicit fetching the application does not need to do anything special. Algorithms implementations will be fetched automatically by the relevant APIs. For example:

EVP_MD_CTX *mdctx;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL) != 1)
goto err;

In this code we are initialising a digest operation to use the SHA256 algorithm. The EVP_DigestInit_ex() function will automatically fetch an implementation of the SHA256 algorithm from the available providers when it needs to. It will do so using the default library context and the default property query string (see below).

With explicit fetching an application fetches the implementation to be used up front, and then passes that to the relevant EVP API. For example:

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

mdctx = EVP_MD_CTX_new();
if (mdctx == NULL)
goto err;
sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
if (sha256 == NULL)
goto err;
if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1)
goto err;

EVP_MD_free(sha256);

In this example we have explicitly fetched an implementation of SHA256 from the set of available providers loaded into the default library context.

With an explicit fetch we can additionally supply a property query to further specify which implementation we wish to obtain. For example:

sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");

Here we are explicitly fetching a FIPS validated implementation of the SHA256 algorithm. Such an implementation exists in the FIPS provider, so we would need to have ensured that the FIPS provider was loaded into the default library context in order for this to be successful. If no algorithm implementation that matches the criteria can be located then the fetch will fail.

See the section on fetching algorithms in the provider man page for further details: [https://www.openssl.org/docs/manmaster/man7/provider.html#Fetching-algorithms].

DISCUSSION HERE ABOUT DEFAULT PROPERTY QUERIES AND HOW TO CONFIGURE THEM

== Using the FIPS Module in applications ==

There are a number of different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

=== Making all applications use the FIPS module by default ===

One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they will automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

$ openssl version -d
OPENSSLDIR: "/usr/local/ssl"

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL on your $PATH. Check that you are running an OpenSSL 3.0 version like this:

$ openssl version -v
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf

Edit the config file to add the following lines near the beginning:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsinstall.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

Obviously the include file location above should match the name of the FIPS module config file that you installed earlier.

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

* You may not want ''all'' applications to use the FIPS module. It may be the case that some applications should and some should not.
* If applications take explicit steps to not load the default config file or set different settings then this method will not work for them
* The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If those applications attempt to use any algorithms that are not present, then they will fail.
* Usage of certain APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

=== Selectively making applications use the FIPS module by default ===

A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following on Unix will cause the application to be executed with a non-standard config file location:

$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

=== Programmatically loading the FIPS module (default library context) ===

Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per the section "Making all applications use the FIPS module by default" above, but edit the fipsinstall.cnf file to remove or comment out the line which says "activate = 1". This means all the required config information will be available to load the FIPS module, but it is not actually automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

fips = OSSL_PROVIDER_load(NULL, "fips");
if (fips == NULL) {
printf("Failed to load FIPS provider\n");
exit(EXIT_FAILURE);
}

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is undefined which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

* Low level cryptographic APIs (use the EVP APIs instead). All such APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.
* Engines
* Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new, EVP_CIPHER_meth_new, EVP_PKEY_meth_new, etc)

=== Loading the FIPS module at the same time as other providers ===

DISCUSSION HERE ABOUT PROPERTY QUERIES

=== Programmatically loading the FIPS module (non-default library context) ===

DISCUSSION HERE ABOUT USING OPENSSL_CTX ETC

=== Using Serializers with the FIPS module ===

STUFF HERE

=== Non-approved alogrithms available in the FIPS module ===

STUFF HERE (X25519, X448, ED25519, ED448)

== STATUS of current development ==



''[this is a collection of notes, changing as time and alpha / beta releases go]''



The current status of OpenSSL 3.0 is '''in development''' 
The next status is expected to be '''alpha'''

=== Platforms ===

These are platforms that have been observed so far. More will be added.

{| class="wikitable"
! Platform !! Builds !! Tests
|-
| Linux x86 / x86_64 || Yes || Yes
|-
| Linux s390x || Yes || Yes
|-
| Windows x86 / x86_64 || Yes || Yes
|-
| MacOS X || Yes || Mostly
|-
| OpenVMS Alpha / Itanium || No || Unknown
|}

=== Features ===

All the core support features are in.

==== Provider implemented operation types ====

{| class="wikitable"
! Operation type !! Code completion % !! Documentation completion % !! Comment
|-
| EVP_DIGEST || 100% || ??
|-
| EVP_CIPHER || 100% || ??
|-
| EVP_MAC || 100% || ??
|-
| EVP_KDF || 100% || ??
|-
| EVP_ASYM_CIPHER || 100%  || ??
|-
| EVP_KEYEXCH || 100%  || ??
|-
| EVP_SIGNATURE || 100%  || ??
|-
| EVP_KEYMGMT || 95% || 70% || Missing functionality for loading HSM keys
|-
| OSSL_SERIALIZER || 50% || 50% || Serializer implemented, deserializer not implemented
|-
| OSSL_STORE || 0% || 0%
|}

==== Provider implemented digests ====

{| class="wikitable"
! Operation type !! Providers !! Code completion % !! Documentation completion % !! Comment
|-
| AES || default, FIPS || 100% || ??
|-
| ARIA || default || 100% || ??
|-
| BF || legacy || 100% || ??
|-
| CAMELLIA || default || 100% || ??
|-
| CAST || legacy || 100% || ??
|-
| DES || legacy || 100% || ??
|-
| DESX || legacy || 100% || ??
|-
| DES-EDE3 || default, FIPS || 100% || ??
|-
| IDEA || legacy || 100% || ??
|-
| RC2 || legacy || 100% || ??
|-
| RC4 || legacy || 100% || ??
|-
| RC5 || legacy || 100% || ??
|-
| SEED || legacy || 100% || ??
|-
| SM4 || default || 100% || ??
|}

==== Provider implemented digests ====

TO BE ADDED

==== Provider implemented MACs ====

TO BE ADDED

==== Provider implemented KDFs ====

TO BE ADDED

==== Provider implemented asymmetric key types ====

TO BE ADDED

==== Provider implemented asymmetric ciphers ====

TO BE ADDED

==== Provider implemented signature ====

TO BE ADDED

==== Provider implemented key exchange ====

TO BE ADDED

==== Provider implemented serializers / deserializers ====

TO BE ADDED

==== Provider implemented OSSL_STORE URI schemes ====

TO BE ADDED

=== Provider implementation support in other OpenSSL APIs ===

Diverse OpenSSL APIs have been modified and continue to be modified to support provider implementations.

{| class="wikitable"
! API !! Code completion % !! Documentation completion % !! Comment
|-
| CMS || 0% || 0%
|-
| CMP || ?? || ??
|-
| CRMF || 5% || 0%
|-
| OSSL_STORE || 0% || 0%
|-
| SSL / TLS || 50% || ??
|}

Configuration "packages"

2020-04-07T04:00:13Z

Levitte: /* Files to add */

If you're missing a configuration for you platform, you may find a "package" here, which may be drop in files just as well as suggestions on what to change in the OpenSSL source to accommodate it.

== z/OS [OpenSSL 1.1.1] ==

OpenSSL 1.1.1 isn't supported on z/OS.

However, if you want to build OpenSSL on z/OS anyway, here are a few hints on how to do that. Though these hints are intended to be helpful, they might not work for you at all, depending on your build environment.

=== Files to add ===

These files can be added in the OpenSSL source tree, in <tt>Configurations/</tt> or in a separate directory. In the latter case, set the environment variable <tt>OPENSSL_LOCAL_CONFIG_DIR</tt> to that directory's name to tell OpenSSL's Configure where they are.

<tt>00-base-zos.conf</tt>:
# Feel free to experiment by uncommenting
zos_asm => {
template => 1,
# cpuid_asm_src => "s390xcap.c # s390xcpuid.s",
bn_asm_src => "bn_asm.c", # s390x-gf2m.s
# ec_asm_src => "ecp_s390x_nistp.c",
# aes_asm_src => "aes-s390x.s aes-ctr.fake aes-xts.fake",
# sha1_asm_src => "sha1-s390x.s sha256-s390x.s sha512-s390x.s",
# rc4_asm_src => "rc4-s390x.s",
# modes_asm_src => "ghash-s390x.s",
# chacha_asm_src => "chacha-s390x.s",
# poly1305_asm_src => "poly1305-s390x.s",
# keccak1600_asm_src => "keccak1600-s390x.s",
}

<tt>zos-unix.conf</tt>
"OS390-Unix" => {
inherit_from => [ "BASE_unix", asm("zos_asm") ],
cc => "/PATH/TO/c99.sh",
cflags => "-O -Wc,dll,XPLINK,exportall,hgpr,lp64 -Wa,'GOFF,SYSPARM(USE_XPLINK)' -qlongname -qlanglvl=extc99 -DB_ENDIAN -DCHARSET_EBCDIC -DNO_SYS_PARAM_H -D_ALL_SOURCE -D_OPEN_THREADS=2 -D_POSIX_SOURCE -D_OPEN_MSGQ_EXT",
module_ldflags => "-Wl,XPLINK,LP64",
shared_ldflags => "-Wl,dll,XPLINK,LP64",
bn_ops => "THIRTY_TWO_BIT RC4_CHAR",
thread_scheme => "(unknown)",
perlasm_scheme => "zOS64",
},

<tt>/PATH/TO/c99.sh</tt>
#!/bin/sh -k
#
# Re-order arguments so that -L comes first.
#
opts=""
lopts=""

for arg in $* ; do
case $arg in
-L*) lopts="$lopts $arg" ;;
*) opts="$opts $arg" ;;
esac
done

c99 -Wl,dll $lopts $opts

Note that if you add <tt>c99.sh</tt> in OpenSSL's <tt>util/</tt> directory, you can set the following in <tt>zos-unix.conf</tt>:

cc => "\$(SRCDIR)/util/c99.sh",

=== Building OpenSSL 1.1.1 ===

(with xplink linkage, 64 bit, from EBCDIC sources)

# get a working EBCDIC perl version.
# gunzip the .tar file.
# use pax to extract from .tar. Example: <tt>pax -ofrom=ISO8859-1,to=IBM-1047 -rvf openssl-1.1.1e.tar</tt>
# Configure: <tt>./Configure OS390-Unix</tt>
# Build: <tt>make</tt>

Configuration "packages"

2020-04-06T12:59:26Z

Levitte: First attempt at a Configuration "package", inspired by https://github.com/openssl/openssl/pull/11262

If you're missing a configuration for you platform, you may find a "package" here, which may be drop in files just as well as suggestions on what to change in the OpenSSL source to accommodate it.

== z/OS [OpenSSL 1.1.1] ==

OpenSSL 1.1.1 isn't supported on z/OS.

However, if you want to build OpenSSL on z/OS anyway, here are a few hints on how to do that. Though these hints are intended to be helpful, they might not work for you at all, depending on your build environment.

=== Files to add ===

These files can be added in the OpenSSL source tree, in <tt>Configurations/</tt> or in a separate directory. In the latter case, set the environment variable <tt>OPENSSL_LOCAL_CONFIG_DIR</tt> to that directory's name to tell OpenSSL's Configure where they are.

<tt>00-base-zos.conf</tt>:
# Feel free to experiment by uncommenting
zos_asm => {
template => 1,
# cpuid_asm_src => "s390xcap.c # s390xcpuid.s",
bn_asm_src => "bn_asm.c", # s390x-gf2m.s
# ec_asm_src => "ecp_s390x_nistp.c",
# aes_asm_src => "aes-s390x.s aes-ctr.fake aes-xts.fake",
# sha1_asm_src => "sha1-s390x.s sha256-s390x.s sha512-s390x.s",
# rc4_asm_src => "rc4-s390x.s",
# modes_asm_src => "ghash-s390x.s",
# chacha_asm_src => "chacha-s390x.s",
# poly1305_asm_src => "poly1305-s390x.s",
# keccak1600_asm_src => "keccak1600-s390x.s",
}

<tt>zos-unix.conf</tt>
"OS390-Unix" => {
inherit_from => [ "BASE_unix", asm("zos_asm") ],
cc => "/PATH/TO/c99.sh",
cflags => "-O -Wc,dll,XPLINK,exportall,hgpr,lp64 -Wa,'GOFF,SYSPARM(USE_XPLINK)' -qlongname -qlanglvl=extc99 -DB_ENDIAN -DCHARSET_EBCDIC -DNO_SYS_PARAM_H -D_ALL_SOURCE -D_OPEN_THREADS=2 -D_POSIX_SOURCE -D_OPEN_MSGQ_EXT",
module_ldflags => "-Wl,XPLINK,LP64",
shared_ldflags => "-Wl,dll,XPLINK,LP64",
bn_ops => "THIRTY_TWO_BIT RC4_CHAR",
thread_scheme => "(unknown)",
perlasm_scheme => "zOS64",
},

<tt>/PATH/TO/c99.sh</tt>
#!/bin/sh -k
#
# Re-order arguments so that -L comes first.
#
opts=""
lopts=""

for arg in $* ; do
case $arg in
-L*) lopts="$lopts $arg" ;;
*) opts="$opts $arg" ;;
esac
done

c99 -Wl,dll $lopts $opts

Note that if you add <tt>c99.sh</tt> in OpenSSL's <tt>util/</tt> directory, you can set the following in <tt>zoss-unix.conf</tt>:

cc => "\$(SRCDIR)/util/c99.sh",

=== Building OpenSSL 1.1.1 ===

(with xplink linkage, 64 bit, from EBCDIC sources)

# get a working EBCDIC perl version.
# gunzip the .tar file.
# use pax to extract from .tar. Example: <tt>pax -ofrom=ISO8859-1,to=IBM-1047 -rvf openssl-1.1.1e.tar</tt>
# Configure: <tt>./Configure OS390-Unix</tt>
# Build: <tt>make</tt>

Main Page

2020-04-06T12:32:28Z

Levitte: /* OpenSSL Quick Links */

This is the OpenSSL wiki. The main site is https://www.openssl.org . If this is your first visit or to get an account please see the [[Welcome]] page. Your participation and [[Contributions]] are valued.

This wiki is intended as a place for collecting, organizing, and refining useful information about OpenSSL that is currently strewn among multiple locations and formats.

== OpenSSL Quick Links ==

<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Configuration "packages"]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Documentation Index|Index of all API functions]]</TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Binaries]]</TD>
</TR>
<TR>
<TD>[[SSL and TLS Protocols]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[1.1 API Changes]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[FIPS modules]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[TLS1.3]]</TD>
</TR>
<TR>
<TD>[[Mailing Lists]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD></TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD></TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD></TD>
</TR>
</TABLE>

== Administrivia ==
Site guidelines, legal and admininstrative issues.
:* [[Basic rules]], [[Commercial Product Disclaimer]], [[Contributions]], [[Copyright]], [[License]]
:* Using This Wiki
:: [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide], [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list], [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ], [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki Mailing List]

== Reference ==
This section contains the automagically generated man pages from the OpenSSL git repository, and similar "man" style reference documentation. The man pages are automatically imported from the OpenSSL git repository and local wiki modifications are submitted as patches.
:* [https://www.openssl.org/docs/manpages.html OpenSSL Manual Pages]
:* [[API]], [[Libcrypto API]], [[Libssl API]]
:* [[FIPS mode()]], [[FIPS_mode_set()]]

== Usage and Programming ==
This section has discussions of practical issues in using OpenSSL
:* Building from Source
:: Where to find it, the different versions, how to build and install it.
:* [[OpenSSL Overview]]
:* [[Versioning]]
:* [[Compilation and Installation]]
:* [[EVP]]
:: Programming techniques and example code
:: Use of EVP is preferred for most applications and circumstances
::* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
::* [[EVP Authenticated Encryption and Decryption]]
::* [[EVP Symmetric Encryption and Decryption]]
::* [[EVP Key and Parameter Generation]]
::* [[EVP Key Agreement]]
::* [[EVP Message Digests]]
::* [[EVP Key Derivation]]
::* [[EVP Signing and Verifying|EVP Signing and Verifying (including MAC codes)]]
:* [[STACK API]]
:* [[List of SSL OP Flags]]
:* Low Level APIs
::[[Creating an OpenSSL Engine to use indigenous ECDH ECDSA and HASH Algorithms]]
:: More specialized non-EVP usage
::* [[Diffie-Hellman parameters]]
:* [[FIPS Mode]]
:* [[Simple TLS Server]]

== Concepts and Theory ==
Discussions of basic cryptographic theory and concepts
Discussions of common operational issues
:* [[Base64]]
:* [http://wiki.openssl.org/index.php/Category:FIPS_140 FIPS 140-2]
:* [[Random Numbers]]
:* [[Diffie Hellman]]
:* [[Elliptic Curve Diffie Hellman]]
:* [[Elliptic Curve Cryptography]]

== Security Advisories ==
:* [https://www.openssl.org/policies/secpolicy.html OpenSSL Security Policy]
:* [https://www.openssl.org/news/vulnerabilities.html OpenSSL Vulnerabilities List]
:* [[Security_Advisories|Security Advisories Additional Information]]

== Feedback and Contributions ==
:* [https://www.openssl.org/news/vulnerabilities.html How to notify us of suspected security vulnerabilities]
:* [https://www.openssl.org/community/#bugs How to report bugs, other than for suspected vulnerabilities]
:* [[Contributions|General background on source and documentation contributions - '''must read''']]
:* Contributing code fixes, other than for suspected vulnerabilities, as well as fixes and other improvements to manual pages:
::* If you are unsure as to whether a feature will be useful for the general OpenSSL community please discuss it on the [https://www.openssl.org/community/ openssl-users mailing list] first. Someone may be already working on the same thing or there may be a good reason as to why that feature isn't implemented.
::* Follow the [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|instructions for accessing source code]] in the appropriate branches. Note that manual pages and the FAQ are maintained with the source code.
::* Submit a pull request for each separate fix (also documented [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|there]])
::* Submit a bug report (see second bullet, above) and reference the pull request. Or you can attach the patch to the ticket.
:* Contributing fixes and other improvements to the web site
::* Follow the [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|instructions for accessing web site sources]]
::* Create a patch (also documented [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|there]])
::* Submit a bug report and add the patch as an attachment
:* [[Developing For OpenSSL]]
:* [[KnownPatches|Known patches not part of OpenSSL]]
:* [[Welcome|Contributing to this wiki]]

== Internals and Development ==
This section is for internal details of primary interest to OpenSSL maintainers and power users
:* [[Code reformatting]]

:* [[Internals]]
:* [[Code Quality]]
:* [[Static and Dynamic Analysis]]
:* [[OCB|OCB Licence details]]
:* [[Defect and Feature Review Process]]
:* [[Unit Testing]] (includes other automated testing information)
:* [[How to Integrate a Symmetric Cipher]]

Talk:OpenSSL 1.1.0 Changes

2020-03-27T06:51:14Z

Levitte:

== Converting code to be compatible with both OpenSSL 1.0.x and 1.1.x ==

Small correction to the example at [[1.1_API_Changes#Adding_forward-compatible_code_to_older_versions]]:

<tt>HMAC_CTX_reset</tt>, and <tt>EVP_MD_CTX_free</tt> are OpenSSL 1.1 APIs themselves so their use should be avoided in the <tt>#if</tt> section.

Suggested example:

<code>
#if (OPENSSL_VERSION_NUMBER < 0x10100000L) || defined (LIBRESSL_VERSION_NUMBER)
static HMAC_CTX *HMAC_CTX_new(void)
{
HMAC_CTX *ctx = OPENSSL_malloc(sizeof(*ctx));
if (ctx != NULL)
HMAC_CTX_init(ctx);
return ctx;
}

static void HMAC_CTX_free(HMAC_CTX *ctx)
{
if (ctx != NULL) {
HMAC_CTX_cleanup(ctx);
OPENSSL_free(ctx);
}
}
#endif
</code>

Similarly examples for other APIs that I encountered:
<code>
#if (OPENSSL_VERSION_NUMBER < 0x10100000L) || defined (LIBRESSL_VERSION_NUMBER)
#define EVP_MD_CTX_new EVP_MD_CTX_create
#define EVP_MD_CTX_free EVP_MD_CTX_destroy
#endif

#if (OPENSSL_VERSION_NUMBER < 0x10100000L) || defined(LIBRESSL_VERSION_NUMBER)
#define ASN1_STRING_get0_data(x) ASN1_STRING_data(x)
#endif
</code>
--[[User:Edwintorok|Edwintorok]] ([[User talk:Edwintorok|talk]]) 13:30, 23 September 2016 (UTC)

== Please update the "No longer works" section ==

That section is ''seriously'' outdated.

--[[User:Levitte|Levitte]] ([[User talk:Levitte|talk]]) 06:51, 27 March 2020 (UTC)

Talk:Compilation and Installation

2019-10-05T10:45:06Z

Levitte: /* Page has grown too large */

== Page has grown too large ==

Hi Everyone. I think this page has grown too large and should be separated into separate pages. It has become messy and hard to organize the information.

Painting with a broad brush, leave "Compilation and Installation" as the main landing page. Always refer to it from external places, like Stack Overflow. At "Compilation and Installation" include the basic information, like intro discussion of various platforms and the Unix/Linux options. Then, create separate subpages for specific platforms, like Linux, OS X, Windows, Windows CE, etc. "Compilation and Installation" provides a link to each subpage.

Does anyone have any thoughts?

[[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 23:31, 4 October 2019 (UTC)

: Good idea. Are you willing to start on that?
:
: --[[User:Levitte|Levitte]] ([[User talk:Levitte|talk]]) 10:45, 5 October 2019 (UTC)

User talk:Matt

2019-10-04T14:32:02Z

Levitte: Created page with "You might want to update your page ;-) --~~~~"

You might want to update your page ;-)

--[[User:Levitte|Levitte]] ([[User talk:Levitte|talk]]) 14:32, 4 October 2019 (UTC)

Talk:EVP Key Derivation

2019-09-15T07:23:16Z

Levitte:

== About this page ==

It should be noted that ever since this page got filled in with examples and all that, it strictly talks about upcoming functionality. The '''EVP_KDF''' API doesn't exist in any current release (and hasn't reached its final form yet), but will be part of the upcoming 3.0 release. It's therefore to be expected that the example shown on this page will change as the API evolves.

--[[User:Levitte|Levitte]] ([[User talk:Levitte|talk]]) 04:13, 15 September 2019 (UTC)

: This is the gist of my direct comment. The ctrl APIs were transient, we're migrating to OSSL_PARAM based ones globally -- it's just going to take a while.
:
: --[[User:Pauli|Pauli]] ([[User talk:Pauli|talk]])

User talk:Pauli

2019-09-15T04:16:18Z

Levitte:

== KDF Changes ==
I think the [modified] KDF example may be too new for most users of OpenSSL. For example, it appears OSSL_PARAM is part of an upcoming release: https://www.openssl.org/docs/manmaster/man3/OSSL_PARAM.html .

I think the new example is going to cause confusion for most users rather than helping them. Also, answers on Stack Overflow a pointing back to the wiki and the old example.

Perhaps you can add the new example as a distinct second example, and clearly state it is part of the OpenSSL 3.0 API.

[[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 00:14, 15 September 2019 (UTC)

: Shouldn't this be discussed on the discussion tab of the page that was changed? That would probably make it a little easier for the rest of us to understand what's going on, rather than this random discussion added to a user page that doesn't even exist...
: --[[User:Levitte|Levitte]] ([[User talk:Levitte|talk]]) 03:57, 15 September 2019 (UTC)

:: Yeah, I was trying to have a sidebar to encourage an edit. Sorry about that.
::
:: [[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 04:00, 15 September 2019 (UTC)

::: I have added a note on the "offending page's" discussion tab, to clarify the hows and the whys for changes happening there. Hope that helps.
::: --[[User:Levitte|Levitte]] ([[User talk:Levitte|talk]]) 04:16, 15 September 2019 (UTC)

Talk:EVP Key Derivation

2019-09-15T04:13:47Z

Levitte: Created page with " == About this page == It should be noted that ever since this page got filled in with examples and all that, it strictly talks about upcoming functionality. The '''EVP_KDF''..."

User talk:Pauli

2019-09-15T03:57:49Z

Levitte: /* KDF Changes */

Libssl API

2019-07-10T09:11:18Z

Levitte:

libssl is the portion of OpenSSL which supports TLS ( [[SSL and TLS Protocols]] ), and depends on [[Libcrypto API|libcrypto]].

This is a '''C''' api. To use it you need to include (at least) '''openssl/ssl.h''' and to link your program with libssl library.

* [[Diffie-Hellman parameters]]
* [[Hostname validation]]

== How to get libssl API to compile with it ==

on Debian base ( debian, ubuntu, ... ) you would need libssl-dev : apt-get install libssl-dev.

on Redhat base ( RedHat, Fedora, ... ) you would need openssl-devel : yum install openssl-devel

You can get sources directly too to compile statically over it.

[[Category:Ssl API]]

Enc

2018-10-08T05:03:10Z

Levitte: Style fix

This page describes the command line tools for encryption and decryption. [[enc|Enc]] is used for various block and stream ciphers using keys based on passwords or explicitly provided. It can also be used for Base64 encoding or decoding.

===Synopsis===

The basic usage is to specify a ciphername and various options describing the actual task.

<pre>
$ openssl enc -ciphername [options]
</pre>

You can obtain an incomplete help message by using an invalid option, eg. '''-help'''.

===Cipher alogorithms===

To get a list of available ciphers you can use the '''list-cipher-algorithms''' command
<pre>
$ openssl list-cipher-algorithms
</pre>

The output gives you a list of ciphers with its variations in [[key size]] and [[mode of operation]]. For example '''AES-256-CBC''' for [[AES]] with key size 256 bits in [[CBC|CBC-mode]]. Some ciphers also have short names, for example the one just mentioned is also known as '''aes256'''. These names are case insensitive. In addition '''none''' is a valid ciphername. This algorithms does nothing at all.
===Options===
The list of options is rather long.

;-in ''filename''
:This specifies the input file.

;-out ''filename''
:This specifies the output file. It will be created or overwritten if it already exists.

;-e or -d
: This specifies whether to encrypt ('''-e''') or to decrypt ('''-d'''). Encryption is the default. Of course you have to get all the other options right in order for it to function properly. In particular it is necessary to give the correct cipher-name as well as '''-a''', '''-A''' or '''-z''' options.

;-a, -A, -base64
: These flags tell OpenSSL to apply [[Base64]]-encoding before or after the cryptographic operation. The '''-a''' and '''-base64''' are equivalent. If you want to decode a base64 file it is necessary to use the '''-d''' option. By default the encoded file has a line break every 64 characters. To suppress this you can use ''in addition'' to '''-base64''' the '''-A''' flag. This will produce a file with no line breaks at all. You can use these flags just for [[#Base64 Encoding|encoding Base64]] without any ciphers involved.

;-bufsize ''n''
: Specify the buffer size. This concerns only internal buffers. It has nothing to do with the cryptographic algorithms in question.

;-debug
: Enable debugging output. This does not include any sensitive information. See also '''-P'''.

;-engine ''id''
: Specify an [[engine]] for example to use special hardware.

;-iv ''IV''
: This specifies the [[initialization vector]] ''IV'' as hexadecimal number. If not explicitly given it will be derived from the password. See key derivation for details.

;-k ''password'', -kfile ''filename''
: Both option are used to specify a password or a file containing the password which is used for key derivation. However '''they are deprecated'''. You should use the ''-pass'' option instead. The equivalents are '''-pass pass:'''''password'' and '''-pass: file:'''''filename'' respectively.

;-K ''key''
: This option allows you to set the ''key'' used for encryption or decryption. This is the key directly used by the cipher algorithm. If no key is given OpenSSL will derive it from a password. This process is described in PKCS5#5 (RFC-2898).

;-md ''messagedigest''
: This specifies the message digest which is used for key derivation. It can take one of the values '''md2''', '''md5''', '''sha''' or '''sha1'''.

;-nopad
: This disables standard padding.

;-salt, -nosalt, -S ''salt''
: These options allow to switch [[Salt|salting]] on or off. With '''-S''' ''salt'' it is possible to explicitly give its value (in hexadecimal).

;-p, -P
: Additionally to any encryption tasks, this prints the key, initialization vector and salt value (if used). If '''-P''' is used just these values are printed, no encryption will take place.

;-pass ''arg''
: This specifies the password source. Possible values for ''arg'' are '''pass:'''''password'' or '''file:'''''filename'', where ''password'' is your password and ''filename'' file containing the password.

;-z
: Use this flag to enable [http://www.zlib.net/ zlib-compression]. After a file is encrypted (and maybe base64 encoded) it will be compressed via zlib. Vice versa while decrypting, zlib will be applied first.

===Examples===
====Base64 Encoding====
To encode a file ''text.plain'' you can use
<pre>
$ openssl enc -base64 -in text.plain -out text.base64
</pre>

To decode a file the the decrypt option ('''-d''') has to be used

<pre>
$ openssl enc -d -base64 -in text.base64 -out text.plain
</pre>

====Encryption====

=====Basic Usage=====
The most basic way to encrypt a file is this
<pre>
$ openssl enc -aes256 -base64 -in some.secret -out some.secret.enc
enter aes-256-cbc encryption password :
Verifying - enter aes-256-cbc encryption password :
</pre>

It will encrypt the file ''some.secret'' using the [[AES|AES-cipher]] in [[CBC|CBC-mode]]. The result will be Base64 encoded and written to ''some.secret.enc''. OpenSSL will ask for password which is used to derive a key as well the initialization vector.
Since encryption is the default, it is not necessary to use the '''-e''' option.

=====Use a given Key=====

It also possible to specify the key directly. For most [[modes of operations]] (i.e. all non-ECB modes) it is then necessary to specify an initialization vector. Usually it is derived together with the key form a password. And as there is no password, also all salting options are obsolete.

The key and the IV are given in hex. Their length depending on the cipher and key size in question.

<pre>
$ openssl enc -des-ecb -K e0e0e0e0f1f1f1f1 -in mesg.plain -out mesg.enc
</pre>

The key above is one of 16 [http://en.wikipedia.org/wiki/Weak_key weak DES keys]. It should not be used in practice.

[[Category:Shell level]]