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 are 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
• source_code_modifier.sh

This script automates the full environment setup required to run the PQC benchmarking tools. It provides setup options for the different types of automated testing supported (computational, TLS, or both), and handles all necessary system configuration and dependency installation.

Key tasks performed include:

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

• Downloading and compiling OpenSSL 3.5.0

• Cloning and building the last-tested or latest 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:

For further information on the main setup script's usage, please refer to the main Installation Instructions page.

This utility script is used for cleaning up files generated during the compiling and benchmarking processes. It provides options for uninstalling libraries (which includes deleting generated __pycache__ directories), clearing old benchmarking results, and removing generated TLS keys. Users can choose to perform individual cleanup actions or both, based on their needs.

This Python utility script generates lists of supported cryptographic algorithms based on the currently installed versions of the Liboqs, OpenSSL (classic + PQC), 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 and parse for the computational and TLS performance testing.

Primarily intended to be invoked by the setup.sh script, this utility accepts an argument that specifies 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 PQC KEM and digital signature algorithms from the Liboqs library using its built-in test binaries.

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

• 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 and source_code_modifier.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 source_code_modifier.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 manages the modification of the OpenSSL 3.5.0 openssl.cnf configuration file to support different stages of the PQC testing pipeline. It adjusts cryptographic provider settings and default group directives as required for:

• Initial setup

• Server certificate and private-key generation used in the TLS handshake testing

• TLS handshake performance benchmarking

These adjustments ensure compatibility with both OpenSSL's native PQC support and the OQS-Provider, depending on the testing context.

Important: It is strongly recommended that this script be used only as part of the automated testing framework. Manual use should be limited to recovery or debugging, as improper configuration may result in broken provider loading or handshake failures.

When called, the utility script accepts the following arguments:

This internal utility script automates source code modifications for OpenSSL and OQS-Provider during the setup process. It is not intended to be run manually from the terminal. The setup.sh script automatically invokes it to adjust hardcoded OpenSSL constants, enable HQC algorithms, and re-enable signature algorithms disabled by default in OQS-Provider, depending on the setup configuration. It is located in the scripts/utility_scripts/ directory.

It provides the following internal modification tools, each of which accepts its own set of arguments:

• oqs_enable_algs - Used for enabling HQC KEM algorithms, enabling signature algorithms disabled by default, or both.
• modify_openssl_src - Used to modify the OpenSSL speed.c source code to increase hardcoded values. Only called if disabled signature algorithms are re-enabled in OQS-Provider.

When calling the utility script, the first argument must always be the modification tool to use. Subsequent arguments can be in any order, but must include all of the accepted arguments listed below for each tool.

Accepted Arguments for oqs_enable_algs:

Accepted Arguments for modify_openssl_src:

Example Usage includes:

source_code_modifier.sh "oqs_enable_algs" "--enable-hqc-algs=1" "--enable-disabled-algs=1"

source_code_modifier.sh "modify_openssl_src" "--user-defined-flag=1" "--user-defined-speed-value=500"