AppVeyor: , CircleCI: , TravisCI:
liboqs
liboqs is an open source C library for quantum-safe cryptographic algorithms.
Overview
liboqs provides:
- a collection of open source implementations of quantum-safe key encapsulation mechanism (KEM) and digital signature algorithms; the full list can be found below
- a common API for these algorithms
- a test harness and benchmarking routines
liboqs is part of the Open Quantum Safe (OQS) project led by Douglas Stebila and Michele Mosca, which aims to develop and integrate into applications quantum-safe cryptography to facilitate deployment and testing in real world contexts. In particular, OQS provides prototype integrations of liboqs into TLS and SSH, through OpenSSL and OpenSSH.
More information on OQS can be found here and in the associated whitepapers.
Status
Supported Algorithms
Details on each supported algorithm can be found in the docs/algorithms folder.
The list below indicates all algorithms supported by liboqs, but not all those algorithms have been selected for standardization by NIST, specifically Kyber (excluding the "-90s" variants), Dilithium (excluding the "-AES" variants), Falcon, and SPHINCS+ (excluding the "robust" variants). Activating only those standardized algorithms for use in liboqs
can be facilitated by setting the OQS_ALGS_ENABLED build configuration variable to STD
. By default liboqs
is built supporting all, incl. experimental, PQ algorithms listed below.
Key encapsulation mechanisms
- BIKE: BIKE-L1, BIKE-L3, BIKE-L5
- Classic McEliece: Classic-McEliece-348864†, Classic-McEliece-348864f†, Classic-McEliece-460896†, Classic-McEliece-460896f†, Classic-McEliece-6688128†, Classic-McEliece-6688128f†, Classic-McEliece-6960119†, Classic-McEliece-6960119f†, Classic-McEliece-8192128†, Classic-McEliece-8192128fâ€
- FrodoKEM: FrodoKEM-640-AES, FrodoKEM-640-SHAKE, FrodoKEM-976-AES, FrodoKEM-976-SHAKE, FrodoKEM-1344-AES, FrodoKEM-1344-SHAKE
- HQC: HQC-128, HQC-192, HQC-256â€
- Kyber: Kyber512, Kyber768, Kyber1024
- NTRU-Prime: sntrup761
Signature schemes
- CRYSTALS-Dilithium: Dilithium2, Dilithium3, Dilithium5
- Falcon: Falcon-512, Falcon-1024
- SPHINCS+-SHA2: SPHINCS+-SHA2-128f-simple, SPHINCS+-SHA2-128s-simple, SPHINCS+-SHA2-192f-simple, SPHINCS+-SHA2-192s-simple, SPHINCS+-SHA2-256f-simple, SPHINCS+-SHA2-256s-simple
- SPHINCS+-SHAKE: SPHINCS+-SHAKE-128f-simple, SPHINCS+-SHAKE-128s-simple, SPHINCS+-SHAKE-192f-simple, SPHINCS+-SHAKE-192s-simple, SPHINCS+-SHAKE-256f-simple, SPHINCS+-SHAKE-256s-simple
Note that for algorithms marked with a dagger (†), liboqs contains at least one implementation that uses a large amount of stack space; this may cause failures when run in threads or in constrained environments. For more information, consult the algorithm information sheets in the docs/algorithms folder.
Limitations and Security
While at the time of this writing there are no vulnerabilities known in any of the quantum-safe algorithms used in this library, caution is advised when deploying quantum-safe algorithms as most of the algorithms and software have not been subject to the same degree of scrutiny as for currently deployed algorithms. Particular attention should be paid to guidance provided by the standards community, especially from the NIST Post-Quantum Cryptography Standardization project. As research advances, the supported algorithms may see rapid changes in their security, and may even prove insecure against both classical and quantum computers. Moreover, note that the sntrup761
is only included for interop testing.
liboqs does not intend to "pick winners": algorithm support is informed by the NIST PQC standardization project. We strongly recommend that applications and protocols rely on the outcomes of this effort when deploying post-quantum cryptography.
We realize some parties may want to deploy quantum-safe cryptography prior to the conclusion of the NIST PQC standardization project. We strongly recommend such attempts make use of so-called hybrid cryptography, in which quantum-safe public-key algorithms are used alongside traditional public key algorithms (like RSA or elliptic curves) so that the solution is at least no less secure than existing traditional cryptography.
WE DO NOT CURRENTLY RECOMMEND RELYING ON THIS LIBRARY IN A PRODUCTION ENVIRONMENT OR TO PROTECT ANY SENSITIVE DATA. This library is meant to help with research and prototyping. While we make a best-effort approach to avoid security bugs, this library has not received the level of auditing and analysis that would be necessary to rely on it for high security use.
Platform limitations
In order to optimize support effort,
- not all algorithms are equally well supported on all platforms. In case of questions, it is first advised to review the documentation files for each algorithm.
- not all compilers are equally well supported. For example, at least v7.1.0 of the GNU compiler is required.
Quickstart
Linux/macOS
-
Install dependencies:
On Ubuntu:
sudo apt install astyle cmake gcc ninja-build libssl-dev python3-pytest python3-pytest-xdist unzip xsltproc doxygen graphviz python3-yaml valgrind
On macOS, using a package manager of your choice (we've picked Homebrew):
brew install cmake ninja [email protected] wget doxygen graphviz astyle valgrind pip3 install pytest pytest-xdist pyyaml
Note that, if you want liboqs to use OpenSSL for various symmetric crypto algorithms (AES, SHA-2, etc.) then you must have OpenSSL version 1.1.1 or higher.
-
Get the source:
git clone -b main https://github.com/open-quantum-safe/liboqs.git cd liboqs
and build:
mkdir build && cd build cmake -GNinja .. ninja
Various cmake
build options to customize the resultant artifacts are available and are documented in CONFIGURE.md. All supported options are also listed in the .CMake/alg-support.cmake
file, and can be viewed by running cmake -LAH ..
in the build
directory.
The following instructions assume we are in build
.
-
By default the main build result is
lib/liboqs.a
, a static library. If you want to build a shared/dynamic library, append-DBUILD_SHARED_LIBS=ON
to thecmake -GNinja ..
command above and the result will belib/liboqs.so|dylib|dll
. The public headers are located in theinclude
directory. There are also a variety of programs built under thetests
directory:test_kem
: Simple test harness for key encapsulation mechanismstest_sig
: Simple test harness for key signature schemestest_kem_mem
: Simple test harness for checking memory consumption of key encapsulation mechanismstest_sig_mem
: Simple test harness for checking memory consumption of key signature schemeskat_kem
: Program that generates known answer test (KAT) values for key encapsulation mechanisms using the same procedure as the NIST submission requirements, for checking against submitted KAT values usingtests/test_kat.py
kat_sig
: Program that generates known answer test (KAT) values for signature schemes using the same procedure as the NIST submission requirements, for checking against submitted KAT values usingtests/test_kat.py
speed_kem
: Benchmarking program for key encapsulation mechanisms; see./speed_kem --help
for usage instructionsspeed_sig
: Benchmarking program for signature mechanisms; see./speed_sig --help
for usage instructionsexample_kem
: Minimal runnable example showing the usage of the KEM APIexample_sig
: Minimal runnable example showing the usage of the signature APItest_aes
,test_sha3
: Simple test harnesses for crypto sub-componentstest_portability
: Simple test harnesses for checking cross-CPU code portability; requires presence ofqemu
; proper operation validated only on Ubuntu
The complete test suite can be run using
ninja run_tests
-
To generate HTML documentation of the API, run:
ninja gen_docs
Then open
docs/doxygen/html/index.html
in your web browser. -
ninja install
can be run to install the built library andinclude
files to a location of choice, which can be specified by passing the-DCMAKE_INSTALL_PREFIX=<dir>
option tocmake
at configure time. Alternatively,ninja package
can be run to create an install package.
Windows
Binaries can be generated using Visual Studio 2019 with the CMake Tools extension installed. The same options as explained above for Linux/macOS can be used and build artifacts are generated in the specified build
folders.
If you want to create Visual Studio build files, e.g., if not using ninja
, be sure to not pass the parameter -GNinja
to the cmake
command as exemplified above. You can then build all components using msbuild
, e.g. as follows: msbuild ALL_BUILD.vcxproj
and install all artifacts e.g. using this command msbuild INSTALL.vcxproj
.
Cross compilation
You can cross compile liboqs for various platforms. Detailed information is available in the Wiki.
Documentation
More detailed information on building, optional build parameters, example applications, coding conventions and more can be found in the wiki.
Contributing
Contributions that meet the acceptance criteria are gratefully welcomed. See our Contributing Guide for more details.
License
liboqs is licensed under the MIT License; see LICENSE.txt for details.
liboqs includes some third party libraries or modules that are licensed differently; the corresponding subfolder contains the license that applies in that case. In particular:
.CMake/CMakeDependentOption.cmake
: BSD 3-Clause Licensesrc/common/common.c
: includes portions which are Apache License v2.0src/common/crypto/aes/aes_c.c
: public domain or any OSI-approved licensesrc/common/crypto/aes/aes*_ni.c
: public domainsrc/common/crypto/sha2/sha2_c.c
: public domainsrc/common/crypto/sha3/xkcp_low
: CC0 (public domain), exceptbrg_endian.h
andKeccakP-1600-AVX2.s
src/common/crypto/sha3/xkcp_low/.../brg_endian.h
: BSD 3-Clause Licensesrc/common/crypto/sha3/xkcp_low/.../KeccakP-1600-AVX2.s
: BSD-like CRYPTOGAMS licensesrc/common/rand/rand_nist.c
: See filesrc/kem/bike/additional
: Apache License v2.0src/kem/classic_mceliece/pqclean_*
: public domainsrc/kem/kyber/pqcrystals-*
: public domain (CC0) or Apache License v2.0src/kem/kyber/pqclean_*
: public domainsrc/sig/dilithium/pqcrystals-*
: public domain (CC0) or Apache License v2.0src/sig/dilithium/pqclean_*
: public domainsrc/sig/sphincs/pqclean_*
: CC0 (public domain)
Acknowledgements
Various companies, including Amazon Web Services, Cisco Systems, evolutionQ, IBM Research, and Microsoft Research have dedicated programmer time to contribute source code to OQS. Various people have contributed source code to liboqs.
Financial support for the development of Open Quantum Safe has been provided by Amazon Web Services, the Canadian Centre for Cyber Security, the Unitary Fund, the NGI Assure Fund, and VeriSign Inc.
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 the source papers for funding acknowledgments.