Project Utility Scripts - crt26/PQC-LEO 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
• configure_openssl_cnf.sh
• get_algorithms.py
• oid_handler.sh
• serial_port_selector.py
• source_code_modifier.sh
• system_state_configurer.sh

This script automates the full environment setup required to run the PQC benchmarking tools. It provides setup options for computational performance, TLS performance, TLS handshake transmission cost, and energy usage testing, and handles all necessary system configuration and dependency installation. Transmission cost testing uses the components installed by the TLS setup modes.

Key tasks performed include:

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

• Downloading and compiling OpenSSL 4.0.3 when required for the selected setup

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

• Building and configuring the energy usage evaluation tools (energy_collector and comp_energy_tester) when energy testing is enabled

• 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 utility script manages the modification of the OpenSSL 4.0.3 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 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, energy usage, TLS handshake transmission cost, and parsing tools to determine which algorithms to run or parse.

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 lists of the supported classical TLS signing algorithms, key-exchange groups, and ciphersuites for supported TLS performance and energy usage testing.

• 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:

Option 4 is used by the source_code_modifier.sh script to obtain the algorithm count when modifying OpenSSL’s speed.c during setup. Do not run it manually on a configured installation: the utility script currently clears existing algorithm lists during initialisation, even in this counting mode.

When regenerating lists manually, choose option 1 for computational-only lists, option 2 for both computational and TLS lists, or option 3 for TLS lists only. The script clears all existing files in test_data/alg_lists during initialisation, before validating the selected option and checking its dependencies. This also happens for option 4 and for an invalid single argument; --help exits before initialisation. Back up any customised lists and choose the option that covers every testing category needed in the environment.

Example usage for a computational-only environment:

cd scripts/utility_scripts
python3 get_algorithms.py 1

This utility script manages custom OID environment variable mappings used only during TLS operations energy usage testing. It is an internal helper invoked by the TLS operations energy test script and is not intended to be called manually. It supports setting or clearing OID mappings so OpenSSL and OQS-Provider can reference private enterprise OIDs during TLS operations energy usage testing. This is required due to various algorithms included within OQS-Provider not having standardised OID values, which is required for the algorithm to be recognised as valid when being used in manual OpenSSL operations.

The utility script must be called with one of the following arguments in order to determine which OID handling operation must be performed:

The algorithms that are included within this script are based on the algorithms listed by OQS-Provider in their ALGORITHMS.md file (OQS-Provider version 0.12.0). Currently, the script is hard-coded to include the algorithms mentioned in that file. This will be updated in the future to be more dynamic. The version of the ALGORITHMS.md file used to dictate the algorithms included in this script can be found here.

This Python utility script is used for handling serial port selection in the energy testing bash scripts when serial control signalling has been selected by the user. The script uses the pyserial package to detect available serial ports on the system, outputs a numbered list of available ports to the user, validates the selected option value, and returns the selected serial device path to the calling Bash script. This utility script is intended to be called by the automated testing scripts (for example, tls_operations_energy_test.sh and pqc_tls_performance_test.sh) and is not intended to be run manually. To support properly grabbing the selected serial port path from the utility script in bash, interactive menu output and warning messages are written to standard error, while only the selected serial device path is written to standard output.

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. Depending on the setup configuration, the setup.sh script automatically invokes it to adjust hardcoded OpenSSL constants and enable algorithms that are disabled by default in OQS-Provider. 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 OQS-Provider algorithms that are disabled by default.
• 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. If using the modify_openssl_src tool, additional arguments must be provided to specify specific modification values. If using the oqs_enable_algs tool, no additional arguments are required, as it automatically enables all disabled algorithms in OQS-Provider.

Accepted Arguments for modify_openssl_src:

Example Usage includes:

source_code_modifier.sh "oqs_enable_algs"

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

This utility script is used for configuring and restoring the system's performance state during energy usage evaluation testing. This helps improve measurement consistency, although background processes and thermal throttling can still affect results. It supports configuring the CPU governor setting and returning a target CPU core to be used by testing binaries*. It accepts one command line argument to set the default state, set custom state values, or restore the original configuration. Based on the detected command line argument, the script will either set the system state to a default configuration optimised for testing, or it will prompt the user to input custom values for the system state configuration. When using default settings, the CPU governor is set to performance and the second CPU core is selected when available (otherwise core 0).

Required Command Line Arguments (one required):

• NOTE: Fan control is currently not supported in this version of PQC-LEO, but future development aims to include this functionality. In the meantime, it is highly recommended to set a manual fan speed to ensure consistent system thermal and power draw conditions during energy usage testing.