Link Search Menu Expand Document

Getting started

Linux/macOS

  1. Install dependencies:

    On Ubuntu:

      sudo apt install cmake gcc ninja-build libssl-dev python3-pytest python3-pytest-xdist unzip xsltproc doxygen graphviz
    

    On macOS, using a package manager of your choice (we’ve picked Homebrew):

     brew install cmake ninja openssl@1.1 wget doxygen graphviz
     pip3 install pytest pytest-xdist
    

    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.

  2. Get the source:

     git clone -b master https://github.com/open-quantum-safe/liboqs.git
     cd liboqs
    

    and build:

     mkdir build && cd build
     cmake -GNinja ..
     ninja
    

Various options can be passed to cmake to customize the build. Some of them include:

  • -DOQS_USE_OPENSSL=<val>: <val> can be ON or OFF; when ON, liboqs uses OpenSSL’s AES, SHA-2, and SHA-3 implementations.
  • -DBUILD_SHARED_LIBS=<val>: <val> can be ON or OFF; when ON, CMake generates instructions for building a shared library, otherwise it generates instructions for building a static library.
  • -DOPENSSL_ROOT_DIR=<dir>: <dir> specifies the directory in which CMake will look for OpenSSL.

All supported options are listed in the .CMake/alg-support.cmake file, and can be viewed by running cmake -LAH .. in the build directory. They are also listed and explained in the wiki.

The following instructions assume we are in build.

  1. The main build result is lib/liboqs.a, a static library. 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 key 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
    • 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
    • example_kem: Minimal runnable example showing the usage of the KEM API
    • example_sig: Minimal runnable example showing the usage of the signature API
    • test_aes, test_sha3: Simple test harnesses for crypto sub-components

    The test suite can be run using

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

     ninja gen_docs
    

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

  3. Finally, 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.

Windows

Binaries can be generated using Visual Studio 2019 with the CMake Tools extension installed.

Cross compilation

You can cross compile liboqs for various platform by supplying CMake with an appropriate toolchain file.

For example, to cross compile for a Raspberry Pi from Ubuntu Bionic:

apt install gcc-8-arm-linux-gnueabihf
mkdir build && cd build
cmake -GNinja -DCMAKE_TOOLCHAIN_FILE=../.CMake/toolchain_rasppi.cmake -DOQS_USE_OPENSSL=OFF ..
ninja

Or to compile for Windows AMD64 from Ubuntu Bionic:

apt install gcc-mingw-w64
mkdir build && cd build
cmake -GNinja -DCMAKE_TOOLCHAIN_FILE=../.CMake/toolchain_windows-amd64.cmake -DOQS_USE_CPU_EXTENSIONS=OFF ..
ninja







Copyright © 2017-2020 The Open Quantum Safe Project.
This site uses Just the Docs, a documentation theme for Jekyll. Background image by Rick Doble.