Home

Awesome

AppVeyor, CircleCI

OQS-OpenSSL_1_1_1

<span style="color: red;">Warning</span>

<b><span style="color: red;">The OpenSSL project has announced that its support for OpenSSL 1.1.1 will stop in September, 2023, and that all users should switch to OpenSSL 3. Consequently, the Open Quantum Safe project is discontinuing development of our OQS-OpenSSL 1.1.1 fork. No more releases are planned for OQS-OpenSSL 1.1.1. The OQS Provider for OpenSSL 3 provides full support for post-quantum key exchange and authentication in TLS 1.3, X.509, and S/MIME.</span></b>

OpenSSL is an open-source implementation of the TLS protocol and various cryptographic algorithms (View the original README.)

OQS-OpenSSL_1_1_1 is a fork of OpenSSL 1.1.1 that adds quantum-safe key exchange and authentication algorithms using liboqs for prototyping and evaluation purposes. This fork is not endorsed by the OpenSSL project.

Overview

liboqs is an open source C library for quantum-resistant cryptographic algorithms. See here for more information.

OQS-OpenSSL_1_1_1-stable is a fork that integrates liboqs into OpenSSL 1.1.1. The goal of this integration is to provide easy prototyping of quantum-safe cryptography in the TLS 1.3 protocol.

Both liboqs and this fork are part of the Open Quantum Safe (OQS) project, which aims to develop and prototype quantum-safe cryptography (QSC). More information about the project can be found here.

Note that, referencing the terminology defined by ETSI and CSA, the terms "post-quantum cryptography" (PQC), "quantum-safe cryptography" (QSC) and "quantum-resistant cryptography" (QRC) all refer to the same class of cryptographic algorithms that is made available for use via this fork.

Status

This fork is currently in sync with the OpenSSL_1_1_1u tag, and adds the following:

For more information, see the release notes.

WE DO NOT RECOMMEND RELYING ON THIS FORK IN A PRODUCTION ENVIRONMENT OR TO PROTECT ANY SENSITIVE DATA. This fork is at an experimental stage, and has not received the same level of auditing and analysis that OpenSSL has received. See the Limitations and Security section below for more information.

liboqs and our integration into OpenSSL is provided "as is", without warranty of any kind. See the LICENSE for the full disclaimer.

Limitations and security

As research advances, the supported algorithms may see rapid changes in their security, and may even prove insecure against both classical and quantum computers.

We believe that the NIST Post-Quantum Cryptography standardization project is currently the best avenue to identifying potentially quantum-resistant algorithms, and strongly recommend that applications and protocols rely on the outcomes of the NIST standardization project when deploying quantum-safe cryptography.

While at the time of this writing there are no vulnerabilities known in any of the quantum-safe algorithms used in this fork, it is advisable to wait on deploying quantum-safe algorithms until further guidance is provided by the standards community, especially from the NIST standardization project.

We realize some parties may want to deploy quantum-safe cryptography prior to the conclusion of the standardization project. We strongly recommend such attempts make use of so-called hybrid cryptography, in which quantum-safe public-key algorithms are combined with traditional public key algorithms (like RSA or elliptic curves) such that the solution is at least no less secure than existing traditional cryptography. This fork provides the ability to use hybrid cryptography.

Proofs of TLS such as [JKSS12] and [KPW13] require a key exchange mechanism that has a form of active security, either in the form of the PRF-ODH assumption, or an IND-CCA KEM. Some of the KEMs provided in liboqs do provide IND-CCA security; others do not (these datasheets specify which provide what security), in which case existing proofs of security of TLS against active attackers do not apply.

Supported Algorithms

If an algorithm is provided by liboqs but is not listed below, it might still be possible to use it in the fork through either one of two ways.

Key Exchange

The following quantum-safe algorithms from liboqs are supported (assuming they have been enabled in liboqs):

<!--- OQS_TEMPLATE_FRAGMENT_LIST_KEXS_START --> <!--- OQS_TEMPLATE_FRAGMENT_LIST_KEXS_END -->

