Skip to content

Customizing liboqs

Jump to bottom
Michael Baentsch edited this page Jan 7, 2021 · 20 revisions

The following options can be passed to CMake before the build file generation process to customize the way liboqs is built. The syntax for doing so is: cmake .. [ARGS] [-D<OPTION_NAME>=<OPTION_VALUE>]..., where <OPTON_NAME> is:

BUILD_SHARED_LIBS

Can be set to ON or OFF. When ON, liboqs is built as a shared library. It is OFF by default, which means liboqs is built as a static library by default.

CMAKE_BUILD_TYPE

Can be set to the following values:

  • Debug: This turns off all compiler optimizations and produces debugging information. When the compiler is Clang, the USE_SANITIZER option can also be specified to enable a Clang sanitizer. This value only has effect when the compiler is GCC or Clang

  • Release: This compiles code at the O3 optimization level, and sets other compiler flags that reduce the size of the binary.

CMAKE_INSTALL_PREFIX

See the CMake documentation.

OQS_ENABLE_KEM_<ALG>/OQS_ENABLE_SIG_<ALG>

This can be set to ON or OFF, and is ON by default. When OFF, <ALG> and its code are excluded from the build process. When ON, made available are additional options whereby individual variants of <ALG> can be excluded from the build process.

For example: if OQS_ENABLE_KEM_BIKE is set to ON, the options OQS_ENABLE_KEM_bike1_l1_cpa, OQS_ENABLE_KEM_bike1_l1_fo, OQS_ENABLE_KEM_bike1_l3_cpa, OQS_ENABLE_KEM_bike1_l3_fo are made available (and are set to be ON by default).

For a full list of such options and their default values, consult .CMake/alg_support.cmake.

OQS_BUILD_ONLY_LIB

Can be ON or OFF. When ON, only liboqs is built, and all the targets: run_tests, gen_docs, and prettyprint are excluded from the build system.

OQS_KEM_DEFAULT

OQS_KEM_alg_default is an identifier exposed by the liboqs API that can be used to refer to a "default" key-exchange algorithm; it can be set at compile-time through the OQS_KEM_DEFAULT option. For example: to set the default key-exchange algorithm to FrodoKEM-640-AES, the option -DOQS_KEM_DEFAULT="OQS_KEM_alg_frodokem_640_aes" can be passed to CMake.

A full list of identifiers that can assigned to OQS_KEM_DEFAULT is found in src/kem/kem.h.

OQS_PORTABLE_BUILD

Can be ON or OFF. When ON, the resulting binary can run on any CPU having the same architecture as the CPU on which the binary was built.

This means that if OQS_USE_CPU_EXTENSIONS is ON, code using CPU extensions (like SSE3 or AVX2) is included only in those places where runtime CPU extension detection and function dispatch is performed (thereby ensuring portability).

OQS_SIG_DEFAULT

OQS_SIG_alg_default is an identifier exposed by the liboqs API that can be used to refer to a "default" digital signature algorithm; it can be set at compile-time through the OQS_SIG_DEFAULT option. For example: to set the default digital signature algorithm to DILITHIUM_2, the option -DOQS_SIG_DEFAULT="OQS_SIG_alg_dilithium_2" can be passed to CMake.

A full list of identifiers that can assigned to OQS_SIG_DEFAULT is found in src/sig/sig.h.

OQS_USE_OPENSSL

This can be set to ON or OFF. When ON, the additional options OQS_USE_AES_OPENSSL, OQS_USE_SHA2_OPENSSL, and OQS_USE_SHA3_OPENSSL are made available and are set to ON by default: they control whether liboqs uses OpenSSL's AES, SHA-2, and SHA-3 implementations.

When this is ON, CMake also scans the filesystem to find the minimum version of OpenSSL required by liboqs (which happens to be 1.1.1). The OPENSSL_ROOT_DIR option can be set to aid CMake in its search.

OQS_USE_CPU_EXTENSIONS

Can be set to ON or OFF. When ON, code that uses CPU-specific extensions is included in the build.

If OQS_PORTABLE_BUILD is ON, code using CPU-specific extensions (like SSE3 or AVX2) is included only in those places where runtime CPU extension detection and function dispatch is performed (thereby ensuring portability). In consequence algorithms without such function dispatch may run slower if both OQS_PORTABLE_BUILD and OQS_USE_CPU_EXTENSIONS are set.

This only has effect when the compiler is either GCC or Clang.

USE_SANITIZER

This has effect when the compiler is Clang and when CMAKE_BUILD_TYPE is Debug. Then, it can be set to:

  • Address: This enables Clang's AddressSanitizer
  • Memory: This enables Clang's MemorySanitizer
  • MemoryWithOrigins: This enables Clang's MemorySanitizer with the added functionality of being able to track the origins of uninitialized values
  • Undefined: This enables Clang's UndefinedBehaviorSanitizer. The BLACKLIST_FILE option can be additionally set to a path to a file listing the entities Clang should ignore.
  • Thread: This enables Clang's ThreadSanitizer
  • Leak: This enables Clang's LeakSanitizer
Clone this wiki locally