OpenSSLWiki - User contributions [en]

FIPS module 2.0

2022-10-20T10:25:00Z

Mspncp: Fix broken CMVP links (fixup)

The ''OpenSSL FIPS Object Module 2.0'' was first validated with FIPS 140-2 certificate [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/1747 #1747] in mid-2012. This 2.0 FIPS module is compatible with OpenSSL releases 1.0.1 and 1.0.2, and not with any other releases.

There are two "clone" validations (known as "Alternative Scenario 1A" validations, also referred to as "re-brand" validations by some test labs) were obtained for the same module. The "RE" validation, [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2473 #2473], was intended to be identical to [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/1747 #1747] while allowing the addition of new platforms. The "SE" validation, [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2398 #2398], was intended for the addition of platforms requiring source code mods and thus new revisions to the module tarball. The [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/1747 #1747] and [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2473 #2473] validations will forever remain at revision 2.0.10, while new revisions will be added to [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2398 #2398] (which is at 2.0.13 as of September 2016).

Note that although the paperwork for the two clone validations #2398 and #2473 was submitted at the same time, and the two sets of paperwork were precisely identical other than the respective references to "RE" versus "SE" in the module names, they were approved at different times (July and November) with different editorial modifications required by the CMVP for the Security Policy documents. Such inconsistencies are common with FIPS 140-2 validations; the outcome from one validation effort is not necessarily predictive of what will happen for subsequent similar (or even identical) attempts.

In addition to the three validations of the ''OpenSSL FIPS Object Module 2.0'' obtained directly by OpenSSL, some third party vendors have obtained additional "re-brand" validations of the same cryptographic module:

:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2676 #2676], Cohesity OpenSSL FIPS Object Module
:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2631 #2631], Intel OpenSSL FIPS Object Module
:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2575 #2575], Cellcrypt Secure Core 3 FIPS 140-2 Module
:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2454 #2454], LogRhythm FIPS Object Module Version 6.3.4
:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2422 #2422], Nimble Storage OpenSSL FIPS Object Module

Note that while these clone validations have re-branded proprietary module names, they reference the original ''OpenSSL FIPS Object Module 2.0'' tarballs which are available under the open source OpenSSL license, and hence these validations can be used and cited by anyone.

A list of formally tested platforms ("Operational Environments") is associated with each validation. Collectively there are over two hundred unique platforms listed across all the ''OpenSSL FIPS Object Module 2.0'' validations:

{| class="wikitable"
|+Unique platforms across all ''OpenSSL FIPS Object Module 2.0'' validations as of 2016-09
|-
|AcanOS 1.0 running on Feroceon 88FR131 (ARMv5) (gcc Compiler Version 4.5.3)
|-
|AcanOS 1.0 running on Intel Core i7-3612QE (x86) with AES-NI (gcc Compiler Version 4.6.2)
|-
|AcanOS 1.0 running on Intel Core i7-3612QE (x86) without AES-NI (gcc Compiler Version 4.6.2)
|-
|AIX 6.1 32-bit running on IBM POWER 7 (PPC) (IBM XL C/C++ for AIX Compiler Version V13.1)
|-
|AIX 6.1 32-bit running on IBM POWER 7 (PPC) with optimizations (IBM XL C/C++ for AIX Compiler Version V10.1)
|-
|AIX 6.1 64-bit running on IBM POWER 7 (PPC) (IBM XL C/C++ for AIX Compiler Version V13.1)
|-
|AIX 6.1 64-bit running on IBM POWER 7 (PPC) with optimizations (IBM XL C/C++ for AIX Compiler Version V10.1)
|-
|AIX 7.1 32-bit running on IBM POWER 7 (PPC) (IBM XL C/C++ for AIX Compiler Version V13.1)
|-
|AIX 7.1 64-bit running on IBM POWER 7 (PPC) (IBM XL C/C++ for AIX Compiler Version V13.1)
|-
|Android 2.2 (gcc Compiler Version 4.4.0)
|-
|Android 2.2 running on OMAP 3530 (ARMv7) with NEON (gcc Compiler Version 4.1.0)
|-
|Android 2.2 running on Qualcomm QSD8250 (ARMv7) with NEON (gcc Compiler Version 4.4.0)
|-
|Android 2.2 running on Qualcomm QSD8250 (ARMv7) without NEON (gcc Compiler Version 4.4.0)
|-
|Android 3.0 (gcc Compiler Version 4.4.0)
|-
|Android 3.0 running on NVIDIA Tegra 250 T20 (ARMv7) (gcc Compiler Version 4.4.0)
|-
|Android 4.0 (gcc Compiler Version 4.4.3)
|-
|Android 4.0 running on NVIDIA Tegra 250 T20 (ARMv7) (gcc Compiler Version 4.4.3)
|-
|Android 4.0 running on Qualcomm Snapdragon APQ8060 (ARMv7) with NEON (gcc compiler Version 4.4.3)
|-
|Android 4.0 running on TI OMAP 3 (ARMv7) with NEON (gcc Compiler Version 4.4.3)
|-
|Android 4.1 running on TI DM3730 (ARMv7) (gcc Compiler Version 4.6)
|-
|Android 4.1 running on TI DM3730 (ARMv7) with NEON (gcc Complier Version 4.6)
|-
|Android 4.1 running on TI DM3730 (ARMv7) without NEON (gcc Compiler Version 4.6)
|-
|Android 4.2 running on Nvidia Tegra 3 (ARMv7) (gcc Compiler Version 4.6)
|-
|Android 4.2 running on Nvidia Tegra 3 (ARMv7) with Neon (gcc Compiler Version 4.6)
|-
|Android 4.2 running on Nvidia Tegra 3 (ARMv7) with NEON (gcc Compiler Version 4.6)
|-
|Android 4.2 running on Nvidia Tegra 3 (ARMv7) without NEON (gcc Compiler Version 4.6)
|-
|Android 5.0 32-bit running on Qualcomm APQ8084 (ARMv7) with NEON (gcc Compiler Version 4.9)
|-
|Android 5.0 32-bit running on Qualcomm APQ8084 (ARMv7) without NEON (gcc Compiler Version 4.9)
|-
|Android 5.0 64-bit running on SAMSUNG Exynos7420 (ARMv8) with NEON and Crypto Extensions (gcc Compiler Version 4.9)
|-
|Android 5.0 64-bit running on SAMSUNG Exynos7420 (ARMv8) without NEON and Crypto Extensions (gcc Compiler Version 4.9)
|-
|Apple iOS 5.0 running on ARM Cortex A8 (ARMv7) with NEON (gcc Compiler Version 4.2.1)
|-
|Apple iOS 5.1 (gcc Compiler Version 4.2.1)
|-
|Apple iOS 5.1 running on ARMv7 (gcc Compiler Version 4.2.1)
|-
|Apple iOS 6.1 running on Apple A6X SoC (ARMv7s) (gcc Compiler Version 4.2.1)
|-
|Apple iOS 7.1 64-bit running on Apple A7 (ARMv8) with NEON (clang Compiler Version 5.1)
|-
|Apple iOS 7.1 64- bit running on Apple A7 (ARMv8) without NEON (clang Compiler Version 5.1)
|-
|Apple OS X 10.7 running on Intel Core i7-3615QM (Apple LLVM version 4.2)
|-
|ArbOS 5.3 running on Xeon E5645 (x86) with AES-NI (gcc Compiler Version 4.1.2)
|-
|ArbOS 5.3 running on Xeon E5645 (x86) without AES-NI (gcc Compiler Version 4.1.2)
|-
|CascadeOS 6.1 (32 bit) (gcc Compiler Version 4.4.5)
|-
|CascadeOS 6.1 (32 bit) running on Intel Pentium T4200 (gcc Compiler Version 4.4.5)
|-
|CascadeOS 6.1 (64 bit) (gcc Compiler Version 4.4.5)
|-
|CascadeOS 6.1 (64 bit) running on Intel Pentium T4200 (gcc Compiler Version 4.4.5)
|-
|CentOS 5.6 64-bit running on Intel Xeon E5-2620v3 (gcc Compiler Version 4.1.2)
|-
|CentOS 5.6 64-bit running on Intel Xeon E5-2690v3 (gcc Compiler Version 4.1.2)
|-
|DataGravity Discovery Series OS V2.0 running on Intel Xeon E5-2420 (x86) with AES-NI (gcc Compiler Version 4.7.2)
|-
|DataGravity Discovery Series OS V2.0 running on Intel Xeon E5-2420 (x86) without AES-NI (gcc Compiler Version 4.7.2)
|-
|DSP Media Framework 1.4 running on TI C64x+ (TMS320C6x C/C++ Compiler v6.0.13)
|-
|DSP Media Framework 1.4 (TMS320C6x C/C++ Compiler v6.0.13)
|-
|eCos 3 running on Freescale i.MX27 926ejs (ARMv5TEJ) (gcc Compiler Version 4.3.2)
|-
|Fedora 14 running on Intel Core i5 with AES-NI (gcc Compiler Version 4.5.1)
|-
|FreeBSD 10.0 running on Xeon E5- 2430L (x86) with AES-NI (clang Compiler Version 3.3)
|-
|FreeBSD 10.0 running on Xeon E5-2430L (x86) with AES-NI (clang Compiler Version 3.3)
|-
|FreeBSD 10.0 running on Xeon E5-2430L (x86) without AES-NI (clang Compiler Version 3.3)
|-
|FreeBSD 10.2 running on Intel Xeon E5-2430L (x86) with AES-NI (clang Compiler Version 3.4.1)
|-
|FreeBSD 10.2 running on Intel Xeon E5-2430L (x86) without AES-NI (clang Compiler Version 3.4.1)
|-
|FreeBSD 8.4 running on Intel Xeon E5440 (x86) 32-bit (gcc Compiler Version 4.2.1)
|-
|FreeBSD 8.4 running on Intel Xeon E5440 (x86) without AES-NI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 8.4 running on Intel Xeon E5440 (x86) without AESNI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.1 running on Xeon E5-2430L (x86) with AES-NI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.1 running on Xeon E5-2430L (x86) without AES-NI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.1 running on Xeon E5-2430L (x86) without AESNI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.2 running on Xeon E5-2430L (x86) with AES-NI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.2 running on Xeon E5-2430L (x86) without AES-NI (gcc Compiler Version 4.2.1)
|-
|HP-UX 11i (32 bit) (HP C/aC++ B3910B)
|-
|HP-UX 11i (32 bit) running on Intel Itanium 2 (HP C/aC++ B3910B)
|-
|HP-UX 11i (64 bit) (HP C/aC++ B3910B)
|-
|HP-UX 11i (64 bit) running on Intel Itanium 2 (HP C/aC++ B3910B)
|-
|iOS 6.0 running on Apple A5 / ARM Cortex-A9 (ARMv7) with NEON (gcc Compiler Version 4.2.1)
|-
|iOS 6.0 running on Apple A5 / ARM Cortex-A9 (ARMv7) without NEON (gcc Compiler Version 4.2.1)
|-
|iOS 8.1 32bit running on Apple A7 (ARMv8) with NEON (clang Compiler Version 600.0.56)
|-
|iOS 8.1 32-bit running on Apple A7 (ARMv8) with NEON (clang Compiler Version 600.0.56)
|-
|iOS 8.1 32bit running on Apple A7 (ARMv8) without NEON (clang Compiler Version 600.0.56)
|-
|iOS 8.1 32-bit running on Apple A7 (ARMv8) without NEON (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64bit running on Apple A7 (ARMv8) with NEON and Crypto Extensions (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64-bit running on Apple A7 (ARMv8) with NEON and Crypto Extensions (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64bit running on Apple A7 (ARMv8) without NEON and Crypto Extensions (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64-bit running on Apple A7 (ARMv8) without NEON and Crypto Extensions (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64-bit running on Apple A7 (ARMv8) without NEON and Crypto Extensions (clang Compilerv Version 600.0.56)
|-
|Linux 2.6.27 (gcc Compiler Version 4.2.4)
|-
|Linux 2.6.27 running on PowerPC e300c3 (gcc Compiler Version 4.2.4)
|-
|Linux 2.6.32 (gcc Compiler Version 4.3.2)
|-
|Linux 2.6.32 running on TI AM3703CBP (ARMv7) (gcc Compiler Version 4.3.2)
|-
|Linux 2.6.33 (gcc Compiler Version 4.1.0)
|-
|Linux 2.6.33 running on PowerPC32 e300 (gcc Compiler Version 4.1.0)
|-
|Linux 2.6 (gcc Compiler Version 4.1.0)
|-
|Linux 2.6 (gcc Compiler Version 4.3.2)
|-
|Linux 2.6 running on a Nimble Storage CS300 with AES-NI
|-
|Linux 2.6 running on a Nimble Storage CS500 with AES-NI
|-
|Linux 2.6 running on a Nimble Storage CS700 with AES-NI
|-
|Linux 2.6 running on Broadcom BCM11107 (ARMv6) (gcc Compiler Version 4.3.2)
|-
|Linux 2.6 running on Freescale e500v2 (PPC) (gcc Compiler Version 4.4.1)
|-
|Linux 2.6 running on Freescale PowerPCe500 (gcc Compiler Version 4.1.0)
|-
|Linux 2.6 running on TI TMS320DM6446 (ARMv4) (gcc Compiler Version 4.3.2)
|-
|Linux 3.10 32-bit running on Intel Atom E3845 (x86) with AES-NI (gcc Compiler Version 4.8.1)
|-
|Linux 3.10 32-bit running on Intel Atom E3845 (x86) without AES-NI (gcc Compiler Version 4.8.1)
|-
|Linux 3.10 on VMware ESXi 6.00 running on Intel Xeon with AES-NI (gcc Compiler Version 4.8.3)
|-
|Linux 3.10 on Vmware ESXi 6.00 running on Intel Xeon without AES-NI (gcc Compiler Version 4.8.3)
|-
|Linux 3.10 running on Intel Xeon with AES-NI (gcc Compiler Version 4.8.3)
|-
|Linux 3.10 running on Intel Xeon without AES-NI (gcc Compiler Version 4.8.3)
|-
|Linux 3.4 64-bit under Citrix XenServer running on Intel Xeon E5-2430L (x86) without AES-NI
|-
|Linux 3.4 under Citrix XenServer 6.2 running on Intel Xeon E5-2430L with AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Citrix XenServer 6.2 running on Intel Xeon E5-2430L without AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Microsoft Windows 2012 Hyper-V running on Intel Xeon E5-2430L with AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Microsoft Windows 2012 Hyper-V running on Intel Xeon E5-2430L with AES-NI (gcc Compiler Version 4.8.0)2
|-
|Linux 3.4 under Microsoft Windows 2012 Hyper-V running on Intel Xeon E5-2430L without AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Vmware ESXi 5.1 running on Intel Xeon E5-2430L with AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Vmware ESXi 5.1 running on Intel Xeon E5-2430L without AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.8 running on ARM926 (ARMv5TEJ) (gcc Compiler Version 4.7.3)
|-
|Linux ORACLESP 2.6 running on ASPEED AST-Series (ARMv5) (gcc Compiler Version 4.4.5)
|-
|Linux ORACLESP 2.6 running on Emulex PILOT3 (ARMv5) (gcc Compiler Version 4.4.5)
|-
|Microsoft Windows 7 (32 bit) (Microsoft 32 bit C/C++ Optimizing Compiler Version 16.00)
|-
|Microsoft Windows 7 (32 bit) running on Intel Celeron (Microsoft 32 bit C/C++ Optimizing Compiler Version 16.00)
|-
|Microsoft Windows 7 (64 bit) (Microsoft C/C++ Optimizing Compiler Version 16.00)
|-
|Microsoft Windows 7 (64 bit) running on Intel Pentium 4 (Microsoft C/C++ Optimizing Compiler Version 16.00)
|-
|Microsoft Windows 7 running on Intel Core i5- 2430M (64-bit) with AES-NI (Microsoft ® C/C++ Optimizing Compiler Version 16.00 for x64)
|-
|Microsoft Windows 7 running on Intel Core i5-2430M (64-bit) with AES-NI (Microsoft « C/C++ Optimizing Compiler Version 16.00 for x64)
|-
|Microsoft Windows CE 5.0 (Microsoft C/C++ Optimizing Compiler Version 13.10 for ARM)
|-
|Microsoft Windows CE 5.0 running on ARMv7 (Microsoft C/C++ Optimizing Compiler Version 13.10 for ARM)
|-
|Microsoft Windows CE 6.0 (Microsoft C/C++ Optimizing Compiler Version 15.00 for ARM)
|-
|Microsoft Windows CE 6.0 running on ARMv5TEJ (Microsoft C/C++ Optimizing Compiler Version 15.00 for ARM)
|-
|Microsoft Windows Server 2008 R2 running on an Intel Xeon E5-2420 (x64) (Microsoft 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86)
|-
|NetBSD 5.1 (gcc Compiler Version 4.1.3)
|-
|NetBSD 5.1 running on Intel Xeon 5500 (gcc Compiler Version 4.1.3)
|-
|NetBSD 5.1 running on PowerPCe500 (gcc Compiler Version 4.1.3)
|-
|OpenWRT 2.6 running on MIPS 24Kc (gcc Compiler Version 4.6.3)
|-
|Oracle Linux 5 (64 bit) (gcc Compiler Version 4.1.2)
|-
|Oracle Linux 5 (64 bit) running on Intel Xeon 5675 (gcc Compiler Version 4.1.2)
|-
|Oracle Linux 5 running on Intel Xeon 5675 with AES-NI (gcc Compiler Version 4.1.2)
|-
|Oracle Linux 6 (gcc Compiler Version 4.4.6)
|-
|Oracle Linux 6 running on Intel Xeon 5675 with AES-NI (gcc Compiler Version 4.4.6)
|-
|Oracle Linux 6 running on Intel Xeon 5675 without AES-NI (gcc Compiler Version 4.4.6)
|-
|Oracle Solaris 10 (32 bit) (gcc Compiler Version 3.4.3)
|-
|Oracle Solaris 10 (32 bit) running on SPARC-T3 (SPARCv9) (gcc Compiler Version3.4.3)
|-
|Oracle Solaris 10 (64 bit) (gcc Compiler Version 3.4.3)
|-
|Oracle Solaris 10 (64 bit) running on SPARC-T3 (SPARCv9) (gcc Compiler Version 3.4.3)
|-
|Oracle Solaris 11(32 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 (32 bit) running on Intel Xeon 5675 (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 (32 bit) running on SPARC-T3 (SPARCv9) (Sun C Version 5.12)
|-
|Oracle Solaris 11 (32 bit) (Sun C Version 5.12)
|-
|Oracle Solaris 11 (64 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 (64 bit) running on Intel Xeon 5675 (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 (64 bit) running on SPARC-T3 (SPARCv9) (Sun C Version 5.12)
|-
|Oracle Solaris 11 (64 bit) (Sun C Version 5.12)
|-
|Oracle Solaris 11 running on Intel Xeon 5675 with AES-NI (32 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 running on Intel Xeon 5675 with AESNI (32 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 running on Intel Xeon 5675 with AES-NI (64 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 running on Intel Xeon 5675 with AESNI (64 bit) (gcc Compiler Version 4.5.2)
|-
|PexOS 1.0 under vSphere ESXi 5.1 running on Intel Xeon E52430L with AES-NI (gcc Compiler Version 4.6.3)3
|-
|PexOS 1.0 under vSphere ESXi 5.1 running on Intel Xeon E52430L without AES-NI (gcc Compiler Version 4.6.3)
|-
|QNX 6.4 running on Freescale i.MX25 (ARMv4) (gcc Compiler Version 4.3.3)
|-
|QNX 6.5 running on Freescale i.MX25 (ARMv4) (gcc Compiler Version 4.3.3)
|-
|TS-Linux 2.4 running on Arm920Tid (ARMv4) (gcc Compiler Version 4.3.2)
|-
|TS-Linux 2.4 running on Arm920Tid (ARMv4) (gcc Compiler Version 4.3.2)4
|-
|Ubuntu 10.04 (32 bit) (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 (32 bit) running on Intel Pentium T4200 (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 (64 bit) (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 (64 bit) running on Intel Pentium T4200 (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 running on Intel Core i5 with AES-NI (32 bit) (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 running on Intel Pentium T4200 (gcc Compiler Version 4.1.3)
|-
|Ubuntu 12.04 running on Intel Xeon E5-2430L (x86) with AES-NI (gcc Compiler Version 4.6.3)
|-
|Ubuntu 12.04 running on Intel Xeon E5-2430L (x86) without AES-NI (gcc Compiler Version 4.6.3)
|-
|Ubuntu 13.04 running on AM335x Cortex-A8 (ARMv7) (gcc Compiler Version 4.7.3)
|-
|Ubuntu 13.04 running on AM335x Cortex-A8 (ARMv7) with NEON (gcc Compiler Version 4.7.3)
|-
|Ubuntu 13.04 running on AM335x Cortex-A8 (ARMv7) without NEON (gcc Compiler Version 4.7.3)
|-
|uCLinux 0.9.29 (gcc Compiler Version 4.2.1)
|-
|uCLinux 0.9.29 running on ARM 922T (ARMv4) (gcc Compiler Version 4.2.1)
|-
|Vmware Horizon Workspace 1.5 under Vmware ESXi 5.0 running on Intel Xeon E3-1220 (x86) with AES-NI (gcc Compiler Version 4.5.1)1
|-
|Vmware Horizon Workspace 1.5 under Vmware ESXi 5.0 running on Intel Xeon E3-1220 (x86) without AES-NI (gcc Compiler Version 4.5.1)
|-
|Vmware Horizon Workspace 2.1 under vSphere ESXi 5.5 running on Intel Xeon E3-1220 (x86) with AES-NI (gcc Compiler Version 4.5.1)
|-
|Vmware Horizon Workspace 2.1 under vSphere ESXi 5.5 running on Intel Xeon E3-1220 (x86) with AESNI (gcc Compiler Version 4.5.1)
|-
|Vmware Horizon Workspace 2.1 under vSphere ESXi 5.5 running on Intel Xeon E3-1220 (x86) without AES-NI (gcc Compiler Version 4.5.1)
|-
|VxWorks 6.7 running on Intel Core 2 Duo (x86) (gcc Compiler Version 4.1.2)
|-
|VxWorks 6.8 (gcc Compiler Version 4.1.2)
|-
|VxWorks 6.8 running on TI TNETV1050 (MIPS) (gcc Compiler Version 4.1.2)
|-
|VxWorks 6.9 running on Freescale P2020 (PPC) (gcc Compiler Version 4.3.3)
|-
|Windows Embedded Compact 7 running on Freescale i.MX53xA (ARMv7) with NEON (Microsoft C/C++ Optimizing Compiler Version 15.00.20720)
|-
|Windows Embedded Compact 7 running on Freescale i.MX53xD (ARMv7) with NEON (Microsoft C/C++ Optimizing Compiler Version 15.00.20720)
|}

FIPS module 2.0

2022-10-20T10:23:15Z

Mspncp: Fix broken CMVP links

The ''OpenSSL FIPS Object Module 2.0'' was first validated with FIPS 140-2 certificate [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/1747 #1747] in mid-2012. This 2.0 FIPS module is compatible with OpenSSL releases 1.0.1 and 1.0.2, and not with any other releases.

There are two "clone" validations (known as "Alternative Scenario 1A" validations, also referred to as "re-brand" validations by some test labs) were obtained for the same module. The "RE" validation, [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2473 #2473], was intended to be identical to [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/1747 #1747] while allowing the addition of new platforms. The "SE" validation, [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2398 #2398], was intended for the addition of platforms requiring source code mods and thus new revisions to the module tarball. The [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/1747 #1747] and [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2473 #2473] validations will forever remain at revision 2.0.10, while new revisions will be added to [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2398 #2398] (which is at 2.0.13 as of September 2016).

Note that although the paperwork for the two clone validations #2398 and #2473 was submitted at the same time, and the two sets of paperwork were precisely identical other than the respective references to "RE" versus "SE" in the module names, they were approved at different times (July and November) with different editorial modifications required by the CMVP for the Security Policy documents. Such inconsistencies are common with FIPS 140-2 validations; the outcome from one validation effort is not necessarily predictive of what will happen for subsequent similar (or even identical) attempts.

In addition to the three validations of the ''OpenSSL FIPS Object Module 2.0'' obtained directly by OpenSSL, some third party vendors have obtained additional "re-brand" validations of the same cryptographic module:

:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2676 #2676], Cohesity OpenSSL FIPS Object Module
:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2631 #2631], Intel OpenSSL FIPS Object Module
:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2575 #2575], Cellcrypt Secure Core 3 FIPS 140-2 Module
:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2454 #2454], LogRhythm FIPS Object Module Version 6.3.4
:: [https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/2454 #2422], Nimble Storage OpenSSL FIPS Object Module

Note that while these clone validations have re-branded proprietary module names, they reference the original ''OpenSSL FIPS Object Module 2.0'' tarballs which are available under the open source OpenSSL license, and hence these validations can be used and cited by anyone.

A list of formally tested platforms ("Operational Environments") is associated with each validation. Collectively there are over two hundred unique platforms listed across all the ''OpenSSL FIPS Object Module 2.0'' validations:

{| class="wikitable"
|+Unique platforms across all ''OpenSSL FIPS Object Module 2.0'' validations as of 2016-09
|-
|AcanOS 1.0 running on Feroceon 88FR131 (ARMv5) (gcc Compiler Version 4.5.3)
|-
|AcanOS 1.0 running on Intel Core i7-3612QE (x86) with AES-NI (gcc Compiler Version 4.6.2)
|-
|AcanOS 1.0 running on Intel Core i7-3612QE (x86) without AES-NI (gcc Compiler Version 4.6.2)
|-
|AIX 6.1 32-bit running on IBM POWER 7 (PPC) (IBM XL C/C++ for AIX Compiler Version V13.1)
|-
|AIX 6.1 32-bit running on IBM POWER 7 (PPC) with optimizations (IBM XL C/C++ for AIX Compiler Version V10.1)
|-
|AIX 6.1 64-bit running on IBM POWER 7 (PPC) (IBM XL C/C++ for AIX Compiler Version V13.1)
|-
|AIX 6.1 64-bit running on IBM POWER 7 (PPC) with optimizations (IBM XL C/C++ for AIX Compiler Version V10.1)
|-
|AIX 7.1 32-bit running on IBM POWER 7 (PPC) (IBM XL C/C++ for AIX Compiler Version V13.1)
|-
|AIX 7.1 64-bit running on IBM POWER 7 (PPC) (IBM XL C/C++ for AIX Compiler Version V13.1)
|-
|Android 2.2 (gcc Compiler Version 4.4.0)
|-
|Android 2.2 running on OMAP 3530 (ARMv7) with NEON (gcc Compiler Version 4.1.0)
|-
|Android 2.2 running on Qualcomm QSD8250 (ARMv7) with NEON (gcc Compiler Version 4.4.0)
|-
|Android 2.2 running on Qualcomm QSD8250 (ARMv7) without NEON (gcc Compiler Version 4.4.0)
|-
|Android 3.0 (gcc Compiler Version 4.4.0)
|-
|Android 3.0 running on NVIDIA Tegra 250 T20 (ARMv7) (gcc Compiler Version 4.4.0)
|-
|Android 4.0 (gcc Compiler Version 4.4.3)
|-
|Android 4.0 running on NVIDIA Tegra 250 T20 (ARMv7) (gcc Compiler Version 4.4.3)
|-
|Android 4.0 running on Qualcomm Snapdragon APQ8060 (ARMv7) with NEON (gcc compiler Version 4.4.3)
|-
|Android 4.0 running on TI OMAP 3 (ARMv7) with NEON (gcc Compiler Version 4.4.3)
|-
|Android 4.1 running on TI DM3730 (ARMv7) (gcc Compiler Version 4.6)
|-
|Android 4.1 running on TI DM3730 (ARMv7) with NEON (gcc Complier Version 4.6)
|-
|Android 4.1 running on TI DM3730 (ARMv7) without NEON (gcc Compiler Version 4.6)
|-
|Android 4.2 running on Nvidia Tegra 3 (ARMv7) (gcc Compiler Version 4.6)
|-
|Android 4.2 running on Nvidia Tegra 3 (ARMv7) with Neon (gcc Compiler Version 4.6)
|-
|Android 4.2 running on Nvidia Tegra 3 (ARMv7) with NEON (gcc Compiler Version 4.6)
|-
|Android 4.2 running on Nvidia Tegra 3 (ARMv7) without NEON (gcc Compiler Version 4.6)
|-
|Android 5.0 32-bit running on Qualcomm APQ8084 (ARMv7) with NEON (gcc Compiler Version 4.9)
|-
|Android 5.0 32-bit running on Qualcomm APQ8084 (ARMv7) without NEON (gcc Compiler Version 4.9)
|-
|Android 5.0 64-bit running on SAMSUNG Exynos7420 (ARMv8) with NEON and Crypto Extensions (gcc Compiler Version 4.9)
|-
|Android 5.0 64-bit running on SAMSUNG Exynos7420 (ARMv8) without NEON and Crypto Extensions (gcc Compiler Version 4.9)
|-
|Apple iOS 5.0 running on ARM Cortex A8 (ARMv7) with NEON (gcc Compiler Version 4.2.1)
|-
|Apple iOS 5.1 (gcc Compiler Version 4.2.1)
|-
|Apple iOS 5.1 running on ARMv7 (gcc Compiler Version 4.2.1)
|-
|Apple iOS 6.1 running on Apple A6X SoC (ARMv7s) (gcc Compiler Version 4.2.1)
|-
|Apple iOS 7.1 64-bit running on Apple A7 (ARMv8) with NEON (clang Compiler Version 5.1)
|-
|Apple iOS 7.1 64- bit running on Apple A7 (ARMv8) without NEON (clang Compiler Version 5.1)
|-
|Apple OS X 10.7 running on Intel Core i7-3615QM (Apple LLVM version 4.2)
|-
|ArbOS 5.3 running on Xeon E5645 (x86) with AES-NI (gcc Compiler Version 4.1.2)
|-
|ArbOS 5.3 running on Xeon E5645 (x86) without AES-NI (gcc Compiler Version 4.1.2)
|-
|CascadeOS 6.1 (32 bit) (gcc Compiler Version 4.4.5)
|-
|CascadeOS 6.1 (32 bit) running on Intel Pentium T4200 (gcc Compiler Version 4.4.5)
|-
|CascadeOS 6.1 (64 bit) (gcc Compiler Version 4.4.5)
|-
|CascadeOS 6.1 (64 bit) running on Intel Pentium T4200 (gcc Compiler Version 4.4.5)
|-
|CentOS 5.6 64-bit running on Intel Xeon E5-2620v3 (gcc Compiler Version 4.1.2)
|-
|CentOS 5.6 64-bit running on Intel Xeon E5-2690v3 (gcc Compiler Version 4.1.2)
|-
|DataGravity Discovery Series OS V2.0 running on Intel Xeon E5-2420 (x86) with AES-NI (gcc Compiler Version 4.7.2)
|-
|DataGravity Discovery Series OS V2.0 running on Intel Xeon E5-2420 (x86) without AES-NI (gcc Compiler Version 4.7.2)
|-
|DSP Media Framework 1.4 running on TI C64x+ (TMS320C6x C/C++ Compiler v6.0.13)
|-
|DSP Media Framework 1.4 (TMS320C6x C/C++ Compiler v6.0.13)
|-
|eCos 3 running on Freescale i.MX27 926ejs (ARMv5TEJ) (gcc Compiler Version 4.3.2)
|-
|Fedora 14 running on Intel Core i5 with AES-NI (gcc Compiler Version 4.5.1)
|-
|FreeBSD 10.0 running on Xeon E5- 2430L (x86) with AES-NI (clang Compiler Version 3.3)
|-
|FreeBSD 10.0 running on Xeon E5-2430L (x86) with AES-NI (clang Compiler Version 3.3)
|-
|FreeBSD 10.0 running on Xeon E5-2430L (x86) without AES-NI (clang Compiler Version 3.3)
|-
|FreeBSD 10.2 running on Intel Xeon E5-2430L (x86) with AES-NI (clang Compiler Version 3.4.1)
|-
|FreeBSD 10.2 running on Intel Xeon E5-2430L (x86) without AES-NI (clang Compiler Version 3.4.1)
|-
|FreeBSD 8.4 running on Intel Xeon E5440 (x86) 32-bit (gcc Compiler Version 4.2.1)
|-
|FreeBSD 8.4 running on Intel Xeon E5440 (x86) without AES-NI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 8.4 running on Intel Xeon E5440 (x86) without AESNI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.1 running on Xeon E5-2430L (x86) with AES-NI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.1 running on Xeon E5-2430L (x86) without AES-NI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.1 running on Xeon E5-2430L (x86) without AESNI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.2 running on Xeon E5-2430L (x86) with AES-NI (gcc Compiler Version 4.2.1)
|-
|FreeBSD 9.2 running on Xeon E5-2430L (x86) without AES-NI (gcc Compiler Version 4.2.1)
|-
|HP-UX 11i (32 bit) (HP C/aC++ B3910B)
|-
|HP-UX 11i (32 bit) running on Intel Itanium 2 (HP C/aC++ B3910B)
|-
|HP-UX 11i (64 bit) (HP C/aC++ B3910B)
|-
|HP-UX 11i (64 bit) running on Intel Itanium 2 (HP C/aC++ B3910B)
|-
|iOS 6.0 running on Apple A5 / ARM Cortex-A9 (ARMv7) with NEON (gcc Compiler Version 4.2.1)
|-
|iOS 6.0 running on Apple A5 / ARM Cortex-A9 (ARMv7) without NEON (gcc Compiler Version 4.2.1)
|-
|iOS 8.1 32bit running on Apple A7 (ARMv8) with NEON (clang Compiler Version 600.0.56)
|-
|iOS 8.1 32-bit running on Apple A7 (ARMv8) with NEON (clang Compiler Version 600.0.56)
|-
|iOS 8.1 32bit running on Apple A7 (ARMv8) without NEON (clang Compiler Version 600.0.56)
|-
|iOS 8.1 32-bit running on Apple A7 (ARMv8) without NEON (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64bit running on Apple A7 (ARMv8) with NEON and Crypto Extensions (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64-bit running on Apple A7 (ARMv8) with NEON and Crypto Extensions (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64bit running on Apple A7 (ARMv8) without NEON and Crypto Extensions (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64-bit running on Apple A7 (ARMv8) without NEON and Crypto Extensions (clang Compiler Version 600.0.56)
|-
|iOS 8.1 64-bit running on Apple A7 (ARMv8) without NEON and Crypto Extensions (clang Compilerv Version 600.0.56)
|-
|Linux 2.6.27 (gcc Compiler Version 4.2.4)
|-
|Linux 2.6.27 running on PowerPC e300c3 (gcc Compiler Version 4.2.4)
|-
|Linux 2.6.32 (gcc Compiler Version 4.3.2)
|-
|Linux 2.6.32 running on TI AM3703CBP (ARMv7) (gcc Compiler Version 4.3.2)
|-
|Linux 2.6.33 (gcc Compiler Version 4.1.0)
|-
|Linux 2.6.33 running on PowerPC32 e300 (gcc Compiler Version 4.1.0)
|-
|Linux 2.6 (gcc Compiler Version 4.1.0)
|-
|Linux 2.6 (gcc Compiler Version 4.3.2)
|-
|Linux 2.6 running on a Nimble Storage CS300 with AES-NI
|-
|Linux 2.6 running on a Nimble Storage CS500 with AES-NI
|-
|Linux 2.6 running on a Nimble Storage CS700 with AES-NI
|-
|Linux 2.6 running on Broadcom BCM11107 (ARMv6) (gcc Compiler Version 4.3.2)
|-
|Linux 2.6 running on Freescale e500v2 (PPC) (gcc Compiler Version 4.4.1)
|-
|Linux 2.6 running on Freescale PowerPCe500 (gcc Compiler Version 4.1.0)
|-
|Linux 2.6 running on TI TMS320DM6446 (ARMv4) (gcc Compiler Version 4.3.2)
|-
|Linux 3.10 32-bit running on Intel Atom E3845 (x86) with AES-NI (gcc Compiler Version 4.8.1)
|-
|Linux 3.10 32-bit running on Intel Atom E3845 (x86) without AES-NI (gcc Compiler Version 4.8.1)
|-
|Linux 3.10 on VMware ESXi 6.00 running on Intel Xeon with AES-NI (gcc Compiler Version 4.8.3)
|-
|Linux 3.10 on Vmware ESXi 6.00 running on Intel Xeon without AES-NI (gcc Compiler Version 4.8.3)
|-
|Linux 3.10 running on Intel Xeon with AES-NI (gcc Compiler Version 4.8.3)
|-
|Linux 3.10 running on Intel Xeon without AES-NI (gcc Compiler Version 4.8.3)
|-
|Linux 3.4 64-bit under Citrix XenServer running on Intel Xeon E5-2430L (x86) without AES-NI
|-
|Linux 3.4 under Citrix XenServer 6.2 running on Intel Xeon E5-2430L with AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Citrix XenServer 6.2 running on Intel Xeon E5-2430L without AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Microsoft Windows 2012 Hyper-V running on Intel Xeon E5-2430L with AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Microsoft Windows 2012 Hyper-V running on Intel Xeon E5-2430L with AES-NI (gcc Compiler Version 4.8.0)2
|-
|Linux 3.4 under Microsoft Windows 2012 Hyper-V running on Intel Xeon E5-2430L without AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Vmware ESXi 5.1 running on Intel Xeon E5-2430L with AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.4 under Vmware ESXi 5.1 running on Intel Xeon E5-2430L without AES-NI (gcc Compiler Version 4.8.0)
|-
|Linux 3.8 running on ARM926 (ARMv5TEJ) (gcc Compiler Version 4.7.3)
|-
|Linux ORACLESP 2.6 running on ASPEED AST-Series (ARMv5) (gcc Compiler Version 4.4.5)
|-
|Linux ORACLESP 2.6 running on Emulex PILOT3 (ARMv5) (gcc Compiler Version 4.4.5)
|-
|Microsoft Windows 7 (32 bit) (Microsoft 32 bit C/C++ Optimizing Compiler Version 16.00)
|-
|Microsoft Windows 7 (32 bit) running on Intel Celeron (Microsoft 32 bit C/C++ Optimizing Compiler Version 16.00)
|-
|Microsoft Windows 7 (64 bit) (Microsoft C/C++ Optimizing Compiler Version 16.00)
|-
|Microsoft Windows 7 (64 bit) running on Intel Pentium 4 (Microsoft C/C++ Optimizing Compiler Version 16.00)
|-
|Microsoft Windows 7 running on Intel Core i5- 2430M (64-bit) with AES-NI (Microsoft ® C/C++ Optimizing Compiler Version 16.00 for x64)
|-
|Microsoft Windows 7 running on Intel Core i5-2430M (64-bit) with AES-NI (Microsoft « C/C++ Optimizing Compiler Version 16.00 for x64)
|-
|Microsoft Windows CE 5.0 (Microsoft C/C++ Optimizing Compiler Version 13.10 for ARM)
|-
|Microsoft Windows CE 5.0 running on ARMv7 (Microsoft C/C++ Optimizing Compiler Version 13.10 for ARM)
|-
|Microsoft Windows CE 6.0 (Microsoft C/C++ Optimizing Compiler Version 15.00 for ARM)
|-
|Microsoft Windows CE 6.0 running on ARMv5TEJ (Microsoft C/C++ Optimizing Compiler Version 15.00 for ARM)
|-
|Microsoft Windows Server 2008 R2 running on an Intel Xeon E5-2420 (x64) (Microsoft 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86)
|-
|NetBSD 5.1 (gcc Compiler Version 4.1.3)
|-
|NetBSD 5.1 running on Intel Xeon 5500 (gcc Compiler Version 4.1.3)
|-
|NetBSD 5.1 running on PowerPCe500 (gcc Compiler Version 4.1.3)
|-
|OpenWRT 2.6 running on MIPS 24Kc (gcc Compiler Version 4.6.3)
|-
|Oracle Linux 5 (64 bit) (gcc Compiler Version 4.1.2)
|-
|Oracle Linux 5 (64 bit) running on Intel Xeon 5675 (gcc Compiler Version 4.1.2)
|-
|Oracle Linux 5 running on Intel Xeon 5675 with AES-NI (gcc Compiler Version 4.1.2)
|-
|Oracle Linux 6 (gcc Compiler Version 4.4.6)
|-
|Oracle Linux 6 running on Intel Xeon 5675 with AES-NI (gcc Compiler Version 4.4.6)
|-
|Oracle Linux 6 running on Intel Xeon 5675 without AES-NI (gcc Compiler Version 4.4.6)
|-
|Oracle Solaris 10 (32 bit) (gcc Compiler Version 3.4.3)
|-
|Oracle Solaris 10 (32 bit) running on SPARC-T3 (SPARCv9) (gcc Compiler Version3.4.3)
|-
|Oracle Solaris 10 (64 bit) (gcc Compiler Version 3.4.3)
|-
|Oracle Solaris 10 (64 bit) running on SPARC-T3 (SPARCv9) (gcc Compiler Version 3.4.3)
|-
|Oracle Solaris 11(32 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 (32 bit) running on Intel Xeon 5675 (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 (32 bit) running on SPARC-T3 (SPARCv9) (Sun C Version 5.12)
|-
|Oracle Solaris 11 (32 bit) (Sun C Version 5.12)
|-
|Oracle Solaris 11 (64 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 (64 bit) running on Intel Xeon 5675 (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 (64 bit) running on SPARC-T3 (SPARCv9) (Sun C Version 5.12)
|-
|Oracle Solaris 11 (64 bit) (Sun C Version 5.12)
|-
|Oracle Solaris 11 running on Intel Xeon 5675 with AES-NI (32 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 running on Intel Xeon 5675 with AESNI (32 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 running on Intel Xeon 5675 with AES-NI (64 bit) (gcc Compiler Version 4.5.2)
|-
|Oracle Solaris 11 running on Intel Xeon 5675 with AESNI (64 bit) (gcc Compiler Version 4.5.2)
|-
|PexOS 1.0 under vSphere ESXi 5.1 running on Intel Xeon E52430L with AES-NI (gcc Compiler Version 4.6.3)3
|-
|PexOS 1.0 under vSphere ESXi 5.1 running on Intel Xeon E52430L without AES-NI (gcc Compiler Version 4.6.3)
|-
|QNX 6.4 running on Freescale i.MX25 (ARMv4) (gcc Compiler Version 4.3.3)
|-
|QNX 6.5 running on Freescale i.MX25 (ARMv4) (gcc Compiler Version 4.3.3)
|-
|TS-Linux 2.4 running on Arm920Tid (ARMv4) (gcc Compiler Version 4.3.2)
|-
|TS-Linux 2.4 running on Arm920Tid (ARMv4) (gcc Compiler Version 4.3.2)4
|-
|Ubuntu 10.04 (32 bit) (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 (32 bit) running on Intel Pentium T4200 (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 (64 bit) (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 (64 bit) running on Intel Pentium T4200 (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 running on Intel Core i5 with AES-NI (32 bit) (gcc Compiler Version 4.1.3)
|-
|Ubuntu 10.04 running on Intel Pentium T4200 (gcc Compiler Version 4.1.3)
|-
|Ubuntu 12.04 running on Intel Xeon E5-2430L (x86) with AES-NI (gcc Compiler Version 4.6.3)
|-
|Ubuntu 12.04 running on Intel Xeon E5-2430L (x86) without AES-NI (gcc Compiler Version 4.6.3)
|-
|Ubuntu 13.04 running on AM335x Cortex-A8 (ARMv7) (gcc Compiler Version 4.7.3)
|-
|Ubuntu 13.04 running on AM335x Cortex-A8 (ARMv7) with NEON (gcc Compiler Version 4.7.3)
|-
|Ubuntu 13.04 running on AM335x Cortex-A8 (ARMv7) without NEON (gcc Compiler Version 4.7.3)
|-
|uCLinux 0.9.29 (gcc Compiler Version 4.2.1)
|-
|uCLinux 0.9.29 running on ARM 922T (ARMv4) (gcc Compiler Version 4.2.1)
|-
|Vmware Horizon Workspace 1.5 under Vmware ESXi 5.0 running on Intel Xeon E3-1220 (x86) with AES-NI (gcc Compiler Version 4.5.1)1
|-
|Vmware Horizon Workspace 1.5 under Vmware ESXi 5.0 running on Intel Xeon E3-1220 (x86) without AES-NI (gcc Compiler Version 4.5.1)
|-
|Vmware Horizon Workspace 2.1 under vSphere ESXi 5.5 running on Intel Xeon E3-1220 (x86) with AES-NI (gcc Compiler Version 4.5.1)
|-
|Vmware Horizon Workspace 2.1 under vSphere ESXi 5.5 running on Intel Xeon E3-1220 (x86) with AESNI (gcc Compiler Version 4.5.1)
|-
|Vmware Horizon Workspace 2.1 under vSphere ESXi 5.5 running on Intel Xeon E3-1220 (x86) without AES-NI (gcc Compiler Version 4.5.1)
|-
|VxWorks 6.7 running on Intel Core 2 Duo (x86) (gcc Compiler Version 4.1.2)
|-
|VxWorks 6.8 (gcc Compiler Version 4.1.2)
|-
|VxWorks 6.8 running on TI TNETV1050 (MIPS) (gcc Compiler Version 4.1.2)
|-
|VxWorks 6.9 running on Freescale P2020 (PPC) (gcc Compiler Version 4.3.3)
|-
|Windows Embedded Compact 7 running on Freescale i.MX53xA (ARMv7) with NEON (Microsoft C/C++ Optimizing Compiler Version 15.00.20720)
|-
|Windows Embedded Compact 7 running on Freescale i.MX53xD (ARMv7) with NEON (Microsoft C/C++ Optimizing Compiler Version 15.00.20720)
|}

OpenSSL 3.0

2021-05-02T13:05:03Z

Mspncp: /* 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.

'''READ ME FIRST:'''

The project is planning on having a FIPS 140-2 (not 140-3) validated module which means that the schedule is driven by the NIST deadline for 140-2 which is near the end of September, 2021.

The team is focused on development, and this page is somewhat out of date, in terms of content and schedule. It is expected that much of the content here will be in the FIPS, or other, documentation in the 3.0 release. This is being started in [https://github.com/openssl/openssl/pull/14710 PR 14710].

The current list of items being worked on, can be found at their [https://app.zenhub.com/workspaces/300-beta-1-573bc8d2d31e1e9a73fff29f/board?repos=7634677 OpenSSL Project Kanban Board on ZenHub].

You can also search GitHub issues for the list of [https://github.com/openssl/openssl/issues?q=is%3Aopen+label%3A%22triaged%3A+OTC+evaluated%22+milestone%3A%223.0.0+beta1%22 items that must be done for 3.0 ("blockers")] and the list of [https://github.com/openssl/openssl/issues?page=1&q=is%3Aopen+label%3A%22triaged%3A+OTC+evaluated%22+no%3Amilestone Items that are "nice to have" but not committed].

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

OpenSSL 3.0

2021-04-27T16:06:42Z

Mspncp:

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

'''READ ME FIRST:'''

The project is planning on having a FIPS 140-2 (not 140-3) validated module which means that the schedule is driven by the NIST deadline for 140-2 which is near the end of September, 2021.

The team is focused on development, and this page is somewhat out of date, in terms of content and schedule. It is expected that much of the content here will be in the FIPS, or other, documentation in the 3.0 release.

The current list of items being worked on, can be found at their [https://app.zenhub.com/workspaces/300-beta-1-573bc8d2d31e1e9a73fff29f/board?repos=7634677 OpenSSL Project Kanban Board on ZenHub].

You can also search GitHub issues for the list of [https://github.com/openssl/openssl/issues?q=is%3Aopen+label%3A%22triaged%3A+OTC+evaluated%22+milestone%3A%223.0.0+beta1%22 items that must be done for 3.0 ("blockers")] and the list of [https://github.com/openssl/openssl/issues?page=1&q=is%3Aopen+label%3A%22triaged%3A+OTC+evaluated%22+no%3Amilestone Items that are "nice to have" but not committed].

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

'''Update:''' 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 new documentation can be previewed in the [https://github.com/openssl/openssl/blob/92010acff9e9e32b8c183079a70d164759eeb62a/README-FIPS.md README-FIPS] file of pull request [https://github.com/openssl/openssl/pull/13684 #13684]. 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
|}

OpenSSL 3.0

2021-04-27T16:03:53Z

Mspncp: Pimp the 'READ ME FIRST'

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

'''READ ME FIRST:'''

The project is planning on having a FIPS 140-2 (not 140-3) validated module which means that the schedule is driven by the NIST deadline for 140-2 which is near the end of September, 2021.

The team is focused on development, and this page is somewhat out of date, in terms of content and schedule. It is expected that much of the content here will be in the FIPS, or other, documentation in the 3.0 release.

The current list of items being worked on, can be found at their [https://app.zenhub.com/workspaces/300-beta-1-573bc8d2d31e1e9a73fff29f/board?repos=7634677 OpenSSL Project Kanban Board on ZenHub]. You can also search GitHub issues for the list of [https://github.com/openssl/openssl/issues?q=is%3Aopen+label%3A%22triaged%3A+OTC+evaluated%22+milestone%3A%223.0.0+beta1%22 items that must be done for 3.0 ("blockers")] and the list of [https://github.com/openssl/openssl/issues?page=1&q=is%3Aopen+label%3A%22triaged%3A+OTC+evaluated%22+no%3Amilestone Items that are "nice to have" but not committed].

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

'''Update:''' 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 new documentation can be previewed in the [https://github.com/openssl/openssl/blob/92010acff9e9e32b8c183079a70d164759eeb62a/README-FIPS.md README-FIPS] file of pull request [https://github.com/openssl/openssl/pull/13684 #13684]. 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
|}

OpenSSL 3.0

2021-04-27T15:51:02Z

Mspncp: /* 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.

'''READ ME FIRST:'''

The project is planning on having a FIPS 140-2 (not 140-3) validated module which means that the schedule is driven by the NIST deadline for 140-2 which is near the end of September, 2021.

The team is focused on development, and this page is somewhat out of date, in terms of content and schedule. It is expected that much of the content here will be in the FIPS, or other, documentation in the 3.0 release.

The current list of items being worked on, can be found at their Kanban board, [https://app.zenhub.com/workspaces/300-beta-1-573bc8d2d31e1e9a73fff29f/board?repos=7634677]. The list of items that must be done for 3.0 ("blockers") can be found at [https://github.com/openssl/openssl/issues?q=is%3Aopen+label%3A%22triaged%3A+OTC+evaluated%22+milestone%3A%223.0.0+beta1%22]. The list of items that are "nice to have" but not committed can be found at [https://github.com/openssl/openssl/issues?page=1&q=is%3Aopen+label%3A%22triaged%3A+OTC+evaluated%22+no%3Amilestone]

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

'''Update:''' 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 new documentation can be previewed in the [https://github.com/openssl/openssl/blob/92010acff9e9e32b8c183079a70d164759eeb62a/README-FIPS.md README-FIPS] file of pull request [https://github.com/openssl/openssl/pull/13684 #13684]. 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
|}

OpenSSL 3.0

2020-09-15T22:54:15Z

Mspncp: Renamed OPENSSL_CTX to OSSL_LIB_CTX, anticipating the OpenSSL 3.0.0 alpha1 release. (Added a comment about the renaming and a link to the older revision.)

__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

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, the OSSL_LIB_CTX was called OPENSSL_CTX. It was renamed for OpenSSL 3.0.0 beta1. If you are still using an alpha release, 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-06-20T21:58:20Z

Mspncp: /* Loading the FIPS module at the same time as other providers */ Fix typo in openssl.cnf

__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 4 different providers as standard. Over time third parties may distribute additional providers that can be plugged into OpenSSL. All algorithm implementations available via providers are accessed through the "EVP" set of APIs. They cannot be accessed using the "low level" APIs (see below).

=== Low Level APIs ===

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

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

=== Legacy Algorithms ===

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

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

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

=== Versioning Scheme ===

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

MAJOR.MINOR.PATCH

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

=== Other major new features ===

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

=== Other notable deprecations and changes ===

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

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

== Installation and Compilation of OpenSSL 3.0 ==

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

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

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

RELEASE_DATE=23 Apr 2020

== Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 ==

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

1) Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL.

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

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

== Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 ==

Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more difficult. In addition to the issues discussed above in the section about upgrading from 1.1.1, the main things to be aware of are:

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

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

For example code that previously looked like this:

EVP_MD_CTX md_ctx;

EVP_MD_CTX_init(&md_ctx);

/* Do something with the md_ctx */

will now generate compiler errors. For example:

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

The code needs to be amended to look like this:

EVP_MD_CTX *md_ctx;

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

/* Do something with the md_ctx */

EVP_MD_CTX_free(md_ctx);

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

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

=== Upgrading from the OpenSSL 2.0 FIPS Object Module ===

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

The function calls 'FIPS_mode()' and 'FIPS_mode_set()' 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.

Note that default properties are not currently functional in the OpenSSL 3.0 alpha 1 or alpha 2 releases.

== 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");

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

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

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

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

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

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

openssl_conf = openssl_init

.include /usr/local/ssl/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-05-09T21:30:35Z

Mspncp: /* 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.

=== Providers and FIPS support ===

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

=== Low Level APIs ===

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

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

=== Legacy Algorithms ===

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

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

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

=== Versioning Scheme ===

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

MAJOR.MINOR.PATCH

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

=== Other major new features ===

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

=== Other notable deprecations and changes ===

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

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

== Installation and Compilation of OpenSSL 3.0 ==

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

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

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

RELEASE_DATE=23 Apr 2020

== Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 ==

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

1) Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL.

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

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

== Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 ==

Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more difficult. In addition to the issues discussed above in the section about upgrading from 1.1.1, the main things to be aware of are:

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

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

For example code that previously looked like this:

EVP_MD_CTX md_ctx;

EVP_MD_CTX_init(&md_ctx);

/* Do something with the md_ctx */

will now generate compiler errors. For example:

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

The code needs to be amended to look like this:

EVP_MD_CTX *md_ctx;

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

/* Do something with the md_ctx */

EVP_MD_CTX_free(md_ctx);

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

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

=== Upgrading from the OpenSSL 2.0 FIPS Object Module ===

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

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

== Completing the installation of the FIPS Module ==

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

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

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

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

For example, to install the FIPS module to its default location:

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

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.

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

== Using the FIPS Module in applications ==

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

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

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

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

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

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

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

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

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

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

openssl_conf = openssl_init

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

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

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

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

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

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

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

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

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

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

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

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

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

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

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

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

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

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

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

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

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

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

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

EVP_MD *sha256;

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

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

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

EVP_MD *sha256;

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

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

EVP_set_default_properties(NULL, "fips=yes");

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

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

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

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

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

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

openssl_conf = openssl_init

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

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

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

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

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

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

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

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

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

/* As an example get some digests */

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

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

/* Use the digests */

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

return ret;

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

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

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

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

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

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

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

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

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

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

== Openssl command line application changes ==

The following additional command line arguments have been added

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

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

== STATUS of current development ==



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



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

=== Known issues ===

==== Building and testing ====

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

==== Integration ====

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

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

==== Programming ====

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

==== SSL/TLS ====

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

=== Platforms ===

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

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

=== Features ===

All the core support features are in.

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

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

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

==== Provider implemented ciphers ====

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

==== Provider implemented digests ====

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

==== Provider implemented MACs ====

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

==== Provider implemented KDFs ====

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

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

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

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

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

==== Provider implemented signature ====

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

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

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

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

===== Serializers =====

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

===== Deserializers =====

TO BE ADDED

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

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

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

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

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

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

OpenSSL 3.0

2020-05-09T20:37:00Z

Mspncp: /* 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.

=== Providers and FIPS support ===

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

=== Low Level APIs ===

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

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

=== Legacy Algorithms ===

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

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

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

=== Versioning Scheme ===

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

MAJOR.MINOR.PATCH

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

=== Other major new features ===

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

=== Other notable deprecations and changes ===

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

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

== Installation and Compilation of OpenSSL 3.0 ==

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

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

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

RELEASE_DATE=23 Apr 2020

== Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 ==

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

1) Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL.

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

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

== Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 ==

Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more difficult. In addition to the issues discussed above in the section about upgrading from 1.1.1, the main things to be aware of are:

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

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

For example code that previously looked like this:

EVP_MD_CTX md_ctx;

EVP_MD_CTX_init(&md_ctx);

/* Do something with the md_ctx */

will now generate compiler errors. For example:

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

The code needs to be amended to look like this:

EVP_MD_CTX *md_ctx;

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

/* Do something with the md_ctx */

EVP_MD_CTX_free(md_ctx);

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

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

=== Upgrading from the OpenSSL 2.0 FIPS Object Module ===

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

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

== Completing the installation of the FIPS Module ==

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

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

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

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

For example, to install the FIPS module to its default location:

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

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 <openssl/provider.h>

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

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

/* Rest of application */

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

=== Fetching algorithms and property queries ===

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

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

EVP_MD_CTX *mdctx;

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

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

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

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

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

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

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

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

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

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

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

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

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

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

== Using the FIPS Module in applications ==

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

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

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

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

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

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

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

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

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

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

openssl_conf = openssl_init

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

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

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

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

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

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

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

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

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

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

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

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

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

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

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

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

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

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

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

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

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

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

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

EVP_MD *sha256;

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

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

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

EVP_MD *sha256;

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

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

EVP_set_default_properties(NULL, "fips=yes");

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

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

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

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

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

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

openssl_conf = openssl_init

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

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

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

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

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

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

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

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

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

/* As an example get some digests */

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

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

/* Use the digests */

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

return ret;

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

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

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

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

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

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

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

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

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

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

== Openssl command line application changes ==

The following additional command line arguments have been added

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

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

== STATUS of current development ==



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



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

=== Known issues ===

==== Building and testing ====

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

==== Integration ====

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

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

==== Programming ====

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

==== SSL/TLS ====

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

=== Platforms ===

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

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

=== Features ===

All the core support features are in.

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

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

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

==== Provider implemented ciphers ====

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

==== Provider implemented digests ====

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

==== Provider implemented MACs ====

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

==== Provider implemented KDFs ====

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

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

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

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

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

==== Provider implemented signature ====

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

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

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

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

===== Serializers =====

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

===== Deserializers =====

TO BE ADDED

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

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

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

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

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

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

OpenSSL 3.0

2020-04-23T17:00:26Z

Mspncp: /* Upgrading from the the OpenSSL 2.0 FIPS Object 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.

=== Providers and FIPS support ===

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

=== Low Level APIs ===

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

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

=== Legacy Algorithms ===

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

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

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

=== Versioning Scheme ===

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

MAJOR.MINOR.PATCH

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

=== Other major new features ===

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

== 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. Please edit the VERSION file in the top of the distribution to remove the quotes around the date on the RELEASE_DATE line, i.e. that line should look like this:

RELEASE_DATE=23 Apr 2020

== Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 ==

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

1) Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL.

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

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

== Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 ==

Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more difficult. In addition to the issues discussed above in the section about upgrading from 1.1.1, the main things to be aware of are:

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

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

For example code that previously looked like this:

EVP_MD_CTX md_ctx;

EVP_MD_CTX_init(&md_ctx);

/* Do something with the md_ctx */

will now generate compiler errors. For example:

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

The code needs to be amended to look like this:

EVP_MD_CTX *md_ctx;

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

/* Do something with the md_ctx */

EVP_MD_CTX_free(md_ctx);

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

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

=== Upgrading from the OpenSSL 2.0 FIPS Object Module ===

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

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

== Completing the installation of the FIPS Module ==

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

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

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

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

For example, to install the module:

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

== Programming in OpenSSL 3.0 ==

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

=== Library Contexts ===

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

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

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

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

=== Providers ===

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

The standard providers are:

* The default provider. This collects together all of the standard built-in OpenSSL algorithm implementations. If an application doesn't specify anything else explicitly (e.g. in the application or via config), then this is the provider that will be used. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. If another provider has already been loaded then it won't be loaded automatically. Therefore if you want to use it in conjunction with other providers then you must load it explicitly. This is a "built-in" provider which means that it is built into libcrypto and does not exist as a separate standalone module.

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

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

* The null provider. This provider is "built-in" to libcrypto and contains no algorithm implementations. In order to guarantee that the default provider is not automatically loaded, the null provider can be loaded instead. This can be useful if you are using non-default library contexts and want to ensure that the default library context is never used "by accident".

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

#include <openssl/provider.h>

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

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

/* Rest of application */

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

=== Fetching algorithms and property queries ===

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

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

EVP_MD_CTX *mdctx;

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

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

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

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

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

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

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

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

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

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

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

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

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

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

== Using the FIPS Module in applications ==

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

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

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

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

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

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

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

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

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

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

openssl_conf = openssl_init

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

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

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

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

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

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

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

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

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

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

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

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

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

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

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

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

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

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

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

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

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

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

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

EVP_MD *sha256;

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

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

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

EVP_MD *sha256;

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

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

EVP_set_default_properties(NULL, "fips=yes");

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

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

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

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

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

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

openssl_conf = openssl_init

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

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

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

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

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

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

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

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

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

/* As an example get some digests */

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

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

/* Use the digests */

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

return ret;

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

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

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

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

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

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

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

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

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

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

== Openssl command line application changes ==

The following additional command line arguments have been added

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

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

== STATUS of current development ==



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



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

=== Known issues ===

==== Building and testing ====

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

==== Integration ====

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

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

==== Programming ====

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

==== SSL/TLS ====

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

=== Platforms ===

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

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

=== Features ===

All the core support features are in.

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

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

==== Provider implemented ciphers ====

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

==== Provider implemented digests ====

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

==== Provider implemented MACs ====

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

==== Provider implemented KDFs ====

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

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

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

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

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

==== Provider implemented signature ====

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

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

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

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

===== Serializers =====

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

===== Deserializers =====

TO BE ADDED

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

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

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

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

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

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

OpenSSL 3.0

2020-04-23T16:59:02Z

Mspncp: /* Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 */ Add link to OpenSSL 1.1.0 Changes page

__NUMBEREDHEADINGS__ 

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

== Main Changes in OpenSSL 3.0 from OpenSSL 1.1.1 ==

=== Major Release ===

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

=== Providers and FIPS support ===

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

=== Low Level APIs ===

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

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

=== Legacy Algorithms ===

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

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

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

=== Versioning Scheme ===

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

MAJOR.MINOR.PATCH

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

=== Other major new features ===

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

== 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. Please edit the VERSION file in the top of the distribution to remove the quotes around the date on the RELEASE_DATE line, i.e. that line should 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 the OpenSSL 2.0 FIPS Object Module ===

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

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

== Completing the installation of the FIPS Module ==

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

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

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

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

For example, to install the module:

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

== Programming in OpenSSL 3.0 ==

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

=== Library Contexts ===

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

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

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

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

=== Providers ===

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

The standard providers are:

* The default provider. This collects together all of the standard built-in OpenSSL algorithm implementations. If an application doesn't specify anything else explicitly (e.g. in the application or via config), then this is the provider that will be used. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. If another provider has already been loaded then it won't be loaded automatically. Therefore if you want to use it in conjunction with other providers then you must load it explicitly. This is a "built-in" provider which means that it is built into libcrypto and does not exist as a separate standalone module.

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

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

* The null provider. This provider is "built-in" to libcrypto and contains no algorithm implementations. In order to guarantee that the default provider is not automatically loaded, the null provider can be loaded instead. This can be useful if you are using non-default library contexts and want to ensure that the default library context is never used "by accident".

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

#include <openssl/provider.h>

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

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

/* Rest of application */

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

=== Fetching algorithms and property queries ===

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

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

EVP_MD_CTX *mdctx;

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

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

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

EVP_MD_CTX *mdctx;
EVP_MD *sha256;

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

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

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

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

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

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

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

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

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

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

== Using the FIPS Module in applications ==

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

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

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

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

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

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

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

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

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

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

openssl_conf = openssl_init

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

[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect

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

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

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

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

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

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

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

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

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

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

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

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

#include <openssl/provider.h>

int main(void)
{
OSSL_PROVIDER *fips;

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

/* Rest of application */

OSSL_PROVIDER_unload(fips);
exit(EXIT_SUCCESS);
}

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

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

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

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

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

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

EVP_MD *sha256;

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

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

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

EVP_MD *sha256;

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

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

EVP_set_default_properties(NULL, "fips=yes");

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

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

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

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

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

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

openssl_conf = openssl_init

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

[openssl_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

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

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

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

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

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

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

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

/* As an example get some digests */

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

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

/* Use the digests */

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

return ret;

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

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

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

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

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

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

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

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

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

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

== Openssl command line application changes ==

The following additional command line arguments have been added

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

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

== STATUS of current development ==



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



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

=== Known issues ===

==== Building and testing ====

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

==== Integration ====

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

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

==== Programming ====

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

==== SSL/TLS ====

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

=== Platforms ===

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

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

=== Features ===

All the core support features are in.

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

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

==== Provider implemented ciphers ====

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

==== Provider implemented digests ====

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

==== Provider implemented MACs ====

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

==== Provider implemented KDFs ====

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

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

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

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

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

==== Provider implemented signature ====

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

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

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

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

===== Serializers =====

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

===== Deserializers =====

TO BE ADDED

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

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

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

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

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

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

EVP Authenticated Encryption and Decryption

2019-04-30T15:07:32Z

Mspncp:

{{DocInclude
|Name=Authenticated Encryption and Decryption
|Url=http://wiki.openssl.org/index.php/Manual:Evp(3)
|Include=evp.h}}

The EVP interface supports the ability to perform authenticated encryption and decryption, as well as the option to attach unencrypted, associated data to the message. Such Authenticated-Encryption with Associated-Data (AEAD) schemes provide confidentiality by encrypting the data, and also provide authenticity assurances by creating a MAC tag over the encrypted data. The MAC tag will ensure the data is not accidentally altered or maliciously tampered during transmission and storage.

There are a number of AEAD modes of operation. The modes include EAX, CCM and GCM mode. Using AEAD modes is nearly identical to using standard symmetric encryption modes like CBC, CFB and OFB modes.

As with standard symmetric encryption you will need to know the following:

* Algorithm (currently only AES is supported)
* Mode (currently only GCM and CCM are supported)
* Key
* Initialisation Vector (IV)

In addition you can (optionally) provide some ''Additional Authenticated Data'' (AAD). The AAD data is not encrypted, and is typically passed to the recipient in plaintext along with the ciphertext. An example of AAD is the IP address and port number in a IP header used with IPsec.

The output from the encryption operation will be the ciphertext, and a tag. The tag is subsequently used during the decryption operation to ensure that the ciphertext and AAD have not been tampered with.

The OpenSSL manual describes the usage of the GCM and CCM modes here: [[Manual:EVP_EncryptInit(3)#GCM_Mode]].

The complete source code of the following examples can be downloaded as [[Media:evp-gcm-encrypt.c|evp-gcm-encrypt.c]] resp. [[Media:evp-ccm-encrypt.c|evp-ccm-encrypt.c]].

==Authenticated Encryption using GCM mode==

Encryption is performed in much the same way as for symmetric encryption as described [[EVP Symmetric Encryption and Decryption|here]]. The main differences are:
* You may optionally pass through an IV length using EVP_CIPHER_CTX_ctrl
* AAD data is passed through in zero or more calls to EVP_EncryptUpdate, with the output buffer set to NULL
* After the EVP_EncryptFinal_ex call a new call to EVP_CIPHER_CTX_ctrl retrieves the tag

See the code below for an example:
<pre>
int gcm_encrypt(unsigned char *plaintext, int plaintext_len,
unsigned char *aad, int aad_len,
unsigned char *key,
unsigned char *iv, int iv_len,
unsigned char *ciphertext,
unsigned char *tag)
{
EVP_CIPHER_CTX *ctx;

int len;

int ciphertext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/* Initialise the encryption operation. */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL))
handleErrors();

/*
* Set IV length if default 12 bytes (96 bits) is not appropriate
*/
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, iv_len, NULL))
handleErrors();

/* Initialise key and IV */
if(1 != EVP_EncryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/*
* Provide any AAD data. This can be called zero or more times as
* required
*/
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

/*
* Provide the message to be encrypted, and obtain the encrypted output.
* EVP_EncryptUpdate can be called multiple times if necessary
*/
if(1 != EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len))
handleErrors();
ciphertext_len = len;

/*
* Finalise the encryption. Normally ciphertext bytes may be written at
* this stage, but this does not occur in GCM mode
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len))
handleErrors();
ciphertext_len += len;

/* Get the tag */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, 16, tag))
handleErrors();

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}
</pre>

==Authenticated Decryption using GCM mode==

Again, the decryption operation is much the same as for normal symmetric decryption as described [[EVP Symmetric Encryption and Decryption|here]]. The main differences are:
* You may optionally pass through an IV length using EVP_CIPHER_CTX_ctrl
* AAD data is passed through in zero or more calls to EVP_DecryptUpdate, with the output buffer set to NULL
* Prior to the EVP_DecryptFinal_ex call a new call to EVP_CIPHER_CTX_ctrl provides the tag
* A non positive return value from EVP_DecryptFinal_ex should be considered as a failure to authenticate ciphertext and/or AAD. It does not necessarily indicate a more serious error.

See the code example below:

<pre>
int gcm_decrypt(unsigned char *ciphertext, int ciphertext_len,
unsigned char *aad, int aad_len,
unsigned char *tag,
unsigned char *key,
unsigned char *iv, int iv_len,
unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;
int len;
int plaintext_len;
int ret;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/* Initialise the decryption operation. */
if(!EVP_DecryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL))
handleErrors();

/* Set IV length. Not necessary if this is 12 bytes (96 bits) */
if(!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, iv_len, NULL))
handleErrors();

/* Initialise key and IV */
if(!EVP_DecryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/*
* Provide any AAD data. This can be called zero or more times as
* required
*/
if(!EVP_DecryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

/*
* Provide the message to be decrypted, and obtain the plaintext output.
* EVP_DecryptUpdate can be called multiple times if necessary
*/
if(!EVP_DecryptUpdate(ctx, plaintext, &len, ciphertext, ciphertext_len))
handleErrors();
plaintext_len = len;

/* Set expected tag value. Works in OpenSSL 1.0.1d and later */
if(!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, 16, tag))
handleErrors();

/*
* Finalise the decryption. A positive return value indicates success,
* anything else is a failure - the plaintext is not trustworthy.
*/
ret = EVP_DecryptFinal_ex(ctx, plaintext + len, &len);

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

if(ret > 0) {
/* Success */
plaintext_len += len;
return plaintext_len;
} else {
/* Verify failed */
return -1;
}
}
</pre>

==Authenticated Encryption using CCM mode==

Encryption with CCM mode is much the same as for encryption with GCM but with some additional things to bear in mind.
* you can only call EVP_EncryptUpdate once for AAD and once for the plaintext.
* The total plaintext length must be passed to EVP_EncryptUpdate (only needed if AAD is passed)
* Optionally the tag and IV length can also be passed. If they are not then the defaults are used (12 bytes for AES tags, and 7 bytes for AES IVs)

See the code below for an example:
<pre>
int ccm_encrypt(unsigned char *plaintext, int plaintext_len,
unsigned char *aad, int aad_len,
unsigned char *key,
unsigned char *iv,
unsigned char *ciphertext,
unsigned char *tag)
{
EVP_CIPHER_CTX *ctx;

int len;

int ciphertext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/* Initialise the encryption operation. */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_ccm(), NULL, NULL, NULL))
handleErrors();

/*
* Setting IV len to 7. Not strictly necessary as this is the default
* but shown here for the purposes of this example.
*/
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, 7, NULL))
handleErrors();

/* Set tag length */
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, 14, NULL);

/* Initialise key and IV */
if(1 != EVP_EncryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/* Provide the total plaintext length */
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, NULL, plaintext_len))
handleErrors();

/* Provide any AAD data. This can be called zero or one times as required */
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

/*
* Provide the message to be encrypted, and obtain the encrypted output.
* EVP_EncryptUpdate can only be called once for this.
*/
if(1 != EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len))
handleErrors();
ciphertext_len = len;

/*
* Finalise the encryption. Normally ciphertext bytes may be written at
* this stage, but this does not occur in CCM mode.
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len))
handleErrors();
ciphertext_len += len;

/* Get the tag */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_GET_TAG, 14, tag))
handleErrors();

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}
</pre>

==Authenticated Decryption using CCM mode==

Decryption with CCM mode is much the same as for decryption with CCM but with some additional things to bear in mind.
* you can only call EVP_DecryptUpdate once for AAD and once for the plaintext.
* The total ciphertext length must be passed to EVP_DecryptUpdate (only needed if AAD is passed)
* Optionally the tag and IV length can also be passed. If they are not then the defaults are used (12 bytes for AES tags, and 7 bytes for AES IVs)
* The tag verify is performed when you call the final EVP_DecryptUpdate and is reflected by the return value: there is no call to EVP_DecryptFinal.

See the code below for an example:
<pre>
int ccm_decrypt(unsigned char *ciphertext, int ciphertext_len,
unsigned char *aad, int aad_len,
unsigned char *tag,
unsigned char *key,
unsigned char *iv,
unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;
int len;
int plaintext_len;
int ret;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/* Initialise the decryption operation. */
if(1 != EVP_DecryptInit_ex(ctx, EVP_aes_256_ccm(), NULL, NULL, NULL))
handleErrors();

/* Setting IV len to 7. Not strictly necessary as this is the default
* but shown here for the purposes of this example */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, 7, NULL))
handleErrors();

/* Set expected tag value. */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, 14, tag))
handleErrors();

/* Initialise key and IV */
if(1 != EVP_DecryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/* Provide the total ciphertext length */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, NULL, ciphertext_len))
handleErrors();

/* Provide any AAD data. This can be called zero or more times as required */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

/*
* Provide the message to be decrypted, and obtain the plaintext output.
* EVP_DecryptUpdate can be called multiple times if necessary
*/
ret = EVP_DecryptUpdate(ctx, plaintext, &len, ciphertext, ciphertext_len);

plaintext_len = len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

if(ret > 0) {
/* Success */
return plaintext_len;
} else {
/* Verify failed */
return -1;
}
}
</pre>

== Potential Issue in AES/GCM ==

Early versions of the authenticated encryption interface required using a 0-sized array (not a NULL array) to arrive at the proper authentication tag '''''when''''' the authentication tag size was ''not'' a multiple of the block size (for example, an authentication tag size of 20 bytes). For more information on the issue and the work-arounds, see [http://rt.openssl.org/Ticket/Display.html?id=2859 Issue #2859: Possible bug in AES GCM mode] and [http://groups.google.com/d/msg/mailing.openssl.users/idg9Z22MYZs/Jqlo8dA-2tMJ Possible bug in GCM/GMAC with (just) AAD of size unequal to block size].

==See also==
* [[EVP]]
* [[Libcrypto API]]
* [[EVP Symmetric Encryption and Decryption]]
* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
* [[EVP Signing and Verifying]]
* [[EVP Message Digests]]
* [[EVP Key Agreement]]
* [[EVP Key and Parameter Generation]]

[[Category:Crypto API]]
[[Category:C level]]
[[Category:Examples]]

File:Evp-gcm-encrypt.c

2019-04-30T15:04:47Z

Mspncp: Mspncp uploaded a new version of File:Evp-gcm-encrypt.c

(EVP GCM Authenticated Encryption and Decryption - C sample)

EVP Authenticated Encryption and Decryption

2019-04-30T14:12:12Z

Mspncp: (Reformat code according to OpenSSL coding style and provide downloadable sample C files)

{{DocInclude
|Name=Authenticated Encryption and Decryption
|Url=http://wiki.openssl.org/index.php/Manual:Evp(3)
|Include=evp.h}}

The EVP interface supports the ability to perform authenticated encryption and decryption, as well as the option to attach unencrypted, associated data to the message. Such Authenticated-Encryption with Associated-Data (AEAD) schemes provide confidentiality by encrypting the data, and also provide authenticity assurances by creating a MAC tag over the encrypted data. The MAC tag will ensure the data is not accidentally altered or maliciously tampered during transmission and storage.

There are a number of AEAD modes of operation. The modes include EAX, CCM and GCM mode. Using AEAD modes is nearly identical to using standard symmetric encryption modes like CBC, CFB and OFB modes.

As with standard symmetric encryption you will need to know the following:

* Algorithm (currently only AES is supported)
* Mode (currently only GCM and CCM are supported)
* Key
* Initialisation Vector (IV)

In addition you can (optionally) provide some ''Additional Authenticated Data'' (AAD). The AAD data is not encrypted, and is typically passed to the recipient in plaintext along with the ciphertext. An example of AAD is the IP address and port number in a IP header used with IPsec.

The output from the encryption operation will be the ciphertext, and a tag. The tag is subsequently used during the decryption operation to ensure that the ciphertext and AAD have not been tampered with.

The OpenSSL manual describes the usage of the GCM and CCM modes here: [[Manual:EVP_EncryptInit(3)#GCM_Mode]].

The complete source code of the following examples can be downloaded as [[Media:evp-gcm-encrypt.c|evp-gcm-encrypt.c]] resp. [[Media:evp-ccm-encrypt.c|evp-ccm-encrypt.c]].

==Authenticated Encryption using GCM mode==

Encryption is performed in much the same way as for symmetric encryption as described [[EVP Symmetric Encryption and Decryption|here]]. The main differences are:
* You may optionally pass through an IV length using EVP_CIPHER_CTX_ctrl
* AAD data is passed through in zero or more calls to EVP_EncryptUpdate, with the output buffer set to NULL
* After the EVP_EncryptFinal_ex call a new call to EVP_CIPHER_CTX_ctrl retrieves the tag

See the code below for an example:
<pre>
int gcm_encrypt(unsigned char *plaintext, int plaintext_len,
unsigned char *aad, int aad_len,
unsigned char *key,
unsigned char *iv, int iv_len,
unsigned char *ciphertext,
unsigned char *tag)
{
EVP_CIPHER_CTX *ctx;

int len;

int ciphertext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/* Initialise the encryption operation. */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL))
handleErrors();

/* Set IV length if default 12 bytes (96 bits) is not appropriate */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, iv_len, NULL))
handleErrors();

/* Initialise key and IV */
if(1 != EVP_EncryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/*
* Provide any AAD data. This can be called zero or more times as
* required
*/
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

/*
* Provide the message to be encrypted, and obtain the encrypted output.
* EVP_EncryptUpdate can be called multiple times if necessary
*/
if(1 != EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len))
handleErrors();
ciphertext_len = len;

/*
* Finalise the encryption. Normally ciphertext bytes may be written at
* this stage, but this does not occur in GCM mode
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len)) handleErrors();
ciphertext_len += len;

/* Get the tag */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, 16, tag))
handleErrors();

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}
</pre>

==Authenticated Decryption using GCM mode==

Again, the decryption operation is much the same as for normal symmetric decryption as described [[EVP Symmetric Encryption and Decryption|here]]. The main differences are:
* You may optionally pass through an IV length using EVP_CIPHER_CTX_ctrl
* AAD data is passed through in zero or more calls to EVP_DecryptUpdate, with the output buffer set to NULL
* Prior to the EVP_DecryptFinal_ex call a new call to EVP_CIPHER_CTX_ctrl provides the tag
* A non positive return value from EVP_DecryptFinal_ex should be considered as a failure to authenticate ciphertext and/or AAD. It does not necessarily indicate a more serious error.

See the code example below:

<pre>
int gcm_decrypt(unsigned char *ciphertext, int ciphertext_len,
unsigned char *aad, int aad_len,
unsigned char *tag,
unsigned char *key,
unsigned char *iv, int iv_len,
unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;
int len;
int plaintext_len;
int ret;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new())) handleErrors();

/* Initialise the decryption operation. */
if(!EVP_DecryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL))
handleErrors();

/* Set IV length. Not necessary if this is 12 bytes (96 bits) */
if(!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, iv_len, NULL))
handleErrors();

/* Initialise key and IV */
if(!EVP_DecryptInit_ex(ctx, NULL, NULL, key, iv)) handleErrors();

/*
* Provide any AAD data. This can be called zero or more times as
* required
*/
if(!EVP_DecryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

/*
* Provide the message to be decrypted, and obtain the plaintext output.
* EVP_DecryptUpdate can be called multiple times if necessary
*/
if(!EVP_DecryptUpdate(ctx, plaintext, &len, ciphertext, ciphertext_len))
handleErrors();
plaintext_len = len;

/* Set expected tag value. Works in OpenSSL 1.0.1d and later */
if(!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, 16, tag))
handleErrors();

/*
* Finalise the decryption. A positive return value indicates success,
* anything else is a failure - the plaintext is not trustworthy.
*/
ret = EVP_DecryptFinal_ex(ctx, plaintext + len, &len);

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

if(ret > 0) {
/* Success */
plaintext_len += len;
return plaintext_len;
} else {
/* Verify failed */
return -1;
}
}
</pre>

==Authenticated Encryption using CCM mode==

Encryption with CCM mode is much the same as for encryption with GCM but with some additional things to bear in mind.
* you can only call EVP_EncryptUpdate once for AAD and once for the plaintext.
* The total plaintext length must be passed to EVP_EncryptUpdate (only needed if AAD is passed)
* Optionally the tag and IV length can also be passed. If they are not then the defaults are used (12 bytes for AES tags, and 7 bytes for AES IVs)

See the code below for an example:
<pre>
int ccm_encrypt(unsigned char *plaintext, int plaintext_len,
unsigned char *aad, int aad_len,
unsigned char *key,
unsigned char *iv,
unsigned char *ciphertext,
unsigned char *tag)
{
EVP_CIPHER_CTX *ctx;

int len;

int ciphertext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/* Initialise the encryption operation. */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_ccm(), NULL, NULL, NULL))
handleErrors();

/*
* Setting IV len to 7. Not strictly necessary as this is the default
* but shown here for the purposes of this example.
*/
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, 7, NULL))
handleErrors();

/* Set tag length */
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, 14, NULL);

/* Initialise key and IV */
if(1 != EVP_EncryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/* Provide the total plaintext length */
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, NULL, plaintext_len))
handleErrors();

/* Provide any AAD data. This can be called zero or one times as required */
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

/*
* Provide the message to be encrypted, and obtain the encrypted output.
* EVP_EncryptUpdate can only be called once for this.
*/
if(1 != EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len))
handleErrors();
ciphertext_len = len;

/*
* Finalise the encryption. Normally ciphertext bytes may be written at
* this stage, but this does not occur in CCM mode.
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len))
handleErrors();
ciphertext_len += len;

/* Get the tag */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_GET_TAG, 14, tag))
handleErrors();

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}
</pre>

==Authenticated Decryption using CCM mode==

Decryption with CCM mode is much the same as for decryption with CCM but with some additional things to bear in mind.
* you can only call EVP_DecryptUpdate once for AAD and once for the plaintext.
* The total ciphertext length must be passed to EVP_DecryptUpdate (only needed if AAD is passed)
* Optionally the tag and IV length can also be passed. If they are not then the defaults are used (12 bytes for AES tags, and 7 bytes for AES IVs)
* The tag verify is performed when you call the final EVP_DecryptUpdate and is reflected by the return value: there is no call to EVP_DecryptFinal.

See the code below for an example:
<pre>
int ccm_decrypt(unsigned char *ciphertext, int ciphertext_len,
unsigned char *aad, int aad_len,
unsigned char *tag,
unsigned char *key,
unsigned char *iv,
unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;
int len;
int plaintext_len;
int ret;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/* Initialise the decryption operation. */
if(1 != EVP_DecryptInit_ex(ctx, EVP_aes_256_ccm(), NULL, NULL, NULL))
handleErrors();

/* Setting IV len to 7. Not strictly necessary as this is the default
* but shown here for the purposes of this example */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, 7, NULL))
handleErrors();

/* Set expected tag value. */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, 14, tag))
handleErrors();

