Installation Instructions - crt26/pqc-evaluation-tools GitHub Wiki

Setup Types

This page describes how to clone the repository and run the setup script to install the required OQS libraries and OpenSSL version. The setup process supports both default and safe-mode configurations depending on your testing requirements.

The standard setup process uses the latest versions of the OQS libraries and performs automatic system detection and installation of the benchmarking suite. It supports various installation modes that determine which OQS libraries are downloaded and built, depending on your environment.

The main setup script also provides a safe-mode option, which can be used if there are any issues with the latest versions of the OQS libraries. When safe-mode is enabled, the script downloads and builds the last tested versions of the OQS libraries that are known to work reliably with this project. For more details on using safe-mode, see the Optional Setup Flags section.

The following instructions describe the standard setup process, which is the default and recommended option.

Cloning the Repository

Clone the current stable version:

git clone https://github.com/crt26/pqc-evaluation-tools.git

Move into the cloned repository directory and execute the setup script:

cd pqc-evaluation-tools
./setup

You may need to change the permissions of the setup script; if that is the case, this can be done using the following commands:

chmod +x setup.sh

Choosing the Installation Mode

When executing the setup script, you will be prompted to select one of the following installation options:

  1. Build only the Liboqs library – For PQC computational performance testing only.

  2. Build both the Liboqs and OQS-Provider libraries – For full testing, including PQC performance and PQC TLS benchmarking.

  3. Build only the OQS-Provider library – For use after a prior Liboqs installation.

The setup script will also build OpenSSL 3.4.1 inside the repository’s lib directory. This version is required to support the OQS-Provider and is built separately from the system’s default OpenSSL installation. It will not interfere with system-level binaries.

If the installation of the OQS-Provider library is selected, the setup script will prompt you to enable two optional features:

  • Enable all disabled signature algorithms – Includes all digital signature algorithms in the OQS-Provider build that are disabled by default. This ensures the full range of supported algorithms can be tested in the TLS performance benchmarking †.

  • Enable KEM encoders – Adds support for OpenSSL’s optional KEM encoder functionality. The benchmarking suite does not currently use this feature but is available for developers who wish to experiment with it.

Once all the relevant options have been selected, the setup script will download, configure and build each library. It will also tailor the builds for your system architecture by applying appropriate build flags.

† Enabling all signature algorithms may cause the OpenSSL speed tool to fail due to internal limits in its source code. The setup script attempts to patch this automatically, but you can configure it manually. Please refer to the Advanced Setup Configuration Guide page for further details.

Ensuring Root Dir Path Marker is Present

A hidden file named .pqc_eval_dir_marker.tmp is created in the project's root directory during setup. Automation scripts use this marker to reliably identify the root path, which is essential for their correct operation.

When running the setup script, it is vital that this is done from the root of the repository so this file is placed correctly.

Do not delete or rename this file while the project is in a configured state. It will be automatically removed when uninstalling all libraries using the cleaner.sh utility script. If the file is removed manually, it can be regenerated by rerunning the setup script or creating it manually.

To verify the file exists, use:

ls -la

To manually recreate the file, run the following command from the root directory:

touch .pqc_eval_dir_marker.tmp

Optional Setup Flags

For advanced setup options, including:

  • safe-mode for using the last tested versions of the dependency libraries,
  • Custom OpenSSL speed.c limits,
  • Enabling HQC algorithms in Liboqs

Please refer to the Advanced Setup Configuration Guide page.