OpenSSLWiki - User contributions [en]

FIPS mode and TLS

2024-02-02T08:32:31Z

Matt: Added sentence about the new FIPS module

This page discusses the use of FIPS with OpenSSL 1.0.x. It is NOT relevant to the FIPS provider in OpenSSL 3.0 or above.

The new SP800-131A and FIPS 186-4 restrictions on algorithms and key sizes complicate
the use of ciphersuites for TLS considerably. This page is intended to answer the
question "can I configure an OpenSSL cipherstring for TLS to comply with the new FIPS restrictions?".

This discussion assumes use of a "FIPS capable" OpenSSL 1.0.1f or later.

A new security framework in development for future versions will make enforcing these types
of restrictions easier and the algorithm restrictions are performed all in one place.

== Quick Summary ==

The preferred cipherstring for OpenSSL 1.0.1f+ for all versions of TLS subject to the new FIPS
restrictions is:
<pre>
'TLSv1.2+FIPS:kRSA+FIPS:!eNULL:!aNULL'
</pre>
However, multiple caveats apply as discussed below.

Workarounds for OpenSSL releases prior to 1.0.1f are discussed below.

== Detailed discussion ==

The general rule is you can't use SHA1 for digital signatures any more nor
a combination like MD5+SHA1. You *can* use SHA1 for HMAC so there's no need to
force the use of SHA256 HMAC ciphersuites.

A cipherstring in OpenSSL also known as a "cipher list"
https://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS
A cipherstring in OpenSSL is a compact notation for a set of cryptographic algorithms
(public key, symmetric key, and digest algorithms) in order of preference.

The cipherstring notation is discussed at https://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT
Briefly, a cipherstring is a series of elements each designating either a specific ciphersuite or a set of
ciphersuites. The "+" operator designates a logical and operation, so "element1+element1" represents that
set of ciphersuites containing the algorithms in both element1 and element2. The "!" operator permanently
all the algorithms in the following element.

=== TLS 1.0 and 1.1 ===

All TLS 1.0/1.1 authenticated PFS (Perfect Forward Secrecy) ciphersuites use SHA1 alone or MD5+SHA1. That
leaves only unauthenticated ones (which are vulnerable to MiTM so we discount
them) or those using static keys. Theoretically that would permit RSA, DH or
ECDH keys in certificates but in practice everyone uses RSA.

The corresponding cipherstring is:
<pre>
openssl ciphers -v 'kRSA+FIPS:!TLSv1.2'
AES256-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(256) Mac=SHA1
DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1
AES128-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA1
</pre>
That cipherstring specifies three possible ciphersuites allowable in FIPS mode for TLS 1.0 and 1.1.
The RSA key in the certificate has to be of suitable size
(2048 bits minimum) as do all other keys in the chain and none of the CAs can
sign using SHA1. Also those kRSA ciphersuites are allowed for
server certificates only; client authentication is never allowed
with the new rules for TLS 1.0 and 1.1.

In a real application when FIPS mode is enabled then only
FIPS ciphersuites are allowed no matter what you use in the string. So in FIPS mode
"kRSA:!TLSv1.2" will be functionally equivalent to "kRSA+FIPS!TLSv1.2".

Note the "TLSv1.2" string was only added to OpenSSL recently, as of OpenSSL 1.0.1f.
It designates the ciphers for TLSv1.2 subject to the FIPS 140-2 and FIPS 186-4
restrictions.

Note the cipherstring 'FIPS:!TLSv1.2' would also allow fixed DH and fixed ECDH
certificates but those are not encountered in the wild.
The key exchange component "kRSA" specifies just those algorithms that support RSA key exchange.

=== TLS 1.2 ===

TLS 1.2 provides more options as the signature can use an algorithm other
than SHA1.
"kRSA+FIPS" specifies those ciphersuites that use RSA key exchange, including TLS v1.2, *and*
are allowed in FIPS mode, and including anonymous ones which may be undesirable:
<pre>
openssl ciphers -v 'kRSA+FIPS'
AES256-GCM-SHA384 TLSv1.2 Kx=RSA Au=RSA Enc=AESGCM(256) Mac=AEAD
AES256-SHA256 TLSv1.2 Kx=RSA Au=RSA Enc=AES(256) Mac=SHA256
AES256-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(256) Mac=SHA1
DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1
AES128-GCM-SHA256 TLSv1.2 Kx=RSA Au=RSA Enc=AESGCM(128) Mac=AEAD
AES128-SHA256 TLSv1.2 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA256
AES128-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA1
</pre>
The ephemeral key for the now permitted PFS keys must be at least 2048 bits (DH)
or 256 bits (ECDH) in size. Anything supporting ECDH will probably set P-256 as
a default so that should be OK (Apache does).

