Project Utility Scripts - crt26/pqc-evaluation-tools GitHub Wiki

These utility scripts assist with development, testing, and environment setup. Most utility scripts are located in the scripts/utility-scripts directory, except cleaner.sh and setup.sh, which is placed in the project's root for convenience. The utility scripts are primarily designed to be called from the various automation scripts in the repository, but some can be called manually if needed.

The project utility scripts include the following:

• setup.sh
• cleaner.sh
• get_algorithms.py
• configure-openssl-cnf.sh

This script automates the full environment setup for running the PQC benchmarking tools. It supports installing Liboqs, OQS-Provider, or both, based on user input, and configures the system accordingly.

Key tasks performed include:

• Installing all required system and Python dependencies (e.g., OpenSSL dev packages, CMake, Valgrind)

• Downloading and compiling OpenSSL 3.4.1

• Cloning and building specific or last-tested versions of Liboqs and OQS-Provider

• Modifying OpenSSL’s speed.c to support extended algorithm counts when needed

• Enabling optional OQS-Provider features (e.g., KEM encoders, disabled signature algorithms)

• Generating algorithm lists used by benchmarking and parsing scripts

The script also handles the automatic detection of the system architecture and adjusts the setup process accordingly:

• On x86_64, standard build options are applied

• On ARM systems (e.g., Raspberry Pi), the script enables the Performance Monitoring Unit (PMU), installs kernel headers, and configures profiling support

The script is run interactively but supports the following optional arguments for advanced use:

--safe-setup                   Use last-tested commits of all libraries  
--set-speed-new-value=<int>    Manually set MAX_KEM_NUM/MAX_SIG_NUM in speed.c
--enable-hqc-algs              Enable HQC KEM algorithms in Liboqs (default: disabled due to security concerns)  

For further information on the main setup script's usage, please refer to the main README file.

This is a utility script for cleaning the various project files from the compiling and benchmarking operations. The script provides functionality for either uninstalling the OQS and other dependency libraries from the system, clearing the old results, algorithm list files, and generated TLS keys, or both.

This Python utility script generates lists of supported cryptographic algorithms based on the currently installed versions of the Liboqs and OQS-Provider libraries. These lists are stored under the test-data/alg-lists directory and are used by benchmarking and parsing tools to determine which algorithms to run. Additionally, the utility script can be used to parse the OQS-Provider ALGORITHMS.md file to determine the number of algorithms it supports.

The setup.sh script primarily invokes this script, where an argument is passed to determine the installation and testing context. However, it can also be run manually to regenerate the algorithm list files.

The script supports the following functionality:

• Extracts supported KEM and digital signature algorithms from the Liboqs library using its built-in test binaries

• Retrieves supported PQC and Hybrid-PQC TLS algorithms from the OQS-Provider via OpenSSL

• Generates hardcoded lists of classical TLS algorithms for baseline performance comparisons

• Parses the OQS-Provider’s ALGORITHMS.md file to determine the total number of supported algorithms (used by setup.sh when configuring OpenSSL’s speed.c)

The utility script accepts the following arguments:

While running option 4 manually will work, it is unnecessary. This function is used exclusively by the setup.sh script to modify OpenSSL’s speed.c file when all OQS-Provider algorithms are enabled. Unlike the other arguments, it does not alter or create files in the repository; it only returns the algorithm count for use during setup.

Example usage when running manually:

cd scripts/utility-scripts
python3 get_algorithms.py 1

This utility script modifies the OpenSSL 3.4.1 configuration file by commenting or uncommenting lines that define the default cryptographic groups. This adjustment is required for successful key generation and TLS handshake testing using the OQS-Provider. It is highly recommended to avoid manually calling this script to avoid any potential issues with misconfiguration in the openssl.cnf file. However, if issues do occur, it is advised to re-run the automatic setup process or restore a backup of the previous conf file's state.

The automated scripts mainly use this script, however it can be called manually using the following commands:

configure-openssl-cnf.sh - (Comment out Default Group Configurations):

./configure-openssl-cnf.sh 0

configure-openssl-cnf.sh - (Uncomment out Default Group Configurations):

./configure-openssl-cnf.sh 1