Installation Instructions - crt26/PQC-LEO GitHub Wiki

The standard setup process uses the last tested commits of the project's dependency libraries to ensure compatibility with this project's automation tools. The setup script performs system detection, installs all required components, and supports multiple installation modes depending on the desired testing configuration.

While the default configuration prioritises stability, users may optionally configure the setup to pull newer versions of the OQS libraries. This can be useful for testing upstream changes or recent algorithm updates. For more advanced configuration options, see the Optional Setup Flags section.

The following instructions describe the standard setup process, which is the default and recommended option.

Clone the current stable version:

git clone https://github.com/crt26/PQC-LEO.git

Move into the cloned repository directory and execute the setup script:

cd PQC-LEO
./setup.sh

You may need to change the permissions of the setup script; if that is the case, this can be done using the following commands:

chmod +x ./setup.sh

When executing the setup script, you will be prompted to select one of the following installation options:

1. Computational Performance Testing Only - Installs components for standalone performance benchmarking (CPU and memory).

2. Full Install - Installs all components for computational performance, TLS performance, and TLS handshake transmission cost testing.

3. TLS Testing Libraries Only - Installs the components required for TLS performance and TLS handshake transmission cost testing. (Requires Option 1 has already been completed).

4. Energy Collector Machine Setup - Installs only the energy collector tools and its dependencies for use on the energy usage collection device. This device is used to poll the energy meter and collect energy usage data during testing and is separate from the main testing machines.

Installation options 1–3 also require the PQC-LEO OpenSSL 4.0.3 build in the repository’s lib directory to support the OQS libraries. This is built automatically during setup and managed separately from the system OpenSSL installation. The OpenSSL installation used for the energy measurement tools is selected independently.

For installation options 1–3, the setup script prompts you to choose whether to install energy measurement tools; option 4 always installs the collector tools. The energy tools can use either a compatible system OpenSSL installation or the PQC-LEO build. The system OpenSSL option requires libssl-dev version 3.3.0 or newer, which is installed and validated during setup if it is not already present. See OpenSSL Compatibility for Energy Tools for further details and manual runtime configuration requirements.

Some energy-testing features, such as UART communication for control signalling, require additional configuration after setup. Refer to the relevant internal and external documentation for details.

If the TLS testing libraries are installed (Options 2 or 3), you will be prompted with the following additional setup options:

• Enable all disabled OQS-Provider algorithms supported by PQC-LEO – Enables OQS-Provider algorithms supported by PQC-LEO that are disabled by default. This ensures the full range of supported algorithms can be tested in the TLS performance benchmarking †.

• Enable KEM encoders – Adds support for OpenSSL’s optional KEM encoder functionality. This option is automatically enabled if energy measurement tools are configured to be installed as the KEM encoders are required for TLS operations energy usage testing.

Once all the relevant options have been selected, the setup script will download, configure and build each library. It will also tailor the builds for your system architecture by applying appropriate build flags.

If issues occur during installation that prevent the project from functioning correctly, it is recommended that a clean installation is performed. This can be done by running the cleaner.sh utility script and selecting Uninstall Libraries Only, followed by Uninstall all Libraries. Existing benchmarking results will be preserved when using these options. Once this has completed, rerun the setup.sh script and select the desired installation option. Please note that Option 3 requires an existing computational installation; for a fresh installation with TLS support, select Option 2.

† Enabling all disabled OQS-Provider algorithms may cause the OpenSSL speed tool to fail due to internal limits in its source code. The setup script attempts to patch this automatically, but you can configure this process manually. Please refer to the Advanced Setup Configuration Guide for further details.

A hidden file named .pqc_leo_dir_marker.tmp is created in the project's root directory during setup. Automation scripts use this marker to reliably identify the root path, which is essential for their correct operation.

When running the setup script, it is vital that this is done from the root of the repository so that this file is placed correctly.

Do not delete or rename this file while the project is in a configured state. It will be automatically removed when uninstalling all libraries using the cleaner.sh utility script. If the file is removed manually, it can be regenerated by rerunning the setup script or creating it manually.

To verify the file exists, use:

ls -la

To manually recreate the file, run the following command from the project's root directory:

touch .pqc_leo_dir_marker.tmp

For advanced setup options, including:

• Pulling the latest version of the OQS libraries rather than the default tested versions
• Custom OpenSSL speed.c limits
• Enabling Liboqs memory optimised implementations

Please refer to the Advanced Setup Configuration Guide page.