If <KEX> is any of the algorithms listed above, the following hybrid algorithms are supported:

For example, since kyber768 claims NIST L3 security, the hybrid p384_kyber768 is available.

Note that algorithms marked with a dagger (†) have large stack usage and may cause failures when run on threads or in constrained environments. For further information about each algorithm's strengths and limitations, see the documentation markdown files at liboqs.

Authentication

The following digital signature algorithms from liboqs are supported by the fork. Note that not all variants of all algorithms are enabled by default; algorithms that are enabled by default are marked with an asterisk, and should you wish to enable additional variants, consult the "Code Generation" section of the documentation in the wiki.

<!--- OQS_TEMPLATE_FRAGMENT_LIST_SIGS_START --> <!--- OQS_TEMPLATE_FRAGMENT_LIST_SIGS_END -->

The following hybrid algorithms are supported; they combine a quantum-safe algorithm listed above with a traditional digital signature algorithm (<SIG> is any one of the algorithms listed above):

For example, since dilithium2 claims NIST L2 security, the hybrids rsa3072_dilithium2 and p256_dilithium2 are available.

For further information about each algorithm's strengths and limitations, see the documentation markdown files at liboqs.

Quickstart

The steps below have been confirmed to work on macOS 10.14 (with clang 10.0.0), Ubuntu 18.04.1 (with gcc-7) and should work on more recent versions of these operating systems/compilers. They have also been confirmed to work on Windows 10 with Visual Studio 2019. All commands below are just examples and might also be used and work differently as per the respective packages' documentations.

Building

Linux and macOS

Step 0: Get pre-requisites

On Ubuntu, you need to install the following packages:

sudo apt install cmake gcc libtool libssl-dev make ninja-build git

On macOS, you need to install the following packages using brew (or a package manager of your choice):

brew install cmake ninja libtool openssl@1.1

Then, get source code of this fork (<OPENSSL_DIR> is a directory of your choosing):

git clone --branch OQS-OpenSSL_1_1_1-stable https://github.com/open-quantum-safe/openssl.git <OPENSSL_DIR>

Step 1: Build and install liboqs

The following instructions will download and build liboqs, then install it into a subdirectory inside the OpenSSL folder.

git clone --branch main https://github.com/open-quantum-safe/liboqs.git
cd liboqs
mkdir build && cd build
cmake -GNinja -DCMAKE_INSTALL_PREFIX=<OPENSSL_DIR>/oqs ..
ninja
ninja install

Building liboqs requires your system to have (a standard) OpenSSL already installed. configure will detect it if it is located in a standard location, such as /usr or /usr/local/opt/openssl (for brew on macOS). Otherwise, you may need to specify it with -DOPENSSL_ROOT_DIR=<path-to-system-openssl-dir> added to the cmake command.

Note: This will only work correctly, if the OpenSSL version used to build liboqs is a version below 3.0.0. If the standard OpenSSL on the build system or the version pointed to by the above -DOPENSSL_ROOT_DIR=... command is a version >= 3.0.0, then you must add the option -DOQS_USE_OPENSSL=OFF to the above cmake build command to successfully complete the subsequent build steps for this package.

Step 2: Build the fork

Now we follow the standard instructions for building OpenSSL. Navigate to <OPENSSL_DIR>, and:

on Ubuntu, run:

./Configure no-shared linux-x86_64 -lm
make -j

on macOS (x86_64), run:

./Configure no-shared darwin64-x86_64-cc
make -j

on macOS (M1 / arm64), run:

./Configure no-shared darwin64-arm64-cc
make -j

Windows

Step 0

Make sure you can build the unmodified version of OpenSSL by following the instructions in INSTALL and NOTES.WIN.

Then, get the fork source code (<OPENSSL_DIR> is a directory of your choosing):

git clone --branch OQS-OpenSSL_1_1_1-stable https://github.com/open-quantum-safe/openssl.git <OPENSSL_DIR>

