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

Setup Types

The standard setup process uses the last tested commits of the project's dependency libraries to ensure compatibility with this project's automation tools. The setup script performs system detection, installs all required components, and supports multiple installation modes depending on the desired testing configuration.

While the default configuration prioritises stability, users may optionally configure the setup to pull newer versions of the OQS libraries. This can be useful for testing upstream changes or recent algorithm updates. For more advanced configuration options, 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.sh

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. Computational Performance Testing Only - Installs components for standalone performance benchmarking (CPU and memory).

  2. Full Install - Installs all components for both computational and TLS performance testing.

  3. TLS Testing Libraries Only - Installs only the TLS benchmarking components. (Requires Option 1 has already been completed).

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

If the TLS testing libraries are installed (Options 2 or 3), you will be prompted with the following additional setup options:

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

  • Enable KEM encoders – Adds support for OpenSSL’s optional KEM encoder functionality. The benchmarking suite does not currently use this feature, but it 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 this process manually. Please refer to the Advanced Setup Configuration Guide 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 that 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 project's root directory:

touch .pqc_eval_dir_marker.tmp

Optional Setup Flags

For advanced setup options, including:

  • Pulling the latest version of the OQS libraries rather than the default tested versions
  • Custom OpenSSL speed.c limits
  • Enabling HQC algorithms in the OQS Libraries

Please refer to the Advanced Setup Configuration Guide page.