BoringSSL is a fork, maintained by Google, of the OpenSSL cryptographic library. (View the original README.)
OQS-BoringSSL is a fork of BoringSSL that adds quantum-safe key exchange and authentication algorithms using liboqs for prototyping and evaluation purposes. This fork is not endorsed by Google.
liboqs is an open source C library for quantum-resistant cryptographic algorithms. See here for more information.
OQS-BoringSSL is a fork that integrates liboqs into BoringSSL so as to facilitate the evaluation 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. More information about the project can be found here.
This fork is built on top of commit 387f82054c8ffa7d2b9e31d908586fbd47f34039, and adds:
- quantum-safe key exchange to TLS 1.3
- hybrid (quantum-safe + elliptic curve) key exchange to TLS 1.3
- quantum-safe digital signatures to TLS 1.3
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 BoringSSL does not guarantee API or ABI stability. See the Limitations and Security section below for more information.
liboqs and this integration are provided "as is", without warranty of any kind. See the LICENSE for the full disclaimer.
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.
Furthermore, the BoringSSL project does not guarantee API or ABI stability; this fork is maintained primarily to enable the use of quantum-safe cryptography in the Chromium web browser, which relies on BoringSSL's TLS implementation.
The fork is currently based on commit hash 387f82054c8ffa7d2b9e31d908586fbd47f34039 which has been verified to work with Chromium tag 100.0.4856.2. If we do decide to update BoringSSL, we will do so to the most recent commit that is supported by the desired tag at which we would like Chromium to be. We consequently also cannot guarantee API or ABI stability for this fork.
If an algorithm is provided by liboqs but is not listed below, it might still be possible to use it in the fork through the build mechanism described here.
The following quantum-safe algorithms from liboqs are supported (assuming they have been enabled in liboqs):
- BIKE:
bikel1,bikel3 - CRYSTALS-Kyber:
kyber512,kyber768,kyber1024,kyber90s512,kyber90s768,kyber90s1024 - FrodoKEM:
frodo640shake,frodo976aes,frodo976shake,frodo1344aes,frodo1344shake - HQC:
hqc128,hqc192,hqc256† - NTRU:
ntru_hps2048509,ntru_hps2048677,ntru_hps4096821,ntru_hps40961229,ntru_hrss701,ntru_hrss1373 - NTRU-Prime:
ntrulpr653,ntrulpr761,ntrulpr857,ntrulpr1277,sntrup653,sntrup761,sntrup857,sntrup1277 - SABER:
lightsaber,saber,firesaber - SIDH:
sidhp434,sidhp503,sidhp610,sidhp751 - SIKE:
sikep434,sikep503,sikep610,sikep751
For each <KEX> listed above, the following hybrid algorithms are made available as follows:
- If
<KEX>has L1 security, the methodp256_<KEX>is available, which combines<KEX>with ECDH using NIST's P256 curve - If
<KEX>has L3 security, the methodp384_<KEX>is available, which combines<KEX>with ECDH using NIST's P384 curve - If
<KEX>has L5 security, the methodp521_<KEX>is available, which combines<KEX>with ECDH using NIST's P521 curve
For example, since kyber768 claims 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.
The following quantum-safe digital signature algorithms from liboqs are supported (assuming they have been enabled in liboqs):
- CRYSTALS-DILITHIUM:
dilithium3,dilithium5,dilithium2_aes,dilithium3_aes,dilithium5_aes - Falcon:
falcon512,falcon1024 - Picnic:
picnicl1fs,picnicl1ur,picnicl1full,picnic3l1,picnic3l3,picnic3l5 - Rainbow:
rainbowIclassic,rainbowIcircumzenithal,rainbowIcompressed,rainbowIIIclassic,rainbowIIIcircumzenithal,rainbowIIIcompressed,rainbowVclassic,rainbowVcircumzenithal,rainbowVcompressed - SPHINCS-Haraka:
sphincsharaka128frobust,sphincsharaka128fsimple,sphincsharaka128srobust,sphincsharaka128ssimple,sphincsharaka192frobust,sphincsharaka192fsimple,sphincsharaka192srobust,sphincsharaka192ssimple,sphincsharaka256frobust,sphincsharaka256fsimple,sphincsharaka256srobust,sphincsharaka256ssimple - SPHINCS-SHA256:
sphincssha256128frobust,sphincssha256128fsimple,sphincssha256128srobust,sphincssha256128ssimple,sphincssha256192frobust,sphincssha256192fsimple,sphincssha256192srobust,sphincssha256192ssimple,sphincssha256256frobust,sphincssha256256fsimple,sphincssha256256srobust,sphincssha256256ssimple - SPHINCS-SHAKE256:
sphincsshake256128frobust,sphincsshake256128fsimple,sphincsshake256128srobust,sphincsshake256128ssimple,sphincsshake256192frobust,sphincsshake256192fsimple,sphincsshake256192srobust,sphincsshake256192ssimple,sphincsshake256256frobust,sphincsshake256256fsimple,sphincsshake256256srobust,sphincsshake256256ssimple
No hybrid signature algorithms are currently implemented. If those are needed for a project please use OQS-OpenSSL which supports them out of the box, or implement them and create a pull request, or create an issue.
We regularly test the fork on Ubuntu 18.04 and above. Support for other platforms and operating systems, as well as for old versions of GCC (< 8) and Clang (< 8), is not guaranteed.
On Ubuntu, you need to install the following packages:
sudo apt install cmake gcc ninja-build libunwind-dev pkg-config python3 python3-psutil golang-go
You will also need the latest version of the toolchain for the Go programming language, available here
Then, get the source code for this fork (<BORINGSSL_DIR> is a directory of your choosing):
git clone --branch master https://github.com/open-quantum-safe/boringssl.git <BORINGSSL_DIR>
The following instructions will download and build liboqs, then install it to <BORINGSSL_DIR>/oqs.
git clone --branch main --single-branch --depth 1 https://github.com/open-quantum-safe/liboqs.git
cd liboqs
mkdir build && cd build
cmake -G"Ninja" -DCMAKE_INSTALL_PREFIX=<BORINGSSL_DIR>/oqs -DOQS_USE_OPENSSL=OFF ..
ninja
ninja install
Now we follow the standard instructions for building BoringSSL. Navigate to <BORINGSSL_DIR>, and:
on Ubuntu, run:
mkdir build
cd build
cmake -GNinja ..
ninja
The fork can also be built with shared libraries, to do so, run cmake -DBUILD_SHARED_LIBRARIES=ON -GNinja ...
To execute the white-box and black-box tests that come with BoringSSL as well the tests for OQS key-exchange and digital signature algorithms, execute ninja run_tests from the build directory.
BoringSSL contains a basic TLS server (server) and TLS client (client) which can be used to demonstrate and test TLS connections.
To run a basic TLS server with all liboqs algorithms enabled, from the build directory, run:
tool/bssl server -accept 4433 -sig-alg <SIG> -loop
where <SIG> is one of the quantum-safe or hybrid signature algorithms listed in the Supported Algorithms section above; if the sig-alg option is omitted, the default classical algorithm ecdhe with prime curve X9_62_prime256v1 is used.
In another terminal window, you can run a TLS client requesting one of the supported key-exchange algorithms:
tool/bssl client -curves <KEX> -connect localhost:4433
where <KEX> is one of the quantum-safe or hybrid key exchange algorithms listed in the Supported Algorithms section above.
You can also simply run python3 oqs_scripts/try_handshake.py, which will pick a random key-exchange and signature algorithm and will attempt a handshake between the TLS server and client with the chosen algorithms.
The Open Quantum Safe project is led by Douglas Stebila and Michele Mosca at the University of Waterloo.
Contributors to this fork include:
- Christian Paquin (Microsoft Research)
- Goutam Tamvada (University of Waterloo)
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.