Automated Energy Usage Testing Scripts - crt26/PQC-LEO GitHub Wiki

These scripts provide automated mechanisms for integrating energy usage evaluations into the existing PQC performance suites available within PQC-LEO. These bash scripts utilise the comp_energy_tester and energy_collector tools included within the framework to provide energy usage metrics for PQC computational and TLS performance. These scripts provide an interface for configuring and running these tools. For further information on the energy evaluation tools used by these scripts, please refer to the Project Tools page.

The following dedicated scripts handle this functionality:

• energy_metric_collector.sh
• pqc_performance_energy_test.sh
• tls_operations_energy_test.sh

Additionally, functionality is included within the pqc_tls_performance_test.sh and tls_handshake_test_client.sh scripts to provide automated TLS handshake energy usage evaluations. This section will describe the dedicated automation scripts.

This controller script provides automation for the energy metric collector device using the collector binary included within the energy_collector tool. The script provides an interactive configuration interface for collection parameters (test type, machine ID, test runs), manages result directories and pre-existing result handling, and invokes the energy collector binary. It supports PQC performance, TLS handshake, and TLS operations collection types. The script will also automatically call the parsing script to parse results into structured CSV files via the central parser once testing has completed. Whilst the collector binary can be used by itself, this script provides an easy solution for result collection, handling, and parsing compared to manual use of the binary.

The energy_collector tool must be present within the PQC-LEO testing environment when calling this script, so please ensure that the relevant tools have been built using the setup.sh script. If the setup process sets that the energy tools should use the PQC-LEO OpenSSL build, the script will automatically configure the LD_LIBRARY_PATH to include the PQC-LEO OpenSSL build used by the energy tools.

Accepted Script Arguments:

Flag	Description
--disable-result-parsing	Disable the automatic result parsing for the test suite.
--help	Display this help message.

This controller script provides automation for the PQC computational performance energy benchmarking. The script utilises the comp_energy_tester binary included within comp_energy_tester tool to perform PQC cryptographic operations using the Liboqs library whilst sending control signals to the collector machine, allowing energy usage metrics to be gathered for each individual KEM/sig algorithm's respective operations. The script will call the comp_energy_tester after configuring the environment and system performance state using the system_state_configurer.sh utility script. The script accepts command line flags to enable custom system state configuration and custom network control ports for energy collector communication, and restores system state upon completion or interruption.

If the setup process sets that the energy tools should use the PQC-LEO OpenSSL build, the script will automatically configure the LD_LIBRARY_PATH to include the PQC-LEO OpenSSL build used by the energy tools.

Accepted Script Arguments:

Flag	Description
--use-custom-sys-state	Used to indicate that custom system state values should be set for the test instead of the default values
--use-custom-eng-control-ports	Enable the use of custom network control ports for energy testing control signalling
--energy-baseline-duration=<TIME>	Set the energy baseline measurement duration in positive whole seconds (default: 60 seconds)
--help	Display the help message

This controller script provides automation for TLS operations energy usage benchmarking. It measures the energy usage of PQC, Hybrid-PQC, and classical cryptographic operations performed directly through OpenSSL commands. The script tests key generation, encapsulation, and decapsulation for supported PQC/Hybrid-PQC KEMs; key generation, signing, and verification for PQC/Hybrid-PQC and classical signatures; and key generation and shared-secret derivation for classical key-exchange algorithms. It communicates with the collector device around each operation window, configures the system performance state through system_state_configurer.sh, and uses oid_handler.sh for PQC algorithms that require custom OID environment mappings. The script accepts command-line flags for custom system-state configuration and custom network control ports, and restores the system state on completion or interruption.

Accepted Script Arguments:

Flag	Description
--use-custom-sys-state	Used to indicate that custom system state values should be set for the test instead of the default values
--use-custom-net-control-ports	Enable the use of custom network control ports for energy collector communication.
--energy-baseline-duration=<TIME>	Set the energy baseline measurement duration in positive whole seconds (default: 60 seconds)
--help	Display the help message