/* Initialise key and IV */
if(1 != EVP_DecryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/* Provide the total ciphertext length */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, NULL, ciphertext_len))
handleErrors();

/* Provide any AAD data. This can be called zero or more times as required */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

/*
* Provide the message to be decrypted, and obtain the plaintext output.
* EVP_DecryptUpdate can be called multiple times if necessary
*/
ret = EVP_DecryptUpdate(ctx, plaintext, &len, ciphertext, ciphertext_len);

plaintext_len = len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

if(ret > 0) {
/* Success */
return plaintext_len;
} else {
/* Verify failed */
return -1;
}
}
</pre>

== Potential Issue in AES/GCM ==

Early versions of the authenticated encryption interface required using a 0-sized array (not a NULL array) to arrive at the proper authentication tag '''''when''''' the authentication tag size was ''not'' a multiple of the block size (for example, an authentication tag size of 20 bytes). For more information on the issue and the work-arounds, see [http://rt.openssl.org/Ticket/Display.html?id=2859 Issue #2859: Possible bug in AES GCM mode] and [http://groups.google.com/d/msg/mailing.openssl.users/idg9Z22MYZs/Jqlo8dA-2tMJ Possible bug in GCM/GMAC with (just) AAD of size unequal to block size].

==See also==
* [[EVP]]
* [[Libcrypto API]]
* [[EVP Symmetric Encryption and Decryption]]
* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
* [[EVP Signing and Verifying]]
* [[EVP Message Digests]]
* [[EVP Key Agreement]]
* [[EVP Key and Parameter Generation]]

[[Category:Crypto API]]
[[Category:C level]]
[[Category:Examples]]

File:Evp-ccm-encrypt.c

2019-04-30T14:05:56Z

Mspncp: (EVP CCM Authenticated Encryption and Decryption - C sample)

(EVP CCM Authenticated Encryption and Decryption - C sample)

File:Evp-gcm-encrypt.c

2019-04-30T14:02:56Z

Mspncp: (EVP GCM Authenticated Encryption and Decryption - C sample)

(EVP GCM Authenticated Encryption and Decryption - C sample)

EVP Symmetric Encryption and Decryption

2019-04-30T11:55:19Z

Mspncp: Reformat code according to OpenSSL coding style and provide downloadable sample C file

{{DocInclude
|Name=Symmetric Encryption and Decryption
|Url=http://wiki.openssl.org/index.php/Manual:Evp(3)
|Include=evp.h}}

The [[Libcrypto API|libcrypto]] library within OpenSSL provides functions for performing symmetric encryption and decryption operations across a wide range of algorithms and modes. This page walks you through the basics of performing a simple encryption and corresponding decryption operation.

In order to perform encryption/decryption you need to know:
* Your algorithm
* Your mode
* Your key
* Your Initialisation Vector (IV)

This page assumes that you know what all of these things mean. If you don't then please refer to [[Basics of Encryption]].

The complete source code of the following example can be downloaded as [[Media:evp-symmetric-encrypt.c|evp-symmetric-encrypt.c]].

==Setting it up==

The code below sets up the program. In this example we are going to take a simple message ("The quick brown fox jumps over the lazy dog"), and then encrypt it using a predefined key and IV. In this example the key and IV have been hard coded in - in a real situation you would never do this! Following encryption we will then decrypt the resulting ciphertext, and (hopefully!) end up with the message we first started with. This program expects two functions to be defined: "encrypt" and "decrypt". We will define those further down the page. Note that this uses the auto-init facility in 1.1.0.

#include <openssl/conf.h>
#include <openssl/evp.h>
#include <openssl/err.h>
#include <string.h>

int main (void)
{
/*
* Set up the key and iv. Do I need to say to not hard code these in a
* real application? :-)
*/

/* A 256 bit key */
unsigned char *key = (unsigned char *)"01234567890123456789012345678901";

/* A 128 bit IV */
unsigned char *iv = (unsigned char *)"0123456789012345";

/* Message to be encrypted */
unsigned char *plaintext =
(unsigned char *)"The quick brown fox jumps over the lazy dog";

/*
* Buffer for ciphertext. Ensure the buffer is long enough for the
* ciphertext which may be longer than the plaintext, depending on the
* algorithm and mode.
*/
unsigned char ciphertext[128];

/* Buffer for the decrypted text */
unsigned char decryptedtext[128];

int decryptedtext_len, ciphertext_len;

/* Encrypt the plaintext */
ciphertext_len = encrypt (plaintext, strlen ((char *)plaintext), key, iv,
ciphertext);

/* Do something useful with the ciphertext here */
printf("Ciphertext is:\n");
BIO_dump_fp (stdout, (const char *)ciphertext, ciphertext_len);

/* Decrypt the ciphertext */
decryptedtext_len = decrypt(ciphertext, ciphertext_len, key, iv,
decryptedtext);

/* Add a NULL terminator. We are expecting printable text */
decryptedtext[decryptedtext_len] = '\0';

/* Show the decrypted text */
printf("Decrypted text is:\n");
printf("%s\n", decryptedtext);

return 0;
}

The program sets up a 256 bit key and a 128 bit IV. This is appropriate for the 256-bit AES encryption that we going to be doing in CBC mode. Make sure you use the right key and IV length for the cipher you have selected, or it will go horribly wrong!! The IV should be random for CBC mode.

We've also set up a buffer for the ciphertext to be placed in. It is important to ensure that this buffer is sufficiently large for the expected ciphertext or you may see a program crash (or potentially introduce a security vulnerability into your code). Note: The ciphertext may be longer than the plaintext (e.g. if padding is being used).

We're also going to need a helper function to handle any errors. This will simply dump any error messages from the OpenSSL error stack to the screen, and then abort the program.

void handleErrors(void)
{
ERR_print_errors_fp(stderr);
abort();
}

==Encrypting the message==

So now that we have set up the program we need to define the "encrypt" function. This will take as parameters the plaintext, the length of the plaintext, the key to be used, and the IV. We'll also take in a buffer to put the ciphertext in (which we assume to be long enough), and will return the length of the ciphertext that we have written.

Encrypting consists of the following stages:
* Setting up a context
* Initialising the encryption operation
* Providing plaintext bytes to be encrypted
* Finalising the encryption operation

During initialisation we will provide an EVP_CIPHER object. In this case we are using EVP_aes_256_cbc(), which uses the AES algorithm with a 256-bit key in [[CBC]] mode. Refer to [[EVP#Working with Algorithms and Modes]] for further details.

int encrypt(unsigned char *plaintext, int plaintext_len, unsigned char *key,
unsigned char *iv, unsigned char *ciphertext)
{
EVP_CIPHER_CTX *ctx;

int len;

int ciphertext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/*
* Initialise the encryption operation. IMPORTANT - ensure you use a key
* and IV size appropriate for your cipher
* In this example we are using 256 bit AES (i.e. a 256 bit key). The
* IV size for *most* modes is the same as the block size. For AES this
* is 128 bits
*/
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_cbc(), NULL, key, iv))
handleErrors();

/*
* Provide the message to be encrypted, and obtain the encrypted output.
* EVP_EncryptUpdate can be called multiple times if necessary
*/
if(1 != EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len))
handleErrors();
ciphertext_len = len;

/*
* Finalise the encryption. Further ciphertext bytes may be written at
* this stage.
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len))
handleErrors();
ciphertext_len += len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}

==Decrypting the Message==

Finally we need to define the "decrypt" operation. This is very similar to encryption and consists of the following stages:
Decrypting consists of the following stages:
* Setting up a context
* Initialising the decryption operation
* Providing ciphertext bytes to be decrypted
* Finalising the decryption operation

Again through the parameters we will receive the ciphertext to be decrypted, the length of the ciphertext, the key and the IV. We'll also receive a buffer to place the decrypted text into, and return the length of the plaintext we have found.

Note that we have passed the length of the ciphertext. This is required as you cannot use functions such as "strlen" on this data - its binary! Similarly, even though in this example our plaintext really is ASCII text, OpenSSL does not know that. In spite of the name plaintext could be binary data, and therefore no NULL terminator will be put on the end (unless you encrypt the NULL as well of course).

Here is the decrypt function:

int decrypt(unsigned char *ciphertext, int ciphertext_len, unsigned char *key,
unsigned char *iv, unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;

int len;

int plaintext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new()))
handleErrors();

/*
* Initialise the decryption operation. IMPORTANT - ensure you use a key
* and IV size appropriate for your cipher
* In this example we are using 256 bit AES (i.e. a 256 bit key). The
* IV size for *most* modes is the same as the block size. For AES this
* is 128 bits
*/
if(1 != EVP_DecryptInit_ex(ctx, EVP_aes_256_cbc(), NULL, key, iv))
handleErrors();

/*
* Provide the message to be decrypted, and obtain the plaintext output.
* EVP_DecryptUpdate can be called multiple times if necessary.
*/
if(1 != EVP_DecryptUpdate(ctx, plaintext, &len, ciphertext, ciphertext_len))
handleErrors();
plaintext_len = len;

/*
* Finalise the decryption. Further plaintext bytes may be written at
* this stage.
*/
if(1 != EVP_DecryptFinal_ex(ctx, plaintext + len, &len))
handleErrors();
plaintext_len += len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return plaintext_len;
}

