Automated TLS Performance Scripts - crt26/PQC-LEO GitHub Wiki

The PQC TLS performance testing suite relies on several scripts to carry out TLS benchmarking, including:

• pqc_tls_performance_test.sh
• tls_handshake_test_server.sh (Internal Script)
• tls_handshake_test_client.sh (Internal Script)
• tls_speed_test.sh (Internal Script)
• tls_generate_keys.sh

Testing scripts are stored in the scripts/test_scripts directory, whilst internal scripts are stored in the scripts/test_scripts/internal_scripts directory. Internal scripts are intended to be called by the main testing scripts and do not support being called in isolation.

This is the main controller script for executing the full TLS performance benchmarking suite. It performs TLS handshake testing for PQC, Hybrid-PQC, and classical configurations, together with cryptographic speed testing for PQC, Hybrid-PQC, and classical algorithms supported by OpenSSL 4.0.3 and the OQS-Provider. The script coordinates all required test operations by invoking subordinate scripts (tls_handshake_test_server.sh, tls_handshake_test_client.sh, and tls_speed_test.sh) and ensures that results are stored correctly under the appropriate machine directory based on the assigned Machine ID. Designed to run on both client and server machines, the script prompts the user for necessary parameters such as machine role, IP addresses, test duration, and number of runs. When run on the client, it configures both the handshake and speed benchmarking parameters accordingly.

It is important to note that when conducting testing, the pqc_tls_performance_test.sh script will prompt the user for parameters regarding the handling of storing and managing test results if the machine or current shell has been designated as the client (depending on whether single machine or separate machine testing is being performed).

Since version 0.6.0 of PQC-LEO, the controller script supports energy usage evaluation during TLS handshake benchmarking. This is currently supported on the client side of the testing suite and can be enabled by including the relevant command-line argument listed below when calling the controller script. By default, TLS handshake performance results are not stored when energy usage testing is enabled. During client configuration, however, the user can choose to store these results alongside the energy usage results. If storage is enabled, the performance results are written to the client machine and parsed without expecting TLS speed results, as TLS speed testing is skipped in this mode.

The script accepts the passing of various command-line arguments when called, which allows the user to configure components of the automated testing functionality. Please refer to the Advanced TLS Testing Customisation page for further information on their usage.

Accepted Script Arguments:

Flag	Description
--server-control-port=<PORT>	Set the server control port (1024-65535)
--client-control-port=<PORT>	Set the client control port (1024-65535)
--s-server-port=<PORT>	Set the OpenSSL S_Server port (1024-65535)
--control-sleep-time=<TIME>	Set the control sleep time in seconds (integer or float)
--disable-control-sleep	Disable the control signal sleep time
--disable-result-parsing	Disable the automatic result parsing for the test suite
--enable-energy-testing	Enable energy testing, ensure the power measurement device is connected and configured correctly
--use-custom-eng-control-ports	Enable the use of custom network control ports for energy testing control signalling (requires --enable-energy-testing to be enabled)
--use-custom-sys-state	If performing energy testing, use custom system state values for the test instead of the default values.
--energy-baseline-duration=<TIME>	Set the energy baseline measurement duration in positive whole seconds (default: 60 seconds). Requires --enable-energy-testing to be enabled.
--help	Display the help message

This script handles the server-side operations for the automated TLS handshake performance testing. It tests PQC and Hybrid-PQC digital signature/KEM pairings, as well as every configured classical digital signature, key-exchange-group, and ciphersuite combination. The script includes error handling and coordinates with the client to retry failed tests using control signalling. This script is intended to be called only by the pqc_tls_performance_test.sh script and cannot be run manually.

This script handles the client-side operations for the automated TLS handshake performance testing. It tests PQC and Hybrid-PQC digital signature/KEM pairings, as well as every configured classical digital signature, key-exchange-group, and ciphersuite combination. The script includes error handling and coordinates with the server to retry failed tests using control signalling. This script is intended to be called only by the pqc_tls_performance_test.sh script and cannot be run manually.

When energy usage testing is enabled, the client script will gather a baseline measurement before beginning the handshake tests. The duration is passed from the controller script through the ENERGY_BASELINE_DURATION environment variable. If this variable is unset or empty, the script will use the default duration of 60 seconds.

This script performs TLS cryptographic operation benchmarking with OpenSSL's speed command. It tests PQC and Hybrid-PQC digital signature and KEM operations implemented natively or through the OQS-Provider, together with a set of classical signature and key-exchange operations. Raw results are separated into pqc, hybrid, and classic speed directories. This script is intended to be called only by the pqc_tls_performance_test.sh script and cannot be run manually. It is only called if the machine or current shell has been designated as the client (depending on whether single-machine or separate-machine testing is performed).

This script generates all certificates and private keys needed for TLS handshake performance and transmission cost testing. It creates a certificate authority (CA), server credentials, and client credentials for each PQC, Hybrid-PQC, and classical digital signature algorithm used in the tests. The client credentials enable mutual authentication during transmission cost testing. For performance tests conducted over a physical or virtual network, the generated key material must be copied to the client machine so both systems can access the required credentials.

This script must be called before conducting automated TLS handshake performance or transmission cost testing.