Skip to content

Customizing liboqs

Jump to bottom
John Schanck edited this page Mar 31, 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_MINIMAL_BUILD

Can be ON or OFF. Default is OFF. When ON, liboqs is built only with the default KEM and SIG algorithms (as can be set with OQS_KEM_DEFAULT and OQS_SIG_DEFAULT, respectively) and thus delivers a very small library/executable.

OQS_DIST_BUILD

Can be ON or OFF. When ON, build liboqs for distribution. When OFF, build liboqs for use on a single machine.

The library is always built for a particular architecture, either x86-64, ARM32v7, or ARM64v8, depending on the setting of CMAKE_SYSTEM_PROCESSOR. But liboqs contains code that is optimized for micro-architectures as well, e.g. x86-64 with the AVX2 extension.

When built for distribution, the library will run on any CPU of the target architecture. Function calls will be dispatched to micro-architecture optimized routines at run-time using CPU feature detection.

When built for use on a single machine, the library will only include the best available code for the target micro-architecture (see OQS_OPT_TARGET).

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_OPT_TARGET

An optimization target. Only has an effect if the compiler is GCC or Clang and OQS_DIST_BUILD=OFF. Can take any valid input to the -march compiler option (on x86_64) or the -mcpu option (on ARM32v7 or ARM64v8). Can also be set to one of the following special values.

  • auto: Use -march=native or -mcpu=native (if the compiler supports it).
  • generic: Use -march=x86-64 on x86-64, or -mcpu=cortex-a5 on ARM32v7, or -mcpu=cortex-a53 on ARM64v8.

The default value is auto.

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