The above command uses git, but alternatively, an archive of the source code can be downloaded and expanded into <OPENSSL_DIR>

Step 1: Build and install liboqs

The following instructions will download (using git, alternatively, download an archive of the source and unzip the project) and build the x64 release configuration of liboqs, then copy the required files it into a subdirectory inside the OpenSSL folder. You may need to install dependencies before building liboqs; see the liboqs README.

git clone --branch main https://github.com/open-quantum-safe/liboqs.git
cd liboqs
mkdir build
cd build
cmake -GNinja -DCMAKE_INSTALL_PREFIX=<OPENSSL_DIR>\oqs ..
ninja
ninja install

Step 2: Build the fork

Now we follow the standard instructions for building OpenSSL:

perl Configure VC-WIN64A
nmake

N.B.: The fork can also be built as a set of shared libraries by specifying shared instead of no-shared in the above commands; We have used no-shared to avoid having to get the libraries in the right place for the runtime linker.

Build options

Default algorithms announced

By default, the fork is built to only announce 128-bit strength QSC hybrid KEM algorithms in the initial TLS handshake (using the EC groups announced extension of TLS1.3). This algorithm set can be changed to an arbitrary collection at build time by setting the variable OQS_DEFAULT_GROUPS to a colon-separated list of KEM algorithms supported, e.g., by running

./Configure no-shared linux-x86_64 -DOQS_DEFAULT_GROUPS=\"p384_kyber768:X25519:newhope1024cca\" -lm

Note: When executing the SSL test suite via make test, be sure to include not only X25519 but also ED448 in the algorithm list specified in OQS_DEFAULT_GROUPS to ensure classic algorithm tests pass.

The announced algorithms can also be modified at runtime by setting the -curves or -groups parameter with programs supporting this option (e.g., openssl s_client or openssl s_server) or by using the SSL_CTX_set1_groups_list API call. A final alternative is to set the TLS_DEFAULT_GROUPS environment variable to such colon-separated list of KEM algorithms supported. This option only works if the SSL_CTX_set1_groups_list API call has not been used.

Running

TLS demo

OpenSSL contains a basic TLS server (s_server) and TLS client (s_client) which can be used to demonstrate and test TLS connections.

To run a server, you first need to generate an X.509 certificate, using either a classical (rsa), quantum-safe (any quantum-safe authentication algorithm in the Supported Algorithms section above), or hybrid (any hybrid authentication algorithm in the Supported Algorithms section above) algorithm. The server certificate can either be self-signed or part of a chain. In either case, you need to generate a self-signed root CA certificate using the following command, replacing <SIG> with an algorithm mentioned above:

apps/openssl req -x509 -new -newkey <SIG> -keyout <SIG>_CA.key -out <SIG>_CA.crt -nodes -subj "/CN=oqstest CA" -days 365 -config apps/openssl.cnf

If you want an ECDSA certificate (<SIG> = ecdsa), you instead need to run:

apps/openssl req -x509 -new -newkey ec:<(apps/openssl ecparam -name secp384r1) -keyout <SIG>_CA.key -out <SIG>_CA.crt -nodes -subj "/CN=oqstest" -days 365 -config apps/openssl.cnf

The root CA certificate can be used directly to start the server (see below), or can be used to issue a server certificate, using the usual OpenSSL process (note that for simplicity, we use the same algorithm for the server and CA certificates; in practice the CA is likely to use a stronger one):

  1. The server generates its key pair, a certificate request and sends the latter to the CA:

     apps/openssl req -new -newkey <SIG> -keyout <SIG>_srv.key -out <SIG>_srv.csr -nodes -subj "/CN=oqstest server" -config apps/openssl.cnf

  2. The CA generates the signed server certificate:

     apps/openssl x509 -req -in <SIG>_srv.csr -out <SIG>_srv.crt -CA <SIG>_CA.crt -CAkey <SIG>_CA.key -CAcreateserial -days 365