There's a snag though. The ciphersuite ECDH-RSA-AES128-SHA can (outside FIPS) be
used for TLS 1.0 and later whereas in FIPS mode it can only be used for TLS v1.2. A
TLS client can't advertise ciphersuites in that way (i.e. you can use this for
TLS1.2 only and nothing earlier) so you're left with the situation where a FIPS
compliant client might say it wants ECDH-RSA-AES128-SHA
and TLS 1.2 and the server only supports TLS 1.0 so it will choke when it tries to
use the prohibited ciphersuite+version combination. Servers are fine because
they can theoretically select based on version (except in practice OpenSSL doesn't support that).

If that wasn't enough there's another complication. For TLS v1.2 you have to
restrict the supported signature algorithms to exclude SHA1, allowing only
SHA256 and above. There is no way to do that in OpenSSL 1.0.1 clients.
Similarly the supported EC curves have to be restricted to exclude some which are
of insufficient field size.

In summary: it's a bloody mess.

The list of allowable ciphers for all versions of TLS, 1.0/1/1/1.2 is 'TLSv1.2:kRSA'
which includes those with no encryption or no authentication which are generally
undesirable and should be excluded. In full with explicit "+FIPS" qualification that becomes:
<pre>
'TLSv1.2+FIPS:kRSA+FIPS:!eNULL:!aNULL'
ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
ECDHE-ECDSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH Au=ECDSA Enc=AESGCM(256) Mac=AEAD
ECDHE-RSA-AES256-SHA384 TLSv1.2 Kx=ECDH Au=RSA Enc=AES(256) Mac=SHA384
ECDHE-ECDSA-AES256-SHA384 TLSv1.2 Kx=ECDH Au=ECDSA Enc=AES(256) Mac=SHA384
DHE-DSS-AES256-GCM-SHA384 TLSv1.2 Kx=DH Au=DSS Enc=AESGCM(256) Mac=AEAD
DHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=DH Au=RSA Enc=AESGCM(256) Mac=AEAD
DHE-RSA-AES256-SHA256 TLSv1.2 Kx=DH Au=RSA Enc=AES(256) Mac=SHA256
DHE-DSS-AES256-SHA256 TLSv1.2 Kx=DH Au=DSS Enc=AES(256) Mac=SHA256
ECDH-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH/RSA Au=ECDH Enc=AESGCM(256) Mac=AEAD
ECDH-ECDSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH/ECDSA Au=ECDH Enc=AESGCM(256) Mac=AEAD
ECDH-RSA-AES256-SHA384 TLSv1.2 Kx=ECDH/RSA Au=ECDH Enc=AES(256) Mac=SHA384
ECDH-ECDSA-AES256-SHA384 TLSv1.2 Kx=ECDH/ECDSA Au=ECDH Enc=AES(256) Mac=SHA384
AES256-GCM-SHA384 TLSv1.2 Kx=RSA Au=RSA Enc=AESGCM(256) Mac=AEAD
AES256-SHA256 TLSv1.2 Kx=RSA Au=RSA Enc=AES(256) Mac=SHA256
ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(128) Mac=AEAD
ECDHE-ECDSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH Au=ECDSA Enc=AESGCM(128) Mac=AEAD
ECDHE-RSA-AES128-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AES(128) Mac=SHA256
ECDHE-ECDSA-AES128-SHA256 TLSv1.2 Kx=ECDH Au=ECDSA Enc=AES(128) Mac=SHA256
DHE-DSS-AES128-GCM-SHA256 TLSv1.2 Kx=DH Au=DSS Enc=AESGCM(128) Mac=AEAD
DHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=DH Au=RSA Enc=AESGCM(128) Mac=AEAD
DHE-RSA-AES128-SHA256 TLSv1.2 Kx=DH Au=RSA Enc=AES(128) Mac=SHA256
DHE-DSS-AES128-SHA256 TLSv1.2 Kx=DH Au=DSS Enc=AES(128) Mac=SHA256
ECDH-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH/RSA Au=ECDH Enc=AESGCM(128) Mac=AEAD
ECDH-ECDSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH/ECDSA Au=ECDH Enc=AESGCM(128) Mac=AEAD
ECDH-RSA-AES128-SHA256 TLSv1.2 Kx=ECDH/RSA Au=ECDH Enc=AES(128) Mac=SHA256
ECDH-ECDSA-AES128-SHA256 TLSv1.2 Kx=ECDH/ECDSA Au=ECDH Enc=AES(128) Mac=SHA256
AES128-GCM-SHA256 TLSv1.2 Kx=RSA Au=RSA Enc=AESGCM(128) Mac=AEAD
AES128-SHA256 TLSv1.2 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA256
AES256-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(256) Mac=SHA1
DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1
AES128-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA1
</pre>
What does this ciphersuite specification mean in practice?

If the peer supports TLS v1.2 it will use a TLS v1.2 ciphersuite which is FIPS
186-4 compliant (with the curve and signature restrictions I mentioned) or
non-PFS RSA otherwise.

If the peer only supports TLS 1.1 or 1.0 it will fall back to the non-PFS RSA
ciphersuites which again will be FIPS 186-4 compliant subject to the silly key
and certificate signing restrictions.

The ciphersuite (for 1.0.1f+) of 'TLSv1.2+FIPS:kRSA+FIPS:!eNULL:!aNULL'
will satisfy FIPS 186-4 for any version of TLS 1.0/1.1/1.2 with caveats as noted.

To specify a list of allowable ciphers for TLS 1.0/1.1 only append !TLSv1.2 which permanently deletes
those which are only usable for TLS v1.2, giving 'kRSA+FIPS:!TLSv1.2'.

=== Cipherstrings ===

Commentary on what the cipherstrings components mean and their relevance:

"TLSv1.2": list of ciphersuites only allowed for TLS 1.2. This means if TLS 1.2
is negotiated they can be used and if not they won't. They also happen to be
permitted by FIPS 186-4 because TLS 1.2 can use signature algorithms stronger
that SHA1. That means that it is "safe" to include this in a cipher string
because (a) they are compliant with FIPS 186-4 in for TLS 1.2 and (b) they can
never be used for TLS 1.1 or 1.0.

"kRSA": list of ciphersuites which support RSA key exchange. Because TLS 1.1 and
1.0 can only use SHA1+MD5 in signatures these are the only ones allowed because
they don't use signatures.

"FIPS": list of ciphersuites allowed in FIPS mode excluding those offering no
encryption. This is for informational purposes only because if you *are* in FIPS
mode you can only use those ciphersuites anyway (but including the no encryption
ones).

The lists above all include ciphersuites which you wouldn't normally use: no
encryption or no authentication. So those need to be disabled. This is done by
appending '!eNULL:!aNULL': this means "disable any ciphersuites present which
include no encryption or authentication".

So combining these we get the following cipher string in FIPS mode:
<pre>
'TLSv1.2:kRSA:!eNULL:!aNULL'
</pre>
which with the functionally redundant "+FIPS" qualifiers is equivant to:
<pre>
'TLSv1.2+FIPS:kRSA+FIPS:!eNULL:!aNULL'
</pre>
Without the "+FIPS" qualifiers and outside FIPS mode you'll will see weak export grade
ciphersuites which would be disabled in FIPS mode. Those can be seen with:
<pre>
openssl ciphers -v 'TLSv1.2:kRSA:!eNULL:!aNULL'
</pre>
To see the actual set of ciphersuites in FIPS mode, without the explicit "+FIPS" qualifiers,
do:
<pre>
OPENSSL_FIPS=1 openssl ciphers -v 'TLSv1.2:kRSA:!eNULL:!aNULL'
</pre>
So in summary "in FIPS mode use the cipherstring 'TLSv1.2:kRSA:!eNULL:!aNULL'"

Note this important disclaimer though: This cipherstring *only* restricts the ciphersuites to those
not explicitly excluded by FIPS 186-4. There are other conditions which must be
enforced such as key size, permitted curves and permitted signature algorithms.
Just because a ciphersuite has been negotiated in this range does not guaranteed
compliance.

The "FIPS capable" OpenSSL does not currently provide a means to automatically enforce the
new FIPS 186-4 restrictions.

=== A quick overview of TLS ===

The primary purpose of the handshake is to enable both peers to securely obtain
a shared secret value called the pre-master secret. They then use that to
generate session keys (encryption and MAC) which are used for the exchange of
actual application data. The handshake is the only place public key algorithms
are used.

In the case of PFS ciphersuites both ends generate a temporary key (ECDH or DH)
and exchange the public bits with each other. They use the algorithm to generate
the shared DH/ECDH secret value which is used later on. The new FIPS restrictions interfere with
this because those keys have to be large enough. For ECDH an extension can be
used to ensure this. For DH you just have to hope the server has a big enough
key and abort if not.

For anonymous algorithms that's all you get. They are vulnerable to man in the
middle (MitM) attacks and so are rarely used.

In the real world algorithms include authentication. In those the server digitally
signs its ECDH or DH key using the key in its certificate. This is to ensure the
temporary ECDH or DH key can't be forged. It is that digital signature that is
important here and the one which the new FIPS restrictions disrupt.

How that temporary key is signed depends on the cipher suite and the key in the
server's certificate. The whole process is called server authentication.

In the case of TLS 1.0 and 1.1 that signature uses a MD5+SHA1 hybrid for RSA
keys and just SHA1 for DSA and ECDSA. That's why PFS is prohibited by the new FIPS
rules: there is no option but to use SHA1.

In the case of TLS 1.2 any valid combination can be used and the MD5+SHA1 hybrid is no
longer present for RSA. RSA just uses the same signature format that
certificates use (PKCS#1).

For TLS 1.2 the client sends the set of signature algorithms it supports in
preference order in the supported signature algorithms extensions. The server
then selects one and uses that for that signature. For new FIPS it would just
use SHA256 as a minimum or abort the connection if the client only supported
SHA1 (unlikely).

Client authentication in TLS is a secondary concern. In this case the client
signs some data related to the handshake and sends the result back. The server
then checks that signature.

As with server authentication TLS 1.1/1.0 has to use either MD5+SHA1 for RSA or
just SHA1 for other algorithms. So client authentication violates the new FIPS
restrictions and cannot be used for TLs 1.0/1.1.

TLS 1.2 removes the restriction to SHA1. In this case the server sends back the
algorithms it supports and the client selects one. Again SHA256 or
better s needed to comply with new FIPS restrictions.

Next consider the non-PFS case. We consider RSA
key exchange only as is the only practical option. This is completely different from PFS. In
this case the client generates the pre master secret and encrypts it using the
servers key. The server decrypts it and then uses that to complete the
handshake. No additional signing is used here so no place for SHA1 to be used.
The server is authenticated because if it didn't have the right key it couldn't
decrypt the pre-master secret. It's a bit unusual in that authentication (which
is normally associated with signatures) is performed using an RSA decryption
operation.

Some further discussion in case that wasn't confusing enough:

Some people say that it is implied that TLS 1.1 and 1.0 must use SHA1 in
digital signatures in all certificates. If so then
TLS 1.1 and 1.0 can never be compliant with new FIPS.

Assuming that is not true, what does it mean in practice? A
a public webserver would require a certificate signed by CAs that
use SHA256 minimum and large enough keys. Not a trivial
task in itself.

Aside from that, problems will be encountered if your server needs to use anything
outside of the new FIPS restrictions (e.g. to talk to other
clients). Some older browsers (e.g. IE on XP is one which is
still very common) don't support SHA2 at all. So they'll fail when they talk to
that server because the can't verify the signatures.

TLS 1.2 is a bit better, at least in theory. The supported signatures should apply to the
whole certificate chain. So a client advertising only SHA1+RSA receive a
chain supporting SHA1+RSA only (if the server has one) and a client supporting SHA256+RSA
will receive a "new FIPS" friendly chain.

However, in practice that requirement is generally ignored and implementations serve up whatever
chain is configured regardless of signature algorithms sent by the client
because many implementers consider that a slly restriction. For interoperability OpenSSL is
similarly lax if a "strict" option isn't set. In fact configuring multiple
chains like that can't be directly done in OpenSSL without application support
which nothing other than s_server can currently handle.

==== Digests in TLS ====

There are different purposes that digest algorithms are put to.

In TLS 1.2 something called the supported signature algorithms extension
determines the supported digests as a public key + algorithm pair. It's that
usage that FIPS 186-4 (and SP800-57) has an impact on. So you can't use RSA+SHA1
any more. For digital signatures the strength of SHA1 is at most 80 bits: it can
be less with a weak key.

That digital signature is used to maintain the integrity of the handshake
messages and certificate chains in PFS ciphersuites: basically server and client
authentication.

For TLS 1.2 you can specify any digest to be used to maintain handshake
integrity for digital signatures: for TLS 1.1 and below you could only use
SHA1+MD5. It's that reason why PFS ciphersuites are banned in TLS 1.1 and below.

Digests use HMAC. For HMAC use the key strength is the digest length so SHA1 is 160 bits.

Before TLS 1.2 all cipher suites used SHA1 HMAC (or in legacy cases MD5) for the
HMAC.

TLS 1.2 introduced some ciphersuites which used SHA256 and SHA384 for the HMAC
and the AEAD ones like AES-GCM which have a mac as part of the algorithm itself.

Note that TLS 1.2 also permits all the ciphersuites for TLS 1.1, 1.0 too.
For details see Table 2 and 3 in SP800-57.

Those tables make a lot more sense when you realise for digital signatures it's
half the digest size. So SHA1 is 20 bytes which is 160 bits and so 80 bits of
strength so it only appears in the "80 bits" box for digital signatures. Whereas
for other uses it is the full digest size so SHA1 appears in the 80, 112 and 128
bit boxes.

Unfortunately the FIPS terminology unnecessarily obfuscated the issue. It would
have been easier to just say in SP800-57 that SHA1 HMAC is 160 bits
of equivalent security instead of placing it in the :Security Strenght 128" row
of Table 3.

TLS 1.2 can use SHA1 in two different places. One is the signature algorithms on
certificates: i.e. the algorithm the CA signs with. The second place is
temporary key signature (server authentication) as described below.

==== Digital Signatures in TLS ====

There are three places digital signatures are used in TLS.

1. The signatures on certificates.

The certificates' signatures are set by the CA so to comply with new FIPS
whatever else you do you need a certificate chain that uses SHA256 at least.

2. Server Key Exchange.

The Server Key Exchange message contains a signature in any authenticated PFS
ciphersuite. The algorithm used depends on the version of TLS.

For TLS 1.1 and 1.0 the algorithm is either a MD5+SHA1 hybrid (RSA) or SHA1
(DSA, ECDSA). Both of these are prohibited by new FIPS so TLS 1.1 and 1.0
authenticated PFS ciphersuites are not allowed.

For TLS 1.2 any appropriate algorithm can be used to sign Server Key Exchange
messages. So PFS authenticated ciphersuites *are* allowed under new FIPS as long
as SHA1 is not used to sign Server Key Exchange. MD5 is of course a double no-no.

3. Certificate Verify.

The Certificate Verify message is used whenever client authentication is enabled
for any applicable ciphersuite (not just PFS). The same digest algorithms are
used as Server Key Exchange.

Therefore new FIPS and TLS 1.1 and 1.0 prohibits client authentication outright
in *any* ciphersuite.

TLS 1.2 is more flexible and can use any appropriate algorithm so client
authentication is permitted as long as SHA1 and MD5 are not used.

=== What about versions of OpenSSL prior to 1.0.1f? ===

The "TLSv1.2" ciphersuite designation was added at 1.0.1f. For earlier versions of
OpenSSL the current equivalent of the cipherstring
<pre>
'TLSv1.2:kRSA:!eNULL:!aNULL'
</pre>
can be "brute forced" as the unwieldy
<pre>
'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:DHE-DSS-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA256:ADH-AES256-GCM-SHA384:ADH-AES256-SHA256:ECDH-RSA-AES256-GCM-SHA384:ECDH-ECDSA-AES256-GCM-SHA384:ECDH-RSA-AES256-SHA384:ECDH-ECDSA-AES256-SHA384:AES256-GCM-SHA384:AES256-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:DHE-DSS-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256:DHE-DSS-AES128-SHA256:ADH-AES128-GCM-SHA256:ADH-AES128-SHA256:ECDH-RSA-AES128-GCM-SHA256:ECDH-ECDSA-AES128-GCM-SHA256:ECDH-RSA-AES128-SHA256:ECDH-ECDSA-AES128-SHA256:AES128-GCM-SHA256:AES128-SHA256:NULL-SHA256:kRSA:!eNULL:!aNULL'
</pre>
However, as new ciphersuites get added to the 'TLSv1.2' ciphersuite that brute force
equivalent might end up not being
equivalent any more.

Since TLSv1.2 only ciphers use SHA256, SHA384 and AES in GCM mode so one string is:
<pre>
'AESGCM:SHA384:SHA256'
</pre>
There are other ways to get the same effect. One is to disable any ciphers which
use SHA1. So "FIPS:-SHA" is currently equivalent to "FIPS+TLSv1.2". The use of
the "-SHA" is necessary here because it only *temporarily* disables SHA1 MACs.
That means you can do: "FIPS:-SHA:FIPS+kRSA" to add back the RSA key exchange
ciphersuites that use SHA1. Contrast that with using "!SHA" instead which permanently
removes SHA1 from the cipherstring.

[[Category:FIPS 140]]

Simple TLS Server

2022-11-08T13:16:02Z

Matt: Ignore broken pipe signals.

You may find an up to date example within repository demos/sslecho.

The code below is a complete implementation of a minimal TLS server. The first thing we do is create an ''SSL_CTX'' or SSL context. This is created using the ''TLS_server_method'' which creates a server that will negotiate the highest version of SSL/TLS supported by the client it is connecting to. The context is then configured by specifying the certificate and private key to use.

Next we perform some normal socket programming and create a new server socket, there's nothing OpenSSL specific about this code. Whenever we get a new connection we call ''accept'' as normal. To handle the TLS we create a new ''SSL'' structure, this holds the information related to this particular connection. We use ''SSL_set_fd'' to tell openssl the file descriptor to use for the communication. In this example, we call ''SSL_accept'' to handle the server side of the TLS handshake, then use ''SSL_write()'' to send our message. Finally we clean up the various structures.

<pre>

#include <stdio.h>
#include <unistd.h>
#include <string.h>
#include <signal.h>
#include <sys/socket.h>
#include <arpa/inet.h>
#include <openssl/ssl.h>
#include <openssl/err.h>

int create_socket(int port)
{
int s;
struct sockaddr_in addr;

addr.sin_family = AF_INET;
addr.sin_port = htons(port);
addr.sin_addr.s_addr = htonl(INADDR_ANY);

s = socket(AF_INET, SOCK_STREAM, 0);
if (s < 0) {
perror("Unable to create socket");
exit(EXIT_FAILURE);
}

if (bind(s, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
perror("Unable to bind");
exit(EXIT_FAILURE);
}

if (listen(s, 1) < 0) {
perror("Unable to listen");
exit(EXIT_FAILURE);
}

return s;
}

SSL_CTX *create_context()
{
const SSL_METHOD *method;
SSL_CTX *ctx;

method = TLS_server_method();

ctx = SSL_CTX_new(method);
if (!ctx) {
perror("Unable to create SSL context");
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}

return ctx;
}

void configure_context(SSL_CTX *ctx)
{
/* Set the key and cert */
if (SSL_CTX_use_certificate_file(ctx, "cert.pem", SSL_FILETYPE_PEM) <= 0) {
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}

if (SSL_CTX_use_PrivateKey_file(ctx, "key.pem", SSL_FILETYPE_PEM) <= 0 ) {
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}
}

int main(int argc, char **argv)
{
int sock;
SSL_CTX *ctx;

/* Ignore broken pipe signals */
signal(SIGPIPE, SIG_IGN);

ctx = create_context();

configure_context(ctx);

sock = create_socket(4433);

/* Handle connections */
while(1) {
struct sockaddr_in addr;
unsigned int len = sizeof(addr);
SSL *ssl;
const char reply[] = "test\n";

int client = accept(sock, (struct sockaddr*)&addr, &len);
if (client < 0) {
perror("Unable to accept");
exit(EXIT_FAILURE);
}

ssl = SSL_new(ctx);
SSL_set_fd(ssl, client);

if (SSL_accept(ssl) <= 0) {
ERR_print_errors_fp(stderr);
} else {
SSL_write(ssl, reply, strlen(reply));
}

SSL_shutdown(ssl);
SSL_free(ssl);
close(client);
}

close(sock);
SSL_CTX_free(ctx);
}

</pre>

== Session Reuse ==

According to Viktor Dukhovni at [http://mta.openssl.org/pipermail/openssl-users/2016-September/004564.html Possible to control session reuse from the client]:

<pre>> For performance testing purposes, I would like to turn off session
> reuse in the (homegrown) client I use for testing. Is there a function
> in the openssl library to do it?
>
> I tried googling for "openssl client don't send session id" but I didn't
> find anything useful.

Just do nothing. Client sessions are not reused unless you explicitly
arrange for reuse of a session by calling SSL_set_session() before
SSL_connect(). If you're trying to avoid wasting memory on storing
client-side sessions that you'll never reuse then this may help:

SSL_CTX_set_session_cache_mode(client_ctx, SSL_SESS_CACHE_OFF);

but note this is also the default state, so is also not needed unless
some other code has explicitly enabled client-side caching of sessions.

Only the server-side cache is enabled by default.</pre>

== 0-RTT ==

0-RTT is specified in XXX (TODO). 0-RTT allows an application to immediately resume a previous session at the expense of consuming unauthenticated data. You should avoid 0-RTT if possible. In fact, an organization's data security policy may not allow it for some higher data sensitivity levels.

Care should be taken if enabling 0-RTT at the server because a number of protections must be enabled. Additionally, some of the protections are required higher up in the stack, outside of the secure socket layer. Below is a list of potential problems from [http://www.ietf.org/mail-archive/web/tls/current/msg23561.html Closing on 0-RTT] on the IETF TLS working group mailing list.

* 0-RTT without stateful anti-replay allows for very high number of replays, breaking rate limiting systems, even high-performance ones, resulting in an opening for DDoS attacks.

* 0-RTT without stateful anti-replay allows for very high number of replays, allowing exploiting timing side channels for information leakage. Very few if any applications are engineered to mitigate or eliminate such side channels.

* 0-RTT without global anti-replay allows leaking information from the 0-RTT data via cache timing attacks. HTTP GET URLs sent to CDNs are especially vulnerable.

* 0-RTT without global anti-replay allows non-idempotent actions contained in 0-RTT data to be repeated potentially lots of times. Abuse of HTTP GET for non-idempotent actions is fairly common.

* 0-RTT allows easily reordering request with re-transmission from the client. This can lead to various unexpected application behavior if possibility of such reordering is not taken into account. "Eventually consistent" datastores are especially vulnerable.

* 0-RTT exporters are not safe for authentication unless the server does global anti-replay on 0-RTT.

[[Category:Examples]]
[[Category:C level]]

Binaries

2022-05-17T12:44:30Z

Matt: Highlight the fact that donations to 3rd parties doesn't come to us, and add details about how to donate to OpenSSL

Some people have offered to provide OpenSSL binary distributions for selected operating systems. The condition to get a link here is that the link is stable and can provide continued support for OpenSSL for a while.

Note: many Linux distributions come with pre-compiled OpenSSL packages. Those are already well-known among the users of said distributions, and will therefore not be mentioned here. If you are such a user, we ask you to get in touch with your distributor first. This service is primarily for operating systems where there are no pre-compiled OpenSSL packages.

'''Important Disclaimer''':
''The listing of these third party products does not imply any endorsement by the OpenSSL project, and these organizations are not affiliated in any way with OpenSSL other than by the reference to their independent web sites here.'' '''In particular any donations or payments to any of these organizations will not be known to, seen by, or in any way benefit the OpenSSL project.'''

'''To make a donation to the project directly go to our [https://github.com/sponsors/openssl github sponsors page]. Alternatively consider becoming a [https://www.openssl.org/support/donations.html corporate sponsor].'''

Use these OpenSSL derived products at your own risk; these products have not been evaluated or tested by the OpenSSL project.

{| class="wikitable sortable" border="1"
|+ Third Party OpenSSL Related Binary Distributions
|-
! scope="col" | Product
! scope="col" | Description
! scope="col" | URL
|-
| OpenSSL for Windows
| Works with MSVC++, Builder 3/4/5, and MinGW. Comes in form of self-install executables.
| https://slproweb.com/products/Win32OpenSSL.html
|-
|-
| OpenSSL for Windows
| Pre-compiled Win32/64 libraries without external dependencies to the Microsoft Visual Studio Runtime DLLs, except for the system provided msvcrt.dll.
| https://indy.fulgan.com/SSL/
|-
|-
| OpenSSL for Windows
| Reproducible builds with latest MinGW-w64, 64/32-bit, static/dynamic libs and executable.
| https://github.com/curl/curl-for-win
|-
|-
| OpenSSL for Solaris
| Versions for Solaris 2.5 - 11 SPARC and X86
| http://www.unixpackages.com/
|-
|-
| OpensSSL for Windows, Linux, OSX, Android
| Pre-compiled packages at conan.io package manager: ''Windows'' x86/x86_64 (Visual Studio 10, 12, 14, 15) ''Linux'' x86/x86_64 (gcc 4.6, 4.8, 4.9, 5, 6, 7) ''OSx'' (Apple clang). Cross-building ready recipe: Linux ARM, Android.
| https://www.conan.io https://conan.io/center/openssl
|-
|-
| OpenSSL for Windows
| Pre-compiled Win32/64 1.0.2, 1.1.0, 1.1.1 and 3.0 libraries without external dependencies, primarily built for François Piette's Internet Component Suite (ICS) for Embarcadero (Borland) Delphi and C++ development tools, but may be used for any Windows applications. The OpenSSL DLLs and EXE files are digitally code signed 'Open Source Developer, François PIETTE', so applications can self verify them for corruption.
| http://wiki.overbyte.eu/wiki/index.php/ICS_Download
|-
|-
| OpenSSL for Windows
| Pre-compiled 64-bit (x64) and 32-bit (x86) 1.1.1 and 3.0 executables and libraries for Microsoft Windows Operating Systems with a dependency on the Microsoft Visual Studio 2015-2019 runtime and Microsoft Visual Studio 2015-2022 runtime respectively. The distribution may be used standalone or integrated into any Windows application. The distribution's EXE and DLL files are digitally signed 'FireDaemon Technologies Limited'.
| [https://kb.firedaemon.com/support/solutions/articles/4000121705 https://kb.firedaemon.com/support/solutions/articles/4000121705]
|-
|-
| OpenSSL for NonStop
| Pre-compiled NonStop ia64/x86 1.0.2, 1.1.1 executables and libraries for the HPE NonStop Operating Systems. Threaded versions are included. The SPT version depends on FLOSS, otherwise there are no other dependencies. 32-bit versions are available. The builds are done by the ITUGLIB Technical Committee as part of Connect.
| [https://ituglib.connect-community.org/apps/Ituglib/SrchOpenSrcLib.xhtml https://ituglib.connect-community.org/apps/Ituglib/SrchOpenSrcLib.xhtml]
|-
|-
|}

=Engines=

Some third parties provide OpenSSL compatible engines. As for the binaries above the following disclaimer applies:

'''Important Disclaimer''':
''The listing of these third party products does not imply any endorsement by the OpenSSL project, and these organizations are not affiliated in any way with OpenSSL other than by the reference to their independent web sites here. In particular any donations or payments to any of these organizations will not be known to, seen by, or in any way benefit the OpenSSL project.''

{| class="wikitable sortable" border="1"
|+ Third Party OpenSSL compatible engines
|-
! scope="col" | Product
! scope="col" | Description
! scope="col" | URL
|-
|-
| Intel® QuickAssist Technology engine
| Intel® QuickAssist Technology (http://www.intel.com/content/www/us/en/embedded/technology/quickassist/overview.html) provides acceleration for a number of cryptographic algorithms. QAT_engine adds support for Intel® QuickAssist Technology to OpenSSL-1.1.0 via the ENGINE framework. The definitive list of algorithms exposed into OpenSSL (a subset of those supported in the device) is defined on the associated github page.
| https://github.com/01org/QAT_Engine
|-
| ATECCX08 engine
| Support for the Atmel ATECC508A (http://www.atmel.com/devices/ATECC508A.aspx) hardware to provide secure key storage, ECC cryptographic calculations for the ECC NIST P-256 curve, and FIPS certified hardware Random Number Generator.
| https://github.com/AtmelCSO/cryptoauth-openssl-engine
|-
|-
| GOST engine
| A reference implementation of the Russian GOST crypto algorithms for OpenSSL. The presence of this engine also enables the built-in OpenSSL support for GOST TLS ciphersuites. (Note: this engine is for OpenSSL version 1.1.0 and above. Previous versions of OpenSSL used a built-in GOST engine)
| https://github.com/gost-engine/engine
|-
|-
| ISARA Radiate Solution Suite OpenSSL Connector
| Commercially available engine and source code patch for OpenSSL 1.0.2 branch. The ISARA Radiate OpenSSL Connector lets you implement OpenSSL using quantum safe algorithms. ISARA Radiate (https://www.isara.com/isara-radiate/) gives you the cryptographic building blocks to create applications that will resist attacks by quantum computers.
| https://www.isara.com/openssl/1/
|-
|-
| BEE2EVP engine
| Implements the Belarusian national cryptography: symmetric and public-key encryption, MAC, AEAD, hashing, digital signature. Encapsulates the Bee2 core cryptographic library into OpenSSL using the EVP interface.
| https://github.com/bcrypto/bee2evp
|-
|-
| wolfSSL wolfEngine
| wolfSSL has an OpenSSL engine, wolfEngine. wolfEngine is structured as a separate standalone library which links against wolfSSL (libwolfssl) and OpenSSL. wolfEngine implements and exposes an OpenSSL engine implementation which wraps the wolfCrypt native API internally. Algorithm support matches that as listed on the wolfCrypt FIPS 140-2 certificate #3389.
| https://github.com/wolfSSL/wolfEngine
|-
|-
| wolfSSL wolfProvider
| Similar to the wolfEngine above, the wolfSSL team has also created the wolfProvider. The wolfProvider is structured as a separate standalone library which links against wolfSSL (libwolfssl) and OpenSSL 3.0.0 using the new provider API. Algorithm support matches that as listed on the wolfCrypt FIPS 140-2 certificate #3389.
| https://github.com/wolfSSL/wolfProvider
|-
|-
|}

TLS1.3

2022-03-28T13:46:31Z

Matt: /* Differences with TLS1.2 and below */ typo fix

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECDHE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

Applications should use the SSL_CTX_set_ciphersuites() or SSL_set_ciphersuites() functions to configure TLSv1.3 ciphersuites. Note that the functions SSL_CTX_get_ciphers() and SSL_get_ciphers() will return
the full list of ciphersuites that have been configured for both TLSv1.2 and below and TLSv1.3.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/manmaster/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the [https://www.openssl.org/docs/manmaster/man3/SSL_get1_session.html SSL_get1_session()] function (or similar).

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_remove_session.html SSL_CTX_remove_session()] to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session(). Calling SSL_get1_session() after a 2 way shutdown will give a resumable session if any was sent. You can check that a session is resumable with [https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html SSL_SESSION_is_resumable()].

Client application developers should consider using the [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html SSL_CTX_sess_set_new_cb()] API instead. This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. The number of tickets can be set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html SSL_CTX_set_num_tickets]. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

If a client sends it's data and directly sends the close notify request and closes the connection, the server will still try to send tickets if configured to do so. Since the connection is already closed by the client, this might result in a write error and receiving the SIGPIPE signal. The write error will be ignored if it's a session ticket. But server applications can still get SIGPIPE they didn't get before.

If the server sends session tickets and you want to be able to get a resumable session, you need to either call SSL_read() after the ticket was sent or do a 2 way shutdown.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/manmaster/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket and possibly a key update is send after the finished message. With TLSv1.2 it happened in case of renegotiation. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

Simple TLS Server

2021-11-11T09:55:12Z

Matt: Update the demo TLS server code for currently supported versions of OpenSSL. Remove some old stuff that is no longer relevant with current versions of OpenSSL.

The code below is a complete implementation of a minimal TLS server. The first thing we do is create an ''SSL_CTX'' or SSL context. This is created using the ''TLS_server_method'' which creates a server that will negotiate the highest version of SSL/TLS supported by the client it is connecting to. The context is then configured by specifying the certificate and private key to use.

Next we perform some normal socket programming and create a new server socket, there's nothing OpenSSL specific about this code. Whenever we get a new connection we call ''accept'' as normal. To handle the TLS we create a new ''SSL'' structure, this holds the information related to this particular connection. We use ''SSL_set_fd'' to tell openssl the file descriptor to use for the communication. In this example, we call ''SSL_accept'' to handle the server side of the TLS handshake, then use ''SSL_write()'' to send our message. Finally we clean up the various structures.

<pre>

#include <stdio.h>
#include <unistd.h>
#include <string.h>
#include <sys/socket.h>
#include <arpa/inet.h>
#include <openssl/ssl.h>
#include <openssl/err.h>

int create_socket(int port)
{
int s;
struct sockaddr_in addr;

addr.sin_family = AF_INET;
addr.sin_port = htons(port);
addr.sin_addr.s_addr = htonl(INADDR_ANY);

s = socket(AF_INET, SOCK_STREAM, 0);
if (s < 0) {
perror("Unable to create socket");
exit(EXIT_FAILURE);
}

if (bind(s, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
perror("Unable to bind");
exit(EXIT_FAILURE);
}

if (listen(s, 1) < 0) {
perror("Unable to listen");
exit(EXIT_FAILURE);
}

return s;
}

SSL_CTX *create_context()
{
const SSL_METHOD *method;
SSL_CTX *ctx;

method = TLS_server_method();

ctx = SSL_CTX_new(method);
if (!ctx) {
perror("Unable to create SSL context");
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}

return ctx;
}

void configure_context(SSL_CTX *ctx)
{
/* Set the key and cert */
if (SSL_CTX_use_certificate_file(ctx, "cert.pem", SSL_FILETYPE_PEM) <= 0) {
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}

if (SSL_CTX_use_PrivateKey_file(ctx, "key.pem", SSL_FILETYPE_PEM) <= 0 ) {
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}
}

int main(int argc, char **argv)
{
int sock;
SSL_CTX *ctx;

ctx = create_context();

configure_context(ctx);

sock = create_socket(4433);

/* Handle connections */
while(1) {
struct sockaddr_in addr;
unsigned int len = sizeof(addr);
SSL *ssl;
const char reply[] = "test\n";

int client = accept(sock, (struct sockaddr*)&addr, &len);
if (client < 0) {
perror("Unable to accept");
exit(EXIT_FAILURE);
}

ssl = SSL_new(ctx);
SSL_set_fd(ssl, client);

if (SSL_accept(ssl) <= 0) {
ERR_print_errors_fp(stderr);
} else {
SSL_write(ssl, reply, strlen(reply));
}

SSL_shutdown(ssl);
SSL_free(ssl);
close(client);
}

close(sock);
SSL_CTX_free(ctx);
}

</pre>

== Session Reuse ==

According to Viktor Dukhovni at [http://mta.openssl.org/pipermail/openssl-users/2016-September/004564.html Possible to control session reuse from the client]:

<pre>> For performance testing purposes, I would like to turn off session
> reuse in the (homegrown) client I use for testing. Is there a function
> in the openssl library to do it?
>
> I tried googling for "openssl client don't send session id" but I didn't
> find anything useful.

Just do nothing. Client sessions are not reused unless you explicitly
arrange for reuse of a session by calling SSL_set_session() before
SSL_connect(). If you're trying to avoid wasting memory on storing
client-side sessions that you'll never reuse then this may help:

SSL_CTX_set_session_cache_mode(client_ctx, SSL_SESS_CACHE_OFF);

but note this is also the default state, so is also not needed unless
some other code has explicitly enabled client-side caching of sessions.

Only the server-side cache is enabled by default.</pre>

== 0-RTT ==

0-RTT is specified in XXX (TODO). 0-RTT allows an application to immediately resume a previous session at the expense of consuming unauthenticated data. You should avoid 0-RTT if possible. In fact, an organization's data security policy may not allow it for some higher data sensitivity levels.

Care should be taken if enabling 0-RTT at the server because a number of protections must be enabled. Additionally, some of the protections are required higher up in the stack, outside of the secure socket layer. Below is a list of potential problems from [http://www.ietf.org/mail-archive/web/tls/current/msg23561.html Closing on 0-RTT] on the IETF TLS working group mailing list.

* 0-RTT without stateful anti-replay allows for very high number of replays, breaking rate limiting systems, even high-performance ones, resulting in an opening for DDoS attacks.

* 0-RTT without stateful anti-replay allows for very high number of replays, allowing exploiting timing side channels for information leakage. Very few if any applications are engineered to mitigate or eliminate such side channels.

* 0-RTT without global anti-replay allows leaking information from the 0-RTT data via cache timing attacks. HTTP GET URLs sent to CDNs are especially vulnerable.

* 0-RTT without global anti-replay allows non-idempotent actions contained in 0-RTT data to be repeated potentially lots of times. Abuse of HTTP GET for non-idempotent actions is fairly common.

* 0-RTT allows easily reordering request with re-transmission from the client. This can lead to various unexpected application behavior if possibility of such reordering is not taken into account. "Eventually consistent" datastores are especially vulnerable.

* 0-RTT exporters are not safe for authentication unless the server does global anti-replay on 0-RTT.

[[Category:Examples]]
[[Category:C level]]

OpenSSL 3.0

2021-09-20T12:36:15Z

Matt:

__NUMBEREDHEADINGS__ 

'''READ ME FIRST:'''

This page is no longer being maintained. Refer instead to the OpenSSL 3.0 [https://www.openssl.org/docs/man3.0/man7/migration_guide.html migration guide] for the most up to date information.

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 ==

Starting with OpenSSL 3.0.0 alpha16, no separate installation step for the FIPS module (a.k.a FIPS provider) is necessary anymore. It will be built and installed automatically if FIPS support has been configured. The current documentation can be found in the [https://github.com/openssl/openssl/blob/master/README-FIPS.md README-FIPS] file on the master branch.

''The documentation in the remaining section applies to alpha versions up to OpenSSL 3.0.0 alpha15.''

Once OpenSSL has been built and installed you will need to take explicit steps to complete the installation of the FIPS module (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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 can 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.cnf file to remove or comment out the line which says "activate = 1" (note that setting this value to 0 is not sufficient). 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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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. The local property query overrides the default properties if the same property name is specified in both.

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 and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 and the default library context 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_ex(). 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 the same function to specify libssl specific properties to use.

In this first example we create two SSL_CTX objects 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_ex(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_ex(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 encoders 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_ex(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_ex(NULL, "provider!=fips", TLS_method());

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithms. Here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

=== 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 encoders 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
|}

Binaries

2021-08-24T10:03:56Z

Matt:

Some people have offered to provide OpenSSL binary distributions for selected operating systems. The condition to get a link here is that the link is stable and can provide continued support for OpenSSL for a while.

Note: many Linux distributions come with pre-compiled OpenSSL packages. Those are already well-known among the users of said distributions, and will therefore not be mentioned here. If you are such a user, we ask you to get in touch with your distributor first. This service is primarily for operating systems where there are no pre-compiled OpenSSL packages.

'''Important Disclaimer''':
''The listing of these third party products does not imply any endorsement by the OpenSSL project, and these organizations are not affiliated in any way with OpenSSL other than by the reference to their independent web sites here. In particular any donations or payments to any of these organizations will not be known to, seen by, or in any way benefit the OpenSSL project.''

Use these OpenSSL derived products at your own risk; these products have not been evaluated or tested by the OpenSSL project.

{| class="wikitable sortable" border="1"
|+ Third Party OpenSSL Related Binary Distributions
|-
! scope="col" | Product
! scope="col" | Description
! scope="col" | URL
|-
| OpenSSL for Windows
| Works with MSVC++, Builder 3/4/5, and MinGW. Comes in form of self-install executables.
| https://slproweb.com/products/Win32OpenSSL.html
|-
|-
| OpenSSL for Windows
| Pre-compiled Win32/64 libraries without external dependencies to the Microsoft Visual Studio Runtime DLLs, except for the system provided msvcrt.dll.
| https://indy.fulgan.com/SSL/
|-
|-
| OpenSSL for Windows
| Reproducible builds with latest MinGW-w64, 64/32-bit, static/dynamic libs and executable.
| https://github.com/curl/curl-for-win
|-
|-
| OpenSSL for Solaris
| Versions for Solaris 2.5 - 11 SPARC and X86
| http://www.unixpackages.com/
|-
|-
| OpensSSL for Windows, Linux, OSX, Android
| Pre-compiled packages at conan.io package manager: ''Windows'' x86/x86_64 (Visual Studio 10, 12, 14, 15) ''Linux'' x86/x86_64 (gcc 4.6, 4.8, 4.9, 5, 6, 7) ''OSx'' (Apple clang). Cross-building ready recipe: Linux ARM, Android.
| https://www.conan.io https://conan.io/center/openssl
|-
|-
| OpenSSL for Windows
| Pre-compiled Win32/64 1.0.2, 1.1.0 and 1.1.1 libraries without external dependencies, primarily built for François Piette's Internet Component Suite (ICS) for Embarcadero (Borland) Delphi and C++ development tools, but may be used for any Windows applications. The OpenSSL DLLs and EXE files are digitally code signed 'Open Source Developer, François PIETTE', so applications can self verify them for corruption.
| http://wiki.overbyte.eu/wiki/index.php/ICS_Download
|-
|-
| OpenSSL for Windows
| Pre-compiled 64-bit (x64) and 32-bit (x86) 1.1.1 executables and libraries for Microsoft Windows Operating Systems with a dependency on the Microsoft Visual Studio 2015-2019 runtime. The distribution may be used standalone or integrated into any Windows application. The distribution's EXE and DLL files are digitally signed 'FireDaemon Technologies Limited'.
| [https://kb.firedaemon.com/support/solutions/articles/4000121705 https://kb.firedaemon.com/support/solutions/articles/4000121705]
|-
|-
| OpenSSL for NonStop
| Pre-compiled NonStop ia64/x86 1.0.2, 1.1.1 executables and libraries for the HPE NonStop Operating Systems. Threaded versions are included. The SPT version depends on FLOSS, otherwise there are no other dependencies. 32-bit versions are available. The builds are done by the ITUGLIB Technical Committee as part of Connect.
| [https://ituglib.connect-community.org/apps/Ituglib/SrchOpenSrcLib.xhtml https://ituglib.connect-community.org/apps/Ituglib/SrchOpenSrcLib.xhtml]
|-
|-
|}

=Engines=

Some third parties provide OpenSSL compatible engines. As for the binaries above the following disclaimer applies:

'''Important Disclaimer''':
''The listing of these third party products does not imply any endorsement by the OpenSSL project, and these organizations are not affiliated in any way with OpenSSL other than by the reference to their independent web sites here. In particular any donations or payments to any of these organizations will not be known to, seen by, or in any way benefit the OpenSSL project.''

{| class="wikitable sortable" border="1"
|+ Third Party OpenSSL compatible engines
|-
! scope="col" | Product
! scope="col" | Description
! scope="col" | URL
|-
|-
| Intel® QuickAssist Technology engine
| Intel® QuickAssist Technology (http://www.intel.com/content/www/us/en/embedded/technology/quickassist/overview.html) provides acceleration for a number of cryptographic algorithms. QAT_engine adds support for Intel® QuickAssist Technology to OpenSSL-1.1.0 via the ENGINE framework. The definitive list of algorithms exposed into OpenSSL (a subset of those supported in the device) is defined on the associated github page.
| https://github.com/01org/QAT_Engine
|-
| ATECCX08 engine
| Support for the Atmel ATECC508A (http://www.atmel.com/devices/ATECC508A.aspx) hardware to provide secure key storage, ECC cryptographic calculations for the ECC NIST P-256 curve, and FIPS certified hardware Random Number Generator.
| https://github.com/AtmelCSO/cryptoauth-openssl-engine
|-
|-
| GOST engine
| A reference implementation of the Russian GOST crypto algorithms for OpenSSL. The presence of this engine also enables the built-in OpenSSL support for GOST TLS ciphersuites. (Note: this engine is for OpenSSL version 1.1.0 and above. Previous versions of OpenSSL used a built-in GOST engine)
| https://github.com/gost-engine/engine
|-
|-
| ISARA Radiate Solution Suite OpenSSL Connector
| Commercially available engine and source code patch for OpenSSL 1.0.2 branch. The ISARA Radiate OpenSSL Connector lets you implement OpenSSL using quantum safe algorithms. ISARA Radiate (https://www.isara.com/isara-radiate/) gives you the cryptographic building blocks to create applications that will resist attacks by quantum computers.
| https://www.isara.com/openssl/1/
|-
|-
| BEE2EVP engine
| Implements the Belarusian national cryptography: symmetric and public-key encryption, MAC, AEAD, hashing, digital signature. Encapsulates the Bee2 core cryptographic library into OpenSSL using the EVP interface.
| https://github.com/bcrypto/bee2evp
|-
|-
|}

OpenSSL 3.0

2021-03-18T12:08:12Z

Matt: /* Loading the FIPS module at the same time as other providers */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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 can 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.cnf file to remove or comment out the line which says "activate = 1" (note that setting this value to 0 is not sufficient). 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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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. The local property query overrides the default properties if the same property name is specified in both.

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 and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 and the default library context 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_ex(). 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 the same function to specify libssl specific properties to use.

In this first example we create two SSL_CTX objects 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_ex(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_ex(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 encoders 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_ex(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_ex(NULL, "provider!=fips", TLS_method());

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithms. Here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

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

2021-03-17T10:39:30Z

Matt: /* Using the FIPS module in SSL/TLS */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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 can 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.cnf file to remove or comment out the line which says "activate = 1" (note that setting this value to 0 is not sufficient). 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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 and the default library context 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_ex(). 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 the same function to specify libssl specific properties to use.

In this first example we create two SSL_CTX objects 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_ex(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_ex(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 encoders 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_ex(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_ex(NULL, "provider!=fips", TLS_method());

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithms. Here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

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

2021-03-17T10:38:23Z

Matt: /* Making all applications use the FIPS module by default */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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 can 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.cnf file to remove or comment out the line which says "activate = 1" (note that setting this value to 0 is not sufficient). 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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 and the default library context 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_ex(). 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 objects 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_ex(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_ex(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 encoders 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_ex(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_ex(NULL, "provider!=fips", TLS_method());

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithms. Here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

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

2021-03-16T15:29:00Z

Matt: /* Confirming that an algorithm is being provided by the FIPS module */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.cnf file to remove or comment out the line which says "activate = 1" (note that setting this value to 0 is not sufficient). 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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 and the default library context 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_ex(). 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 objects 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_ex(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_ex(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 encoders 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_ex(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_ex(NULL, "provider!=fips", TLS_method());

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithms. Here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

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

2021-03-16T15:21:56Z

Matt: /* Programmatically loading the FIPS module (default library context) */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.cnf file to remove or comment out the line which says "activate = 1" (note that setting this value to 0 is not sufficient). 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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 and the default library context 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_ex(). 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 objects 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_ex(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_ex(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 encoders 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_ex(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_ex(NULL, "provider!=fips", TLS_method());

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

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

2021-03-16T15:12:24Z

Matt: /* Using the FIPS module in SSL/TLS */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 and the default library context 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_ex(). 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 objects 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_ex(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_ex(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 encoders 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_ex(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_ex(NULL, "provider!=fips", TLS_method());

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

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

2021-03-16T15:08:00Z

Matt: /* Using the FIPS module in SSL/TLS */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 and the default library context 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 objects 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 encoders 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

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

2021-03-16T15:06:09Z

Matt: Rename serializers/deserializers to encoders/decoders

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to encode and decode keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 Encoders and Decoders with the FIPS module ===

Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). 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 encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. 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 encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoder and decoder are implemented in both the default and base providers 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 encoder/decoder have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 encoders 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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_ENCODER || 100% || 100%
|-
| OSSL_DECODER || 100% || 100%
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 encoder / decoder ====

===== Encoders =====

{| class="wikitable"
! Encoder !! 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 || 100% || ??
|-
| 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% || ??
|}

===== Decoders =====

TO BE ADDED

{| class="wikitable"
! Decoder !! 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 decoders
|}

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

2021-03-16T14:46:32Z

Matt: /* Using the FIPS Module in applications */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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

2021-03-16T14:46:14Z

Matt: /* Using the FIPS Module in applications */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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

2021-03-16T14:45:56Z

Matt: /* Using the FIPS Module in applications */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

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 high level APIs, such as EVP, instead)
- 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
avoid using all deprecated functions.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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

2021-03-16T14:37:17Z

Matt: Add warning about deprecated APIs

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you use them.

Some deprecated APIs avoid the usage of the FIPS module. It is recommended that applications needing to use the FIPS module should not use any deprecated APIs in order to avoid this problem.

=== 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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

2021-03-16T14:34:26Z

Matt: Add the word "deprecated" to the phrase about avoiding use of the FIPS module

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 deprecated 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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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
|}

Diffie Hellman

2021-02-13T14:34:57Z

Matt: /* Working with Parameters and Generating Keys */

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_assign(params, EVP_PKEY_DHX, 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();

/* Optional : useful if you want to check your private key*/
BIO* fp = BIO_new_fp(stdout, BIO_NOCLOSE);
EVP_PKEY_print_private(fp, dhkey, 0, NULL);

</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]]

Diffie Hellman

2021-02-13T14:29:39Z

Matt: Undo revision 3139 by L.Habib (talk)

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();

/* Optional : useful if you want to check your private key*/
BIO* fp = BIO_new_fp(stdout, BIO_NOCLOSE);
EVP_PKEY_print_private(fp, dhkey, 0, NULL);

</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

2021-01-07T16:43:25Z

Matt: /* Loading the FIPS module at the same time as other providers */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

openssl_conf = openssl_init

.include /usr/local/ssl/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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

2021-01-07T16:41:36Z

Matt: /* Making all applications use the FIPS module by default */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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

2021-01-07T16:41:22Z

Matt: /* Making all applications use the FIPS module by default */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.cnf

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

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. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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
|}

Library Initialization

2020-10-16T14:30:41Z

Matt: Correct OPENSSL_init_crypto line

This page discusses OpenSSL library initialization when using the <tt>libssl</tt> and <tt>libcrypto</tt> components.

There are two ways to initialize the OpenSSL library, and they depend on the version of the library you are using. If you are using OpenSSL 1.0.2 or below, then you would use <tt>SSL_library_init</tt>. If you are using OpenSSL 1.1.0 or above, then the library will initialize itself automatically. Optionally you can explicitly initialise it using <tt>OPENSSL_init_ssl</tt> or <tt>OPENSSL_init_crypto</tt>. A compatibility macro exists in <tt>ssl.h</tt> that maps <tt>SSL_library_init</tt> to <tt>OPENSSL_init_ssl</tt>, so you can continue to use <tt>SSL_library_init</tt> if desired. Also see ''[http://mta.openssl.org/pipermail/openssl-dev/2016-February/005491.html SSL_library_init]'' on the OpenSSL-dev mailing list.

The rest of this page discusses initializing the library in 1.0.2. If you are using 1.1.0 or above then you don't need to take any further steps.

If you fail to initialize the library in 1.0.2, then you will experience unexplained errors like <tt>SSL_CTX_new</tt> returning <tt>NULL</tt>, error messages like <tt>SSL_CTX_new:library has no ciphers</tt> and <tt>alert handshake failure</tt> with no shared ciphers.

Below is a list of some initialization calls you might encounter in code or documentation. Unfortunately, all the initialization function return a useless values (for example, always 1) or are void functions. There is no way to determine if a failure occurred.

* SSL_library_init
* OpenSSL_add_ssl_algorithms
* OpenSSL_add_all_algorithms
* SSL_load_error_strings
* ERR_load_crypto_strings
 

== libssl Initialization ==

<tt>libssl</tt> should be initialized with calls to <tt>SSL_library_init</tt> and <tt>SSL_load_error_strings</tt>. If your program is multi-threaded, you should install the static locks. If you need (or don't need) configuration from <tt>openssl.cnf</tt>, then you should call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt>.

If you are supporting both pre-1.1.0 and post-1.1.0 version of the OpenSSL library and you want to take control of <tt>SSL_library_init</tt> and <tt>OPENSSL_init_ssl</tt>, then you can perform:

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

#if OPENSSL_VERSION_NUMBER < 0x10100000L
SSL_library_init();
#else
OPENSSL_init_ssl(0, NULL);
#endif</pre>

When you call <tt>libssl</tt>, the function will also initialize <tt>libcrypto</tt> components. There are two corner cases discussed in later sections. The first corner case is static locks, and second is <tt>OPENSSL_config</tt>.

<tt>OpenSSL_add_ssl_algorithms</tt> is a <tt>#define</tt> for <tt>SSL_library_init</tt>. You only need to call one or the other. If you want to print error strings using OpenSSL's built in functions, then call <tt>SSL_load_error_strings</tt>.

The <tt>SSL_library_init</tt> function loads the algorithms use by <tt>libssl</tt>. Below is an excerpt from <tt>ssl_algs.c</tt> (with some additional formatting for clarity).

<pre>int SSL_library_init(void)
{

#ifndef OPENSSL_NO_DES
EVP_add_cipher(EVP_des_cbc());
EVP_add_cipher(EVP_des_ede3_cbc());
#endif
#ifndef OPENSSL_NO_IDEA
EVP_add_cipher(EVP_idea_cbc());
#endif
...

#ifndef OPENSSL_NO_COMP
(void)SSL_COMP_get_compression_methods();
#endif

...

/* initialize cipher/digest methods table */
ssl_load_ciphers();

return(1);
}</pre>

The call to <tt>ssl_load_ciphers</tt> simply builds a table for use in the library. The following is from <tt>ssl_ciph.c</tt> (with some additional formatting for clarity).

<pre>void ssl_load_ciphers(void)
{
ssl_cipher_methods[SSL_ENC_DES_IDX] = EVP_get_cipherbyname(SN_des_cbc);
ssl_cipher_methods[SSL_ENC_3DES_IDX] = EVP_get_cipherbyname(SN_des_ede3_cbc);
...
ssl_digest_methods[SSL_MD_MD5_IDX] = EVP_get_digestbyname(SN_md5);
ssl_mac_secret_size[SSL_MD_MD5_IDX] = EVP_MD_size(ssl_digest_methods[SSL_MD_MD5_IDX]);
...
ssl_digest_methods[SSL_MD_SHA384_IDX] = EVP_get_digestbyname(SN_sha384);
ssl_mac_secret_size[SSL_MD_SHA384_IDX] = EVP_MD_size(ssl_digest_methods[SSL_MD_SHA384_IDX]);
...
}</pre>

=== Library Apps ===

The following examines how the OpenSSL development team uses initialization in the OpenSSL utilities.

<tt>s_client</tt> initializes itself with the following calls:
* OpenSSL_add_ssl_algorithms
* SSL_load_error_strings

<tt>s_server</tt> initializes itself with the following calls:
* SSL_load_error_strings();
* OpenSSL_add_ssl_algorithms();

<tt>s_time</tt> initializes itself with the following calls:
* OpenSSL_add_ssl_algorithms();

<tt>state_machine</tt> initializes itself with the following calls:
* SSL_library_init();
* OpenSSL_add_ssl_algorithms();
* SSL_load_error_strings();
* ERR_load_crypto_strings();

== libcrypto Initialization ==

<tt>libcrypto</tt> should be initialized with calls to <tt>OpenSSL_add_all_algorithms</tt> and <tt>ERR_load_crypto_strings</tt>. If your program is multi-threaded, you should install the static locks. If you need (or don't need) configuration from <tt>openssl.cnf</tt>, then you should call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt>.

The <tt>OPENSSL_add_all_algorithms</tt> function is <tt>#define</tt>'d to either <tt>OPENSSL_add_all_algorithms_conf</tt> or <tt>OPENSSL_add_all_algorithms_noconf</tt> depending upon the value of <tt>OPENSSL_LOAD_CONF</tt>. A typical installation does ''not'' define <tt>OPENSSL_LOAD_CONF</tt>, which means <tt>OPENSSL_add_all_algorithms_noconf</tt> is used. Below is an excerpt from <tt>c_all.c</tt> (with some additional formatting for clarity).

<pre>void OPENSSL_add_all_algorithms_noconf(void)
{
/*
* For the moment OPENSSL_cpuid_setup does something
* only on IA-32, but we reserve the option for all
* platforms...
*/
OPENSSL_cpuid_setup();
OpenSSL_add_all_ciphers();
OpenSSL_add_all_digests();
...
}</pre>

<tt>OpenSSL_add_all_ciphers</tt> looks a lot like <tt>SSL_library_init</tt> from the <tt>libssl</tt> initialization routines (sans the call to <tt>ssl_load_ciphers</tt>). Below is an excerpt from <tt>c_allc.c</tt> (with some additional formatting for clarity).

<pre>void OpenSSL_add_all_ciphers(void)
{

#ifndef OPENSSL_NO_DES
EVP_add_cipher(EVP_des_cfb());
EVP_add_cipher(EVP_des_cfb1());
EVP_add_cipher(EVP_des_cfb8());
EVP_add_cipher(EVP_des_ede_cfb());
EVP_add_cipher(EVP_des_ede3_cfb());
EVP_add_cipher(EVP_des_ede3_cfb1());
EVP_add_cipher(EVP_des_ede3_cfb8());
...
#endif

#ifndef OPENSSL_NO_RC4
EVP_add_cipher(EVP_rc4());
EVP_add_cipher(EVP_rc4_40());
# ifndef OPENSSL_NO_MD5
EVP_add_cipher(EVP_rc4_hmac_md5());
# endif
#endif

...

/* Note: there is no call to ssl_load_ciphers() here */
}</pre>

Finally, [http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html <tt>OpenSSL_add_all_algorithms(3)</tt>] offers the following advice:

<blockquote>Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a statically linked executable can be quite large. If this is important it is possible to just add the required ciphers and digests.</blockquote>

If you want the small footprint, then call <tt>EVP_add_cipher</tt> with the ciphers and algorithms you need (and nothing more).

=== Library Apps ===

The following examines how the OpenSSL development team uses initialization in the OpenSSL utilities.

<tt>enc</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();

<tt>dec</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();

<tt>pkcs8</tt> initializes itself with the following calls:
* ERR_load_crypto_strings();
* OpenSSL_add_all_algorithms();

<tt>cms_sign</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();
* ERR_load_crypto_strings();

<tt>cms_ver</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();
* ERR_load_crypto_strings();

== OpenSSL_config ==

If you are supporting early and late versions of the library and need to call <tt>OpenSSL_config</tt> or <tt>OPENSSL_init_crypto</tt>, then the following is roughly equivalent.

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

#if OPENSSL_VERSION_NUMBER < 0x10001000L
OPENSSL_config(NULL);
#else
OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL);
#endif</pre>

== ENGINEs and RDRAND ==

A call to <tt>ENGINE_load_builtin_engines</tt> loads all built-in engines, including those for <tt>AES_NI</tt> instructions and <tt>RDRAND</tt>. After the call, OpenSSL will use the engines for AES encryption and random number generation, if available. In this case, <tt>RDRAND</tt> will be the only source of random numbers.

If you are concerned over possible <tt>RDRAND</tt> tampering, then you should explicitly call <tt>RAND_set_rand_engine(NULL)</tt> after loading all engines. If another module in the program happens to call <tt>ENGINE_load_builtin_engines</tt> again, then you will go back to using <tt>RDRAND</tt>.

You can also call <tt>ENGINE_unregister_RAND</tt> followed by <tt>ENGINE_register_all_complete</tt> to unregister <tt>RDRAND</tt> as default random number generator implementation.

To avoid accidental use of <tt>RDRAND</tt>, you can build OpenSSL with <tt>OPENSSL_NO_RDRAND</tt> defined. This is the preferred method to avoid all use of <tt>RDRAND</tt>.

Future version of the library will change the default behavior. That is, in the future, you will have to explicitly call <tt>ENGINE_load_rdrand</tt> if you want to use <tt>RDRAND</tt>. The change has been checked in, but its only available through <tt>git</tt> at the moment.

For the full discussion, see coderman's ''[http://seclists.org/fulldisclosure/2013/Dec/99 RDRAND used directly when default engines loaded in openssl-1.0.1-beta1 through openssl-1.0.1e]''.

== Static Locks ==

If your program is multi-threaded, then you will need to install the static locks. The static locks are used for extensively for <tt>libssl</tt>, and used in the random number generator for <tt>libcrypto</tt>. The locks should be installed '''''after''''' the calling:

* SSL_library_init
* OpenSSL_add_ssl_algorithms
* OpenSSL_add_all_algorithms
* SSL_load_error_strings
* ERR_load_crypto_strings

See [http://stackoverflow.com/a/42856544/608639 Multithreaded program using OpenSSL and locks randomly crashes] on Stack Overflow and [http://www.openssl.org/docs/crypto/threads.html threads(3)] for details until the wiki is updated with an example.

== OPENSSL_config ==

<tt>OPENSSL_config</tt> and <tt>OPENSSL_noconfig</tt> loads and unloads <tt>openssl.cnf</tt>. More correctly, a call to <tt>OPENSSL_config(NULL)</tt> loads the default configuration in <tt>openssl.cnf</tt>, <tt>OPENSSL_config(filename)</tt> loads another configuration, and <tt>OPENSSL_noconfig</tt> unlods a configuration.

<tt>OPENSSL_config</tt> may (or may not) be called depending upon how the OpenSSL library was configured, and it depends on whether <tt>OPENSSL_LOAD_CONF</tt> was defined. Because <tt>OPENSSL_config</tt> may (or may not) be called, your program may or may not need to make the call to <tt>OPENSSL_config</tt>. If, for example, your program is dynamically loading an ENGINE from <tt>OPENSSL_config</tt>, then you will need to ensure a call to <tt>OPENSSL_config</tt>.

You can check the value of <tt>OPENSSL_LOAD_CONF</tt> by <tt>cat</tt>'ing you<tt><nowiki><openssl/opensslconf.h></nowiki></tt>. You can then decide to call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt> based upon the definition (or lack threof) for <tt>OPENSSL_LOAD_CONF</tt>.

<pre>$ cat /usr/local/ssl/include/openssl/opensslconf.h | grep -i load
$</pre>

Here are the rules you should observe. In either case, your program should not depend upon the OpenSSL library and get into a known state.

* If you need something from <tt>openssl.cnf</tt>, then call <tt>OPENSSL_config</tt>. Don't depend on the library to do it for you.
* If you don't need something from <tt>openssl.cnf</tt> (or its mucking up you program), then call <tt>OPENSSL_noconfig</tt>. The library may have called <tt>OPENSSL_config</tt> for you.

== Engines ==

If your application needs to use engines, then it should either call call <tt>ENGINE_load_builtin_engines</tt> or <tt>OPENSSL_config</tt> to load the built-in engines (including dynamically configured engines from <tt>openssl.cnf</tt>).

Engines are are automatically loaded (or not loaded) based on the definition of <tt>OPENSSL_LOAD_CONF</tt> (or lack of definition). You should not depend on library behavior, so you should call <tt>OPENSSL_config</tt> or <tt>ENGINE_load_builtin_engines</tt> if you need engines.

You can also load a particular engine if you know what you want to use. <tt>eng_all.c</tt> lists the built-in engines you can load. For example, the following loads the <tt>rdrand</tt> engine provided for some Intel CPUs.

<pre>unsigned long err = 0;
int rc = 0;

OPENSSL_cpuid_setup();
ENGINE_load_rdrand();

ENGINE* eng = ENGINE_by_id("rdrand");
if(NULL == eng) handleFailure();

rc = ENGINE_init(eng);
if(1 != rc) handleFailure();

rc = ENGINE_set_default(eng, ENGINE_METHOD_RAND);
if(1 != rc) handleFailure();

/* OK to proceed */
...

ENGINE_finish(eng);
ENGINE_free(eng);
ENGINE_cleanup();</pre>

If you want an engine to provide all incumbent functionality for the OpenSSL library, then then call <tt>ENGINE_register_complete</tt> after loading the engine. Incumbent functionality is determined by the manufacturer and includes includes RSA, DSA, DH, ECDH, MD, and RAND operations. See <tt>eng_all.c</tt>, <tt>eng_fat.c</tt>, and [http://www.openssl.org/docs/crypto/engine.html engine(3)] for details.

<pre>ENGINE* eng = ENGINE_by_id("XXX");
if(!(eng->flags & ENGINE_FLAGS_NO_REGISTER_ALL))
ENGINE_register_complete(eng);</pre>

== Cleanup ==

How to cleanup the library arises on occasion. Its often in the context of running a program under a memory checker like Valgrind.

OpenSSL does not provide a <tt>SSL_library_uninit</tt> or <tt>SSL_library_cleanup</tt> function (also see [http://rt.openssl.org/Ticket/Display.html?id=3824&user=guest&pass=guest Issue #3824, FEATURE: Please provide a function to unintialize the library]). To cleanup the library the library call the following functions:

* FIPS_mode_set(0);
* ENGINE_cleanup();
* CONF_modules_unload(1);
* EVP_cleanup();
* CRYPTO_cleanup_all_ex_data();
* ERR_remove_state();
* ERR_free_strings();

'''Note:''' ERR_remove_state() was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state() was introduced. ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0 when the thread handling functionality was entirely rewritten.

<tt>CRYPTO_cleanup_all_ex_data</tt> and <tt>ERR_remove_state</tt> should be called on each thread, and not just the main thread.

The above list is a minimum to call. You will still need to cleanup Diffie-Hellman parameters, server contexts, static locks, etc.

After cleanup, you may have some memory leaks due to dynamic allocation of private static variables like <tt>ssl_comp_methods</tt>. This is a well known issue (see [http://rt.openssl.org/Ticket/Display.html?id=2561&user=guest&pass=guest Issue #2561, Memory leak with SSL built-in compressions]).

==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 usful to detect either <tt>OPENSSL_init_ssl</tt> and <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:Examples]]

OpenSSL 3.0

2020-10-15T12:59:42Z

Matt: /* Library Contexts */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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).

* The RAND_DRBG subsystem has been removed. The new EVP_RAND is a partial replacement: the DRBG callback framework is absent.

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

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 OSSL_LIB_CTX type. See the man page [https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX.html here].

'''Note:''' ''In alpha releases of OpenSSL 3.0.0 up until alpha6, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 alpha7. If you are still using an alpha6 release or earlier, take a look at this [https://wiki.openssl.org/index.php?title=OpenSSL_3.0&oldid=3119 older version of the wiki page].''

Many new functions have been introduced into OpenSSL that take an OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_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 OSSL_LIB_CTX_load_config() function described on the man page).

=== Providers ===

Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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/fipsmodule.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 and base providers. The other library context will just use the default provider.

OSSL_LIB_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 = OSSL_LIB_CTX_new();
nonfipslibctx = OSSL_LIB_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 and base providers so we
* don't need to explicitly load them here.
*/
if (!OSSL_LIB_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 OSSL_LIB_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);
OSSL_LIB_CTX_free(fipslibctx);
OSSL_LIB_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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-06T12:13:28Z

Matt: /* Using Serializers with the FIPS module */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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/fipsmodule.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 and base providers. 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 and base providers so we
* don't need to explicitly load them 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 and Deserializers with the FIPS module ===

Serializers and deserializers are used to read and write keys or parameters from or to some external format (for example a PEM file). 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. Similarly you need a deserializer to read previously saved keys and parameters. 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/deserializer will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL serializers and deserializers are implemented in both the default and base providers 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/deserializers have the "fips=yes" property against them. You should ensure that either the default or base 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-06T12:10:04Z

Matt: /* Programmatically loading the FIPS module (non-default library context) */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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/fipsmodule.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 and base providers. 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 and base providers so we
* don't need to explicitly load them 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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-06T12:09:49Z

Matt: /* Programmatically loading the FIPS module (non-default library context) */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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/fipsmodule.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 and base providers. 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 and base provider so we
* don't need to explicitly load them 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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-06T12:07:01Z

Matt: /* Loading the FIPS module at the same time as other providers */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-06T12:03:58Z

Matt: /* Programmatically loading the FIPS module (default library context) */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for serializing and de-serializing keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

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 high level APIs, such as EVP, instead)
* 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.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions.

=== 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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-06T11:59:25Z

Matt: /* Programmatically loading the FIPS module (default library context) */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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;
OSSL_PROVIDER *base;

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

/* Rest of application */

OSSL_PROVIDER_unload(base);
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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-05T14:30:55Z

Matt: /* Providers */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five 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 base provider. This contains a small sub-set of non-cryptographic algorithms available in the default provider. For example algorithms to serialize and deserialize keys to files. If you do not load the default provider then you should always load this one instead (including if you are using the FIPS provider).

* 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-05T14:25:25Z

Matt: /* Completing the installation of the FIPS Module */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-05T14:23:18Z

Matt: /* Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-05T14:22:36Z

Matt: /* 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.

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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.

== 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-05T14:20:49Z

Matt: /* Providers and FIPS support */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). They cannot be accessed using the "low level" APIs (see below).

One of the standard providers available is the FIPS provider. This makes available FIPS validated cryptographic algorithms.

=== Low Level APIs ===

OpenSSL has historically provided two sets of APIs for invoking cryptographic algorithms: the "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-05T14:17:54Z

Matt: /* Low Level APIs */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). 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 "high level" APIs (such as the "EVP" APIs) and the "low level" APIs. The high level 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 high level 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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-08-05T14:16:23Z

Matt: /* Providers and FIPS support */

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

=== License Change ===

In previous versions, OpenSSL was licensed under the dual [https://www.openssl.org/source/license-openssl-ssleay.txt OpenSSL and SSLeay licenses] (both licenses apply). From OpenSSL 3.0 this is replaced by the [https://www.openssl.org/source/apache-license-2.0.txt Apache License v2].

=== 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 5 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 "high" level APIs (for example those functions prefixed with "EVP"). 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()' have been removed from OpenSSL 3.0. 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 (if you wish to use it). 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 FIPS module to its default location:

$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.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

If you installed OpenSSL to a different location, you need to adjust the output and module path accordingly.

== 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 <stdio.h>
#include <stdlib.h>

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

== 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 no longer present so you must remove them from your application if you 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/fipsmodule.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 fipsmodule.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 conforms 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 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/fipsmodule.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 and alpha 2 releases 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 objects 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 alpha 1 and alpha 2 releases 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]]

=== Confirming that an algorithm is being provided by the FIPS module ===

A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithm, here the example of a digest is used.

# To go from an ''EVP_MD_CTX'' to an ''EVP_MD'', use the '''EVP_MD_CTX_md()''' call.
# To go from the ''EVP_MD'' to its ''OSSL_PROVIDER'', use the '''EVP_MD_provider()''' call.
# To extract the name from the ''OSSL_PROVIDER'', use the '''OSSL_PROVIDER_name()''' call.
# Finally, use strcmp(3) or printf(3) on the name.

== 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
|-
| FreeBSD - aarch64 || Yes || Yes || Tested on 13.0-CURRENT
|-
| FreeBSD - amd64 || Yes || Yes || Tested on 12.1-STABLE and 11.3-STABLE
|-
| FreeBSD - i386 || Yes || Yes || Had to run <code>./config no-pic</code> due to lack of CAST PIC support
|-
| 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 || 100% || ??
|-
| 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, FIPS || 100% || ??
|}

==== 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 || 100% || ??
|-
| 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
|}