The Open Quantum Safe (OQS) project has the goal of developing and prototyping quantum-resistant cryptography.
liboqs-cpp offers a C++ wrapper for the Open Quantum Safe liboqs C library, which is a C library for quantum-resistant cryptographic algorithms.
The wrapper is written in standard C++11, hence in the following it is assumed that you have access to a C++11 compliant compiler. liboqs-cpp has been extensively tested on Linux, macOS and Windows platforms. Continuous integration is provided via GitHub actions.
The project contains the following files and directories:
include/oqs_cpp.hpp: main header file for the wrapperinclude/common.hpp: utility codeinclude/rand/rand.hpp: support for RNGs from<oqs/rand.h>examples/kem.cpp: key encapsulation exampleexamples/rand.cpp: RNG exampleexamples/sig.cpp: signature exampleunit_tests: unit tests written using GoogleTest
Execute in a Terminal/Console/Administrator Command Prompt
git clone --depth=1 https://github.com/open-quantum-safe/liboqs
cmake -S liboqs -B liboqs/build -DBUILD_SHARED_LIBS=ON
cmake --build liboqs/build --parallel 8
cmake --build liboqs/build --target installThe last line may require prefixing it by sudo on UNIX-like systems.
Change --parallel 8 to match the number of available cores on your system.
On UNIX-like platforms, you may need to set
the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH on macOS) environment variable to
point to the path to liboqs' library directory, e.g.,
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/libOn Windows platforms, you must ensure that the liboqs shared
library oqs.dll is visible system-wide, and that the following environment
variable are being set. Use the "Edit the system environment variables" Control
Panel tool or execute in a Command Prompt, e.g.,
set PATH=%PATH%;C:\Program Files (x86)\liboqs\binYou can change liboqs' installation directory by configuring the build to use an
alternative path, e.g., C:\liboqs, by replacing the first CMake line above by
cmake -S liboqs -B liboqs/build -DCMAKE_INSTALL_PREFIX="C:\liboqs" -DBUILD_SHARED_LIBS=ONExecute in a Terminal/Console/Administrator Command Prompt
git clone --depth=1 https://github.com/open-quantum-safe/liboqs-cpp
cmake -S liboqs-cpp -B liboqs-cpp/build
cmake --build liboqs-cpp/build --target installExecute, on UNIX-like platforms
cmake --build liboqs-cpp/build --target examples --parallel 8and, on Windows platforms
cmake --build liboqs-cpp/build --target examples -DLIBOQS_INCLUDE_DIR="C:\Program Files (x86)\liboqs\include" -DLIBOQS_LIB_DIR="C:\Program Files (x86)\liboqs\lib" --parallel 8Note that you may need to change the flags -DLIBOQS_INCLUDE_DIR
and -DLIBOQS_LIB_DIR to point to the correct location of liboqs in case you
installed it in a non-standard location.
To build only a specific target, e.g. examples/kem, specify the target as the
argument of the cmake command, e.g.,
cmake --build liboqs-cpp/build --target kemExecute
liboqs-cpp/build/kem
liboqs-cpp/build/sig
liboqs-cpp/build/randNote that on Windows platforms, the location and the names of the built examples
may be slightly different, e.g., liboqs-cpp/build/Debug/kem.exe.
Execute
cmake --build liboqs-cpp/build/unit_tests --target unit_tests --parallel 8followed by
ctest --test-dir liboqs-cpp/buildliboqs-cpp is a header-only wrapper. To use liboqs-cpp, you only need to
#include <liboqs-cpp/oqs_cpp.hpp>in your application, and have liboqs library installed as described above. See examples/standalone for a standalone example.
To avoid namespace pollution, liboqs-cpp includes all of its code inside the
namespace oqs. All the liboqs C API is located in the namespace oqs::C,
hence to use directly a C API function you must qualify the call
with oqs::C::liboqs_C_function(...).
liboqs-cpp defines four main classes: oqs::KeyEncapsulation
and oqs::Signature, providing post-quantum key encapsulation and signture
mechanisms, respectively, and
oqs::KEMs and oqs::Sigs, containing only static member functions that
provide information related to the available key encapsulation mechanisms or
signature mechanism, respectively.
oqs::KeyEncapsulation and/or oqs::Signature must be instantiated with a
string identifying one of mechanisms supported by liboqs; these can be
enumerated using the oqs::KEMs::get_enabled_KEM_mechanisms()
and oqs::Sigs::get_enabled_sig_mechanisms() member functions.
Support for alternative RNGs is provided by the include/rand/rand.hpp header
file, which exports its functions in namespace oqs::rand. This header file
must be explicitly included in order to activate the support for alternative
RNGs.
The wrapper also defines a high resolution timing class, oqs::Timer<>.
The examples in
the examples
directory are self-explanatory stand-alone applications and provide more details
about the wrapper's API and its usage.
To generate the full official API documentation in both PDF and HTML formats run
doxygen on
the Doxyfile
file. The tool dot from the Graphviz package
must be installed (sudo apt-get install graphviz in Ubuntu/Debian).
Running doxygen will generate the documentation directory doc containing
both the HTML and LaTeX documentation.
The HTML documentation file will be accessible by opening doc/html/index.html
with the browser of your choice.
To generate a PDF file of the documentation, run
latexmk -pdf refman.texfrom the doc/latex directory or compile the file doc/latex/refman.tex with
your LaTeX compiler. This will create the doc/latex/refman.pdf documentation
file. Consult your favourite LaTeX manual for how to compile/build LaTeX files
under your specific operating system.
A self-explanatory minimalistic Docker file is provided
in Dockerfile.
Build the image by executing
docker build -t oqs-cpp .Run, e.g., the key encapsulation example by executing
docker run -it oqs-cpp sh -c "liboqs-cpp/build/kem"Or, run the unit tests with
docker run -it oqs-cpp sh -c "ctest --test-dir liboqs-cpp/build"In case you want to use the Docker container as a development environment, mount your current project in the Docker container with
docker run --rm -it --workdir=/app -v ${PWD}:/app oqs-cpp /bin/bashliboqs is designed for prototyping and evaluating quantum-resistant cryptography. Security of proposed quantum-resistant algorithms may rapidly change as research advances, and may ultimately be completely insecure against either classical or quantum computers.
We believe that the NIST Post-Quantum Cryptography standardization project is currently the best avenue to identifying potentially quantum-resistant algorithms. liboqs does not intend to "pick winners", and we strongly recommend that applications and protocols rely on the outcomes of the NIST standardization project when deploying post-quantum cryptography.
We acknowledge that some parties may want to begin deploying post-quantum cryptography prior to the conclusion of the NIST standardization project. We strongly recommend that any attempts to do make use of so-called hybrid cryptography, in which post-quantum 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.
Just like liboqs, liboqs-cpp is provided "as is", without warranty of any kind. See LICENSE for the full disclaimer.
liboqs-cpp is licensed under the MIT License; see LICENSE for details.
The Open Quantum Safe project is led by Douglas Stebila and Michele Mosca at the University of Waterloo.
liboqs-cpp was developed by Vlad Gheorghiu at softwareQ Inc. and at the 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, softwareQ, and Microsoft 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 the source papers for funding acknowledgments.