Skip to content

Customizing liboqs

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

Various options can be passed to cmake during the build file generation process that can be used to customize the way liboqs is built, and what its functionality is. This page lists and explains each of these options.

List of Options

CMAKE_BUILD_TYPE

It can take the following values:

  • Debug: This will turn off all optimizations and compile the code with debug information included. For this value, when the compiler is Clang, the USE_SANITIZER flag can also be passed in to enable a Clang Sanitizer build. This value only has effect when the compiler is GCC or Clang.
  • Generic: This enables code to built with the O3 optimization level, and other flags are set that reduce the binary size. This does not enable CPU extensions such as AVX2, SSE, etc., so as to preserve the resulting binary's portability, since such feature detection is not done during runtime. This value only has effect when the compiler is GCC or Clang.
  • Optimized: This, along with all the flags enabled by the Generic value, adds the -march=native flag to enable the use of CPU features. 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 that use liboqs as a dependency. When specified, only liboqs is built, and targets such as run_tests, 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 process.

OQS_BUILD_TYPE

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

USE_SANITIZER

This has effect when the compiler is Clang and when CMAKE_BUILD_TYPE is Debug. Then, it can take the following values:

  • 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 origins of uninitialized values
  • Undefined: This enables Clang's UndefinedBehaviorSanitizer. Here, the BLACKLIST_FILE option can be specified additionally to specify 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

liboqs exposes OQS_KEM_alg_default as part of it's API. This represents the default key-exchange algorithm and can be set at compile-time through the OQS_KEM_DEFAULT option. For example: to set the default KEM to Frodo 976 AES, the option -DOQS_KEM_DEFAULT="OQS_KEM_alg_frodokem_976_aes" can be passed in. The full list of the possible identifiers that can be specified can be found in src/kem/kem.h.

OQS_SIG_DEFAULT

liboqs exposes OQS_SIG_alg_default as part of it's API. This represents the default digital signature algorithm and can be set at compile-time through the OQS_SIG_DEFAULT option. For example: to set the default SG to Dilithium 2, the option -DOQS_SIG_DEFAULT="OQS_SIG_alg_dilithium_2" can be passed in. The full list of the possible identifiers that can be specified can be found in src/sig/sig.h.

OQS_USE_OPENSSL

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

When set to ON, CMake also scans the filesystem to find a version of OpenSSL that satisfies liboqs' requirements (which happens to be 1.1.1). The OPENSSL_ROOT_DIR option can be passed 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, further options are enabled 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