Clone this wiki locally
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
Can be set to
ON, liboqs is built as a shared library. It is
OFF by default, which means liboqs is built as a static library by default.
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
O3optimization level, and sets other compiler flags that reduce the size of the binary.
See the CMake documentation.
This can be set to
OFF, and is
ON by default. When
<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_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.
ON, only liboqs is built, and all the targets:
prettyprint are excluded from the build system.
If set, this defines a semicolon deliminated list of algorithms to be contained in a minimal build of
liboqs: Only algorithms explicitly set here are included in a build: For example running
cmake -DOQS_MINIMAL_BUILD="OQS_ENABLE_KEM_kyber_768;OQS_ENABLE_SIG_dilithium_3" .. will build a minimum-size
liboqs library only containing support for Kyber768 and Dilithium3.
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).
This can be set to
ON, the additional options
OQS_USE_SHA3_OPENSSL are made available to control whether liboqs uses OpenSSL's AES, SHA-2, and SHA-3 implementations. By default,
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.
Setting this option to
OFF is also recommended when
liboqs is intended for use within OQS-OpenSSL(1.1.1) on a system with a default OpenSSLv3 installation: Otherwise, the reference to
libcrypto cannot be done correctly: If built with OQS_USE_OPENSSL=ON
liboqs would depend in such environment on
libcrypto3 while oqs-openssl would create libcrypto1.1. In such environment, the use of oqs-provider should be considered.
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 (on x86_64) or
-mcpu (on ARM32v7 or ARM64v8) option for
CMAKE_C_COMPILER. Can also be set to one of the following special values.
-mcpu=native(if the compiler supports it).
-march=x86-64on x86-64, or
-mcpu=cortex-a5on ARM32v7, or
The default value is
ON, the benchmarking script will try to use the ARMv8 Performance Monitoring Unit (PMU). This will make cycle counts on ARMv8 platforms significantly more accurate.
In order to use this option, user mode access to the PMU must be enabled via a kernel module. If user mode access is not enabled via kernel module, benchmarking will throw an
Illegal Instruction error. A kernel module that has been found to work on several platforms can be found here for linux. Follow the instructions there (i.e., clone the repository,
cd enable_ccr and
make install) to load the kernel module, after which benchmarking should work. Superuser permissions are required. Linux header files must also be installed on your platform, which may not be present by default.
Note that this option is not known to work on Apple M1 chips.
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
Memory: This enables Clang's
MemoryWithOrigins: This enables Clang's
MemorySanitizerwith the added functionality of being able to track the origins of uninitialized values
Undefined: This enables Clang's
BLACKLIST_FILEoption can be additionally set to a path to a file listing the entities Clang should ignore.
Thread: This enables Clang's
Leak: This enables Clang's
This is used in conjunction with
tests/test_constant_time.py to use Valgrind to look for instances of secret-dependent control flow. liboqs must also be compiled with CMAKE_BUILD_TYPE set to
Debug. See the documentation in
tests/test_constant_time.py for more information on usage.