Using the key and certificate thus created, running a basic TLS server with all possible key-exchange algorithms enabled, can be achieved using the following command, replacing <SERVER> with either <SIG>_CA or <SIG>_srv:

apps/openssl s_server -cert <SERVER>.crt -key <SERVER>.key -www -tls1_3

In another terminal window, you can run a TLS client requesting one of the supported key-exchanges (<KEX> = one of the quantum-safe or hybrid key exchange algorithms listed in the Supported Algorithms section above:

apps/openssl s_client -groups <KEX> -CAfile <SIG>_CA.crt

CMS demo

OpenSSL has facilities to perform signing operations pursuant to RFC 5652. This fork can be used to perform such operations with quantum-safe algorithms.

Building on the artifacts created in the TLS setup above (CA and server certificate creation using a specific (quantum-safe) <SIG> algorithm), the following command can be used to generate a (quantum-safe) signed file from some input file:

apps/openssl cms -in inputfile -sign -signer <SIG>_srv.crt -inkey <SIG>_srv.key -nodetach -outform pem -binary -out signedfile.cms

This command can be used to verify (and extract the contents) of the CMS file resultant from the command above:

apps/openssl cms -verify -CAfile <SIG>_CA.crt -inform pem -in signedfile.cms -crlfeol -out signeddatafile

The contents of inputfile and the resultant signeddatafile should be the same.

Also supported are general signing operations using the standard OpenSSL dgst commands using QSC public/private keys of any of the supported signature algorithms. Example command using the same file notation used above:

    echo TestDataToSign | apps/openssl dgst -sha256 -sign <SIG>_srv.key -out signature

Performance testing

TLS end-to-end testing

"Empty" TLS handshakes can be performance tested via the standard openssl s_time command. In order to suitably trigger this with an OQS KEM/SIG pair of choice, first follow all steps outlined in the TLS demo section to obtain an OQS-algorithm-signed server certificate. You can then run the performance test in one of two ways:

apps/openssl s_server -cert <SERVER>.crt -key <SERVER>.key -www -tls1_3 -groups <KEX>

Then run apps/openssl s_time

apps/openssl s_server -cert <SERVER>.crt -key <SERVER>.key -www -tls1_3

and specify the key-exchange algorithm through s_time using apps/openssl s_time -curves <KEX>.

Algorithm speed testing

OpenSSL also has facilities to perform pure speed tests of the cryptographic algorithms supported. This can be used to compare the relative performance of OQS algorithms.

To measure the speed of all KEM algorithms supported by the underlying liboqs:

apps/openssl speed oqskem

Similarly, to measure the speed of all OQS signature algorithms:

apps/openssl speed oqssig

As with standard OpenSSL, one can also pass a particular algorithm name to be tested, e.g., apps/openssl speed dilithium2.

We also have docker-based performance test environments in the oqs-demos subproject.

Integration testing

We have various pytest test suites for the TLS and CMS functionalities. Consult the oqs-test/ README for more information.

Third Party Integrations

Various third-party software applications, such as nginx and curl use OpenSSL to establish TLS connections; they can be built against our fork to make use of quantum-safe cryptography. The oqs-demos repository provides instructions for building various software like so.

Contributing

Contributions are gratefully welcomed. See our Contributing Guide for more details.

License

All modifications to this repository are released under the same terms as OpenSSL, namely as described in the file LICENSE.

Team

The Open Quantum Safe project is led by Douglas Stebila and Michele Mosca at the University of Waterloo.

Contributors to OQS-OpenSSL_1_1_1 include:

Acknowledgments

Financial support for the development of Open Quantum Safe has been provided by Amazon Web Services and the Canadian Centre for Cyber Security.

We'd like to make a special acknowledgement to the companies who have dedicated programmer time to contribute source code to OQS, including Amazon Web Services, evolutionQ, Microsoft Research, Cisco Systems, and IBM Research.

Research projects which developed specific components of OQS have been supported by various research grants, including funding from the Natural Sciences and Engineering Research Council of Canada (NSERC); see here and here for funding acknowledgments.