diff --git a/CONFIGURE.md b/CONFIGURE.md index c40b3de3d0..94da895335 100644 --- a/CONFIGURE.md +++ b/CONFIGURE.md @@ -7,21 +7,22 @@ The following options can be passed to CMake before the build file generation pr - [CMAKE_INSTALL_PREFIX](#CMAKE_INSTALL_PREFIX) - [OQS_ALGS_ENABLED](#OQS_ALGS_ENABLED) - [OQS_BUILD_ONLY_LIB](#OQS_BUILD_ONLY_LIB) -- [OQS_ENABLE_KEM_\/OQS_ENABLE_SIG_\](#OQS_ENABLE_KEM_\/OQS_ENABLE_SIG_\) +- [OQS_ENABLE_KEM-ALG](#OQS_ENABLE_KEM_ALG) +- [OQS_ENABLE_SIG-ALG](#OQS_ENABLE_SIG_ALG) - [OQS_MINIMAL_BUILD](#OQS_MINIMAL_BUILD) - [OQS_DIST_BUILD](#OQS_DIST_BUILD) -- [OQS_USE_\_INSTRUCTIONS](OQS_USE_\_INSTRUCTIONS) +- [OQS_USE_CPU_FEATURE_INSTRUCTIONS](OQS_USE_CPU_FEATURE_INSTRUCTIONS) - [OQS_USE_OPENSSL](#OQS_USE_OPENSSL) - [OQS_OPT_TARGET](#OQS_OPT_TARGET) - [OQS_SPEED_USE_ARM_PMU](#OQS_SPEED_USE_ARM_PMU) - [USE_SANITIZER](#USE_SANITIZER) - [OQS_ENABLE_TEST_CONSTANT_TIME](#OQS_ENABLE_TEST_CONSTANT_TIME) -## BUILD_SHARED_LIBS +## BUILD_SHARED_LIBS {#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 +## CMAKE_BUILD_TYPE {#CMAKE_BUILD_TYPE} Can be set to the following values: @@ -29,15 +30,15 @@ Can be set to the following values: - `Release`: This compiles code at the `O3` optimization level, and sets other compiler flags that reduce the size of the binary. -## CMAKE_INSTALL_PREFIX +## CMAKE_INSTALL_PREFIX {#CMAKE_INSTALL_PREFIX} See the [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). -## OQS_ALGS_ENABLED +## OQS_ALGS_ENABLED {#OQS_ALGS_ENABLED} Selects algorithm set enabled. Possible values are "STD" selecting all algorithms standardized by NIST; "NIST_R4" selecting all algorithms evaluated in round 4 of the NIST PQC competition; "All" (or any other value) selecting all algorithms integrated into liboqs. If the parameter is not given "STD" is set by default. -## OQS_ENABLE_KEM_\/OQS_ENABLE_SIG_\ +## OQS_ENABLE_KEM_ALG> {#OQS_ENABLE_KEM_ALG} This can be set to `ON` or `OFF`, and is `ON` by default. When `OFF`, `` and its code are excluded from the build process. When `ON`, made available are additional options whereby individual variants of `` can be excluded from the build process. @@ -45,17 +46,25 @@ For example: if `OQS_ENABLE_KEM_BIKE` is set to `ON`, the options `OQS_ENABLE_KE For a full list of such options and their default values, consult [.CMake/alg_support.cmake](https://github.com/open-quantum-safe/liboqs/blob/master/.CMake/alg_support.cmake). -## OQS_BUILD_ONLY_LIB +## OQS_ENABLE_SIG_ALG> {#OQS_ENABLE_SIG_ALG} + +This can be set to `ON` or `OFF`, and is `ON` by default. When `OFF`, `` and its code are excluded from the build process. When `ON`, made available are additional options whereby individual variants of `` can be excluded from the build process. + +For example: if `OQS_ENABLE_SIG_DILITHIUM` is set to `ON`, the options `OQS_ENABLE_SIG_dilithium2`, `OQS_ENABLE_SIG_dilithium3`, `OQS_ENABLE_SIG_dilithium5` 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](https://github.com/open-quantum-safe/liboqs/blob/master/.CMake/alg_support.cmake). + +## OQS_BUILD_ONLY_LIB {#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_MINIMAL_BUILD +## OQS_MINIMAL_BUILD {#OQS_MINIMAL_BUILD} 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="KEM_kyber_768;SIG_dilithium_3" ..` will build a minimum-size `liboqs` library only containing support for Kyber768 and Dilithium3. The full list of identifiers that can set are listed [here for KEM algorithms](https://github.com/open-quantum-safe/liboqs/blob/main/src/kem/kem.h#L34) and [here for Signature algorithms](https://github.com/open-quantum-safe/liboqs/blob/f3caccff9e6225e7c50ca27f5ee6e58b7bc74188/src/sig/sig.h#L34). Default setting is empty, thus including all [supported algorithms](https://github.com/open-quantum-safe/liboqs#supported-algorithms) in the build. -## OQS_DIST_BUILD +## OQS_DIST_BUILD {#OQS_DIST_BUILD} Can be `ON` or `OFF`. When `ON`, build liboqs for distribution. When `OFF`, build liboqs for use on a single machine. @@ -65,17 +74,17 @@ When built for distribution, the library will run on any CPU of the target archi 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_OPT_TARGET)). -## OQS_USE_\_INSTRUCTIONS +## OQS_USE_CPU_FEATURE_INSTRUCTIONS {#OQS_USE_CPU_FEATURE_INSTRUCTIONS} These can be set to `ON` or `OFF` and take an effect if liboqs is built for use on a single machine. By default, the CPU features are automatically determined and set to `ON` or `OFF` based on the CPU features available on the build system. The default values can be overridden by providing CMake build options. The available options on x86-64 are: `OQS_USE_ADX_INSTRUCTIONS`, `OQS_USE_AES_INSTRUCTIONS`, `OQS_USE_AVX_INSTRUCTIONS`, `OQS_USE_AVX2_INSTRUCTIONS`, `OQS_USE_AVX512_INSTRUCTIONS`, `OQS_USE_BMI1_INSTRUCTIONS`, `OQS_USE_BMI2_INSTRUCTIONS`, `OQS_USE_PCLMULQDQ_INSTRUCTIONS`, `OQS_USE_VPCLMULQDQ_INSTRUCTIONS`, `OQS_USE_POPCNT_INSTRUCTIONS`, `OQS_USE_SSE_INSTRUCTIONS`, `OQS_USE_SSE2_INSTRUCTIONS` and `OQS_USE_SSE3_INSTRUCTIONS`. The available options on ARM64v8 are `OQS_USE_ARM_AES_INSTRUCTIONS`, `OQS_USE_ARM_SHA2_INSTRUCTIONS`, `OQS_USE_ARM_SHA3_INSTRUCTIONS` and `OQS_USE_ARM_NEON_INSTRUCTIONS`. -## OQS_USE_OPENSSL +## OQS_USE_OPENSSL {#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 to control whether liboqs uses OpenSSL's AES, SHA-2, and SHA-3 implementations. By default, `OQS_USE_AES_OPENSSL` is `ON` (on x86-64 only if `OQS_DIST_BUILD` and `OQS_USE_AES_INSTRUCTIONS` are not set), `OQS_USE_SHA2_OPENSSL` is `ON` while `OQS_USE_SHA3_OPENSSL` is `OFF`. When `OQS_USE_OPENSSL` 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 +## OQS_OPT_TARGET {#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` (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. - `auto`: Use `-march=native` or `-mcpu=native` (if the compiler supports it). @@ -83,7 +92,7 @@ An optimization target. Only has an effect if the compiler is GCC or Clang and ` The default value is `auto`. -## OQS_SPEED_USE_ARM_PMU +## OQS_SPEED_USE_ARM_PMU {#OQS_SPEED_USE_ARM_PMU} Can be `ON` or `OFF`. When `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. @@ -91,7 +100,7 @@ In order to use this option, user mode access to the PMU must be enabled via a k Note that this option is not known to work on Apple M1 chips. -## USE_SANITIZER +## USE_SANITIZER {#USE_SANITIZER} This has effect when the compiler is Clang and when [CMAKE_BUILD_TYPE](#CMAKE_BUILD_TYPE) is `Debug`. Then, it can be set to: @@ -102,6 +111,6 @@ This has effect when the compiler is Clang and when [CMAKE_BUILD_TYPE](#CMAKE_BU - `Thread`: This enables Clang's `ThreadSanitizer` - `Leak`: This enables Clang's `LeakSanitizer` -## OQS_ENABLE_TEST_CONSTANT_TIME +## OQS_ENABLE_TEST_CONSTANT_TIME {#OQS_ENABLE_TEST_CONSTANT_TIME} 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](#CMAKE_BUILD_TYPE) set to `Debug`. See the documentation in [`tests/test_constant_time.py`](https://github.com/open-quantum-safe/liboqs/blob/main/tests/test_constant_time.py) for more information on usage.