==Ciphertext Output==

If all goes well you should end up with output that looks like the following:
Ciphertext is:
0000 - e0 6f 63 a7 11 e8 b7 aa-9f 94 40 10 7d 46 80 a1 .oc.......@.}F..
0010 - 17 99 43 80 ea 31 d2 a2-99 b9 53 02 d4 39 b9 70 ..C..1....S..9.p
0020 - 2c 8e 65 a9 92 36 ec 92-07 04 91 5c f1 a9 8a 44 ,.e..6.....\...D
Decrypted text is:
The quick brown fox jumps over the lazy dog

For further details about symmetric encryption and decryption operations refer to the OpenSSL documentation [[Manual:EVP_EncryptInit(3)]].

==Padding==

OpenSSL uses PKCS padding by default. If the mode you are using allows you to change the padding, then you can change it with <tt>[http://www.openssl.org/docs/man1.0.2/crypto/EVP_CIPHER_CTX_set_padding.html EVP_CIPHER_CTX_set_padding]</tt>. From the man page:

<blockquote>EVP_CIPHER_CTX_set_padding() enables or disables padding. By default encryption operations are padded using standard block padding and the padding is checked and removed when decrypting. If the pad parameter is zero then no padding is performed, the total amount of data encrypted or decrypted must then be a multiple of the block size or an error will occur...

PKCS padding works by adding n padding bytes of value n to make the total length of the encrypted data a multiple of the block size. Padding is always added so if the data is already a multiple of the block size n will equal the block size. For example if the block size is 8 and 11 bytes are to be encrypted then 5 padding bytes of value 5 will be added...

If padding is disabled then the decryption operation will only succeed if the total amount of data decrypted is a multiple of the block size.</blockquote>

==C++ Programs==

Questions regarding how to use the EVP interfaces from a C++ program arise on occasion. Generally speaking, using the EVP interfaces from a C++ program is the same as using them from a C program.

You can download a sample program using EVP symmetric encryption and C++11 called [[Media:Evp-encrypt-cxx.tar.gz|evp-encrypt.cxx]]. The sample uses a custom allocator to zeroize memory, C++ smart pointers to manage resources, and provides a <tt>secure_string</tt> using <tt>basic_string</tt> and the custom allocator. You need to use <tt>g++ -std=c++11 ...</tt> to compile it because of <tt>std::unique_ptr</tt>.

You should also ensure you configure an build with <tt>-fexception</tt> to ensure C++ exceptions pass as expected through C code. And you should avoid other flags, like <tt>-fno-exceptions</tt> and <tt>-fno-rtti</tt>.

The program's <tt>main</tt> simply encrypts and decrypts a string using AES-256 in CBC mode:

<pre>typedef unsigned char byte;
typedef std::basic_string<char, std::char_traits<char>, zallocator<char> > secure_string;
using EVP_CIPHER_CTX_ptr = std::unique_ptr<EVP_CIPHER_CTX, decltype(&::EVP_CIPHER_CTX_free)>;
...

int main(int argc, char* argv[])
{
// Load the necessary cipher
EVP_add_cipher(EVP_aes_256_cbc());

// plaintext, ciphertext, recovered text
secure_string ptext = "Yoda said, Do or do not. There is no try.";
secure_string ctext, rtext;

byte key[KEY_SIZE], iv[BLOCK_SIZE];
gen_params(key, iv);

aes_encrypt(key, iv, ptext, ctext);
aes_decrypt(key, iv, ctext, rtext);

OPENSSL_cleanse(key, KEY_SIZE);
OPENSSL_cleanse(iv, BLOCK_SIZE);

std::cout << "Original message:\n" << ptext << std::endl;
std::cout << "Recovered message:\n" << rtext << std::endl;

return 0;
}</pre>

And the encryption routine is as follows. The decryption routine is similar:

<pre>void aes_encrypt(const byte key[KEY_SIZE], const byte iv[BLOCK_SIZE], const secure_string& ptext, secure_string& ctext)
{
EVP_CIPHER_CTX_ptr ctx(EVP_CIPHER_CTX_new(), ::EVP_CIPHER_CTX_free);
int rc = EVP_EncryptInit_ex(ctx.get(), EVP_aes_256_cbc(), NULL, key, iv);
if (rc != 1)
throw std::runtime_error("EVP_EncryptInit_ex failed");

// Cipher text expands upto BLOCK_SIZE
ctext.resize(ptext.size()+BLOCK_SIZE);
int out_len1 = (int)ctext.size();

rc = EVP_EncryptUpdate(ctx.get(), (byte*)&ctext[0], &out_len1, (const byte*)&ptext[0], (int)ptext.size());
if (rc != 1)
throw std::runtime_error("EVP_EncryptUpdate failed");

int out_len2 = (int)ctext.size() - out_len1;
rc = EVP_EncryptFinal_ex(ctx.get(), (byte*)&ctext[0]+out_len1, &out_len2);
if (rc != 1)
throw std::runtime_error("EVP_EncryptFinal_ex failed");

// Set cipher text size now that we know it
ctext.resize(out_len1 + out_len2);
}</pre>

==Notes on some unusual modes==

Worthy of mention here is the [[XTS]] mode (e.g. EVP_aes_256_xts()). This works in exactly the same way as shown above, except that the "tweak" is provided in the IV parameter. A further "gotcha" is that XTS mode expects a key which is twice as long as normal. Therefore EVP_aes_256_xts() expects a key which is 512-bits long.

Authenticated encryption modes ([[GCM]] or [[CCM]]) work in essentially the same way as shown above but require some special handling. See [[EVP Authenticated Encryption and Decryption]] for further details.

==See also==
* [[EVP]]
* [[Libcrypto API]]
* [[EVP Authenticated Encryption and Decryption]]
* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
* [[EVP Signing and Verifying]]
* [[EVP Message Digests]]
* [[EVP Key Agreement]]
* [[EVP Key and Parameter Generation]]

[[Category:Crypto API]]
[[Category:C level]]
[[Category:Examples]]

File:Evp-symmetric-encrypt.c

2019-04-30T11:50:06Z

Mspncp: EVP Symmetric Encryption and Decryption - C sample

EVP Symmetric Encryption and Decryption - C sample