Getting started

Linux and Mac

1. 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 openssl@3 wget doxygen graphviz astyle valgrind
    pip3 install pytest pytest-xdist pyyaml
   

   Using Nix:

    nix develop
   

   Note that, if you want liboqs to use OpenSSL for various symmetric crypto algorithms (AES, SHA-2, etc.) then you must have OpenSSL installed (version 3.x recommended; EOL version 1.1.1 also still possible).

2. 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 -N .. in the build directory.

The following instructions assume we are in build.

1. 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 the cmake -GNinja .. command above and the result will be lib/liboqs.so|dylib|dll. The public headers are located in the include directory. There are also a variety of programs built under the tests directory:

   • test_kem: Simple test harness for key encapsulation mechanisms
   • test_sig: Simple test harness for signature schemes
   • test_sig_stfl: Simple test harness for stateful signature schemes
   • test_kem_mem: Simple test harness for checking memory consumption of key encapsulation mechanisms
   • test_sig_mem: Simple test harness for checking memory consumption of signature schemes
   • kat_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 using tests/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 using tests/test_kat.py
   • kat_sig_stfl: Program for checking results against submitted KAT values using tests/test_kat.py
   • speed_kem: Benchmarking program for key encapsulation mechanisms; see ./speed_kem --help for usage instructions
   • speed_sig: Benchmarking program for signature mechanisms; see ./speed_sig --help for usage instructions
   • speed_sig_stfl: Benchmarking program for stateful signature mechanisms; see ./speed_sig_stfl --help for usage instructions
   • example_kem: Minimal runnable example showing the usage of the KEM API
   • example_sig: Minimal runnable example showing the usage of the signature API
   • example_sig_stfl: Minimal runnable example showing the usage of the stateful signature API
   • test_aes, test_sha3: Simple test harnesses for crypto sub-components
   • test_portability: Simple test harnesses for checking cross-CPU code portability; requires presence of qemu; proper operation validated only on Ubuntu

   The complete test suite can be run using

    ninja run_tests
   

2. To generate HTML documentation of the API, run:

    ninja gen_docs
   

   Then open docs/html/index.html in your web browser.

3. ninja install can be run to install the built library and include files to a location of choice, which can be specified by passing the -DCMAKE_INSTALL_PREFIX=<dir> option to cmake at configure time. Alternatively, ninja package can be run to create an install package.

4. ninja uninstall can be run to remove all installation files.

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.