Installation
================================================================================
In this section, you will find step-by-step instructions on how to set up the
QKDLite solution for your infrastructure. The guide will be ordered as follows:
#. `Compile QKDLite Transport Key Utility and QKDLite Utility`_ describes the
compilation process required for the **QKDLite Transport Key Utility** and
**QKDLite Utility** for Ubuntu versions other than Ubuntu 22.04 LTS (Jammy
Jellyfish).
#. `Set Up QKDLite Node`_ describes the configuration process to set up QKDLite
solution on Ubuntu LTS 22.04 VM.
#. `Configure pQCee Quantum-safe TLS Proxy`_ describes the process of
configuring the proxy to forward incoming quantum-safe TLS traffic to the
target service(s).
Compile QKDLite Transport Key Utility and QKDLite Utility
--------------------------------------------------------------------------------
If the VM operating system (OS) you are targeting is Ubuntu 22.04 LTS, you can
get the QKDLite release package from pQCee and skip this step. Otherwise, please
get the QKDLite repository from pQCee and follow the steps below to compile the
QKDLite Utility binary for other Debian-based Linux OS.
Prepare the Build Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The build environment to compile the QKDLite Utility has the following
pre-requisites:
#. gcc
#. libcurl4-openssl-dev
#. make
There are two ways to prepare the build environment:
#. The easier method is to load the QKDLite repository in the provided
DevContainer. The pre-requisites are automatically installed for you.
#. If using the QKDLite repository as is, please ensure you have installed the
above pre-requisites before proceeding to build the utility. Otherwise, the
build process will exit with dependency errors. You can install the
pre-requisites as follows on your target Debian-based Linux OS.
.. code-block:: bash
sudo apt update && sudo apt upgrade -y
sudo apt install gcc libcurl4-openssl-dev make -y
Build the QKDLite Transport Key Utility and QKDLite Utility
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Once you have readied the build environment, follow the steps below to build
``Insert2HSM`` and ``QKD2HSM`` binaries:
#. Build the QKDLite_API library, followed by the ``Insert2HSM`` and ``QKD2HSM``
binaries.
.. code-block:: bash
cd QKDLite_API/
make libQKDLite_API.so
cd ../hsm/
make Insert2HSM
make QKD2HSM
.. caution::
If you try to execute ``QKD2HSM`` at this juncture, you should see an
error complaining about unable to load shared library files. If you wish
to rectify this path issue, you will need to copy the
``libQKDLite_API.so`` and ``libQKDLite_HSM.so`` files to ``/usr/lib``.
#. Once you fixed the above issues, executing ``QKD2HSM`` will present you with
the program banner containing the text "QKD2HSM utility by pQCee" as shown
below:
.. code-block:: text
+--------------------------+
| QKD2HSM utility by pQCee |
| |
| Copyright (c) pQCee |
| info@pqcee.com |
+--------------------------+
Set Up QKDLite Node
--------------------------------------------------------------------------------
Once you have finished building the binaries for QKDLite Utility, we will
proceed to set up the core QKDLite software components and dependencies on the
target Linux platform.
Install QKDLite node
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Install QKDLite node in the VM.
#. Create a directory ``mkdir ~/QKDLite`` and copy both QKDLite components into
this directory.
#. Copy QKDLite Utility binaries (listed below) into ``~/QKDLite``.
- ``/hsm/Insert2HSM``
- ``/hsm/QKD2HSM``
- ``/hsm/libQKDLite_HSM.so``
- ``/QKDLite_API/libQKDLite_API.so``
#. Copy QKDLite Scripts (listed below) into ``/QKDLite``.
- ``/qkdlite_scripts/*.sh``
#. Set up library dependencies for QKDLite Utility.
.. code-block:: shell
cd /usr/lib
sudo ln -fs ~/QKDLite/libQKDLite_API.so .
sudo ln -fs ~/QKDlite/libQKDLite_HSM.so .
Install Quantum-safe SSH and TLS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Install our custom OQS SSH for QKDLite node to securely connect to another
QKDLite node.
#. Place custom OQS builds of openSSL, curl and openSSH in ``/opt/oqssa``.
#. Configure QKDLite Utility to use the custom OQS ``libcurl``.
.. code-block:: shell
cd /lib/x86_64-linux-gnu
sudo ln -fs /opt/oqssa/lib/libcurl.so.4.8.0 libcurl.so.4
#. Place SSH key files in ``~/.ssh`` and make them readonly to user with ``chmod
400``.
Configure QKDLite Scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#. Configure the environment variables for the QKDLite Scripts.
#. Create a password file ``hsm_passwd.txt`` outside of ``/QKDLite`` and save
the password inside this text file. The script ``qkdlite_setup.sh`` use
``../hsm_passwd.txt`` file to set up the environment variable to store the
HSM password.
#. Review the contents of the ``qkdlite_setup.sh`` script file to see if any
changes are need from the default settings. Otherwise, stick to the
default settings.
#. Once all the above is done, you are ready to use the QKDLite Scripts to
execute key management tasks.
.. note::
You can use either **QKDLite Scripts** or ``QKD2HSM`` **QKDLite Utility** to
perform key management tasks using both HSM and KME communication.
Configure pQCee Quantum-safe TLS Proxy
--------------------------------------------------------------------------------
If you require a quantum-safe connection between the QKDLite node to a classical
TLS KME in your infrastructure, you can follow the instructions below to
configure and deploy our quantum-safe TLS proxy.
The instructions assume deploying the quantum-safe TLS proxy as a VM on a cloud
infrastructure.
#. Setup a VM to be used as a TLS proxy.
#. Create an **Ubuntu 22.04 LTS** VM on your cloud infrastructure with SSH
access from the internet.
#. SSH into the VM and patch to the latest ``apt`` updates.
.. code-block:: shell
sudo apt update
sudo apt upgrade
#. Install `Docker Engine on Ubuntu
`_.
#. Install pQCee quantum-safe TLS proxy.
#. Download our quantum-safe TLS proxy ``Dockerfile`` and
``nginx-conf/nginx.conf`` files into a directory in the VM.
#. In the ``Dockerfile``, set ``ARG KME_IP`` to the IP address of the KME.
During the Docker image build process, the placeholder ``KME_IP`` in
``nginx-conf/nginx.conf`` will be replaced with the KME's IP address.
#. In the root of the directory containing our quantum-safe TLS proxy source
files, build the docker image.
.. code-block:: shell
sudo docker build -t oqs-nginx .
#. Once the docker image is built, execute the container to listen at port
443.
.. code-block:: shell
sudo docker run --detach --name oqs-nginx -p 443:443 oqs-nginx
#. Verify that pQCee quantum-safe TLS proxy accepts quantum-safe TLS connections
at port 443.
#. On you local development system, use the command below to connect to the
quantum-safe TLS proxy using the official FIPS ML-KEM-768 post-quantum
cipher.
.. code-block:: shell
docker run \
-it openquantumsafe/curl \
curl -k https:// --curves mlkem768
.. note::
```` refers to the internet-facing IP address
assigned to your VM on your cloud infrastructure.
#. A successful quantum-safe TLS connection returns a "Welcome to nginx"
homepage on your console.
#. Configure QKDLite node to send network connections via pQCee quantum-safe TLS
proxy to the QKD KME.
#. In the ``qkdlite_init.sh`` file, set ``KME_IP`` to the IP address of the
quantum-safe TLS proxy.
#. Perform a QKD key creation operation using ``create_key_keyid.sh``. A
successful key creation means that the QKDLite node is now connecting to
the quantum-safe TLS proxy using a quantum-safe TLS connection. Thus, the
QKDLite node now connects to the QKD KME via the pQCee quantum-safe TLS
proxy.