Skip to content

Customizing liboqs

Jump to bottom
xvzcf edited this page Mar 18, 2020 · 20 revisions

The following options can be passed to CMake before the build file generation process to customize the way liboqs is built:

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
  • Generic: This compiles code at the O3 optimization level, and sets other compiler flags that reduce the size of the binary. Since their detection is not done during runtime, CPU extensions such as AVX2, SSE, etc., are not enabled so as to preserve portability. This value only has effect when the compiler is GCC or Clang
  • Optimized: This compiles the code with all compiler flags used in the Generic build type and -march=native to enable the use of CPU extensions. The resulting binary will not be portable. This value only has effect when the compiler is GCC or Clang
  • Dependency: This is for third-party software built using CMake that consumes liboqs as a dependency. If specified, only the library is built, and targets such as run_tests and gen_docs are not made available to the build system. This can prevent name collisions, for example, when add_subdirectory() is used to incorporate liboqs into the build system

OQS_BUILD_TYPE

This is identical to CMAKE_BUILD_TYPE. It is a separate option so that third-party software (using CMake as their build system) can use add_subdirectory() to incorporate liboqs into the build process and can set the CMAKE_BUILD_TYPE for their projects as desired.

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.

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

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_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_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.

Clone this wiki locally