Installation ================================================================================ Installing QKDLite solution -------------------------------------------------------------------------------- In this section, we will guide you on how to set up a pair of virtual QKDLite nodes that can replicate keys from the main node to the remote node. You will need to get the installer package from pQCee to install QKDLite solution in your Virtual Machine (VM) or bare metal machine. We will use the following example settings on two VMs to guide you through the installation process. #. QKDLite Main Node - Operating System: x64 Ubuntu Server 22.04 LTS (Jammy Jellyfish) - Node Name: QKDLITE_SAE_A - Username: pqcee - SAE Name: SAE_A - Intranet IP: 192.168.1.10 - Public Internet IP: 1.2.3.4 #. QKDLite Remote Node - Operating System: x64 Ubuntu Server 22.04 LTS (Jammy Jellyfish) - Node Name: QKDLITE_SAE_B - Username: pqcee - SAE Name: SAE_B - Intranet IP: 192.168.1.20 - Public Internet IP: 4.3.2.1 Set Up the Virtual Machines ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Create two VM instances in your cloud infrastructure. #. Setup one VM for QKDLite Main Node. #. Setup a second VM for QKDLite Remote Node. #. Ensure that you can SSH into pqcee user account in each VM via its respective public internet IP address from your Internet administration machine. .. code-block:: bash :caption: console: Secure Shell login to QKDLITE_SAE_A ssh -i ~/.ssh/ pqcee@1.2.3.4 .. code-block:: bash :caption: console: Secure Shell login to QKDLITE_SAE_B ssh -i ~/.ssh/ pqcee@4.3.2.1 #. Update each VM to the latest patches and set the appropriate clock time zone. .. code-block:: bash :caption: console: Update Ubuntu OS sudo apt update sudo apt upgrade -y sudo timedatectl set-timezone Asia/Singapore .. note:: You may need to reboot the operating system at the end of this step. #. Copy the QKDLite installer package to the home root directory each VM. Please replace ```` below with your SSH private key filename. .. code-block:: bash :caption: console: Secure Copy QKDLite installer to VMs scp -i ~/.ssh/ pQCee_QKDLite_3.2.0_installer_Ubuntu_2204_LTS_x64.tar.gz pqcee@1.2.3.4:~ scp -i ~/.ssh/ pQCee_QKDLite_3.2.0_installer_Ubuntu_2204_LTS_x64.tar.gz pqcee@4.3.2.1:~ #. Extract the QKDLite installer package into a directory. The created directory will have the same name as the ``.tar.gz`` filename. .. code-block:: bash :caption: console: Extract QKDLite installer package tar -xzvf pQCee_QKDLite_3.2.0_installer_Ubuntu_2204_LTS_x64.tar.gz Install QKDLite in the VMs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Install QKDLite solution by executing the installer package. #. In each VM, execute the installer package and follow the instructions provided by the installer. .. code-block:: bash :caption: console cd ~/pQCee_QKDLite_3.2.0_installer_Ubuntu_2204_LTS_x64 ./install.sh #. The installer will request for the following information. #. **External public IP address**. If you assigned an external public IP address to the VM and the IP address is not detected by the installer, please type in the public IP address. Otherwise, press Enter to skip. .. code-block:: text :caption: console: QKDLite installer The following IP address(es) have been detected on this machine and they will be included in the ETSI server certificate generation: 127.0.0.1 192.168.1.10 If you require additional external public IP address for inclusion in the ETSI server certificate generation, please enter the IP address (or press Enter for none): 1.2.3.4 #. **Organisation name**. The organisation name is required to generate CA and server certificates for the ETSI server in the QKDLite node. Enter a string without spaces representative of your organisation. .. code-block:: text :caption: console: QKDLite installer Please enter organisation name: pQCee #. **Certificate expiry (in years)**. Specify the number of years before the generated CA and server certificates expires. Press Enter to use the default setting of 10 years. .. code-block:: text :caption: console: QKDLite installer Please enter certificate expiry timeline in year(s): [10] #. **SAE Name of main node and remote node**. The Security Application Entity (SAE) name is required for the proper labelling of quantum keys to be provided via the ETSI server. We can use "SAE_A" for QKDLITE_SAE_A and "SAE_B" for QKDLITE_SAE_B. If you are on QKDLITE_SAE_A, press Enter to use the defaults for "SAE_A" for main node and "SAE_B" for remote node. .. code-block:: text :caption: console: QKDLite installer Please enter SAE name for this node: [SAE_A] Please enter SAE name for remote node: [SAE_B] #. **SSH details of remote node**. The username and IP address of the remote node is required for the localhost node to connect to the remote node for key replication. Press Enter to use the same username as your localhost node, and enter the IP address of the remote node. .. code-block:: text :caption: console: QKDLite installer Please enter SSH username for remote node: [pqcee] Please enter IP address for remote node (e.g., 192.168.1.10): 192.168.1.20 #. **HSM SO Pin**. The Security Officer (SO) Pin is used to perform administration actions on the HSM. The installer installs SoftHSMv2 out of the box and the SO Pin allows you to create and delete HSM slots. Enter your SO Pin twice to confirm. .. code-block:: text :caption: console: QKDLite installer Please enter an SO Pin for the HSM: Please enter the SO Pin again: .. note:: Due to the sensitive nature of the secrets, characters typed for SO Pin, User Pin, and Transport Key Data will not be shown on screen. #. **HSM User Pin**. The HSM User Pin is used to add, delete and view keys stored inside the HSM slot. Enter your User Pin twice to confirm. .. code-block:: text :caption: console: QKDLite installer Please enter a User Pin for the HSM: Please enter the User Pin again: #. **Transport Key Data**. The Transport Key Data is your secret used to create a Transport Key in the HSM slot. The Transport Key Data must be the same for both the main node and the remote node, otherwise key replication from main node to remote node will fail. .. code-block:: text :caption: console: QKDLite installer Please enter Transport Key data: Please enter the Transport Key data again: #. Once you have entered the above information, the installer will proceed to install QKDLite. Connect QKDLite Main Node to Remote Node ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once QKDLite has been installed on both main node and remote node, we will need to grant the right permissions for the main node to connect to the remote node to perform key replication. #. In QKDLite main node, copy the text contents of the ``qkdlite-mldsa-key.pub`` ssh client public key displayed on the console. .. code-block:: bash :caption: console on QKDLite main node cd ~/.ssh cat qkdlite-mldsa-key.pub # copy contents of file printed on console output #. In QKDLite remote node, append the copied ssh client public key to the end of the ``authorized_keys`` file. .. code-block:: bash :caption: console on QKDLite remote node cd ~/.ssh vim authorized_keys # append copied contents to this file .. caution:: Ensure that you append the copied contents to a **new line** in the file. Otherwise, sshd is unable to authenticate against your newly-added public key in ``authorized_keys`` file. .. tip:: You can use ``nano`` to edit files if you are not familiar with ``vim``. #. Back to QKDLite main node, test that QKDLite main node can connect to the remote node. .. code-block:: bash :caption: console on QKDLite main node cd ~/QKDLite ./replicate_create_keys_qrng.py QKDLITE_SAE_B TestKey 1 ./replicate_delete_keys.py QKDLITE_SAE_B TestKey A successful connection will show a console output as follows: .. code-block:: text :caption: console output pqcee@QKDLITE_SAE_A:~/QKDLite$ ./replicate_create_keys_qrng.py QKDLITE_SAE_B TestKey 1 Creating QRNG key(s) locally on QKDLITE_SAE_A... TestKey,4545aca956bb1f9c808338d5fb4b7f56 Exporting QRNG key(s) locally on QKDLITE_SAE_A... TestKey, 4545aca956bb1f9c808338d5fb4b7f56, 60CA71133D81E38DBA5872105422EB247B6EF4F9CB3F31153BA151188130C10BD9062C44122BB789 Importing key(s) on remote QKDLite node QKDLITE_SAE_B... TestKey,4545aca956bb1f9c808338d5fb4b7f56 pqcee@QKDLITE_SAE_A:~/QKDLite$ ./replicate_delete_keys.py QKDLITE_SAE_B TestKey Deleting keys on remote QKDLite node QKDLITE_SAE_B... TestKey,4545aca956bb1f9c808338d5fb4b7f56 Deleting keys locally on QKDLITE_SAE_A... TestKey,4545aca956bb1f9c808338d5fb4b7f56 .. note:: The above instructions establish a one-way connection from QKDLITE_SAE_A to QKDLITE_SAE_B. If you require another one-way connection in the reverse direction from QKDLITE_SAE_B to QKDLITE_SAE_A, you will need to repeat the above instructions with QKDLITE_SAE_B as the main node. Configure pQCee pqTLS -------------------------------------------------------------------------------- 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 pqTLS. The instructions assume deploying pqTLS as a VM on a cloud infrastructure. #. Setup a VM to be used as pqTLS. #. 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 pqTLS. #. Download our pqTLS ``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 pqTLS 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 pqTLS accepts quantum-safe TLS connections at port 443. #. On you local development system, use the command below to connect to pqTLS 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 pqTLS to the QKD KME. #. In the ``qkdlite_init.sh`` file, set ``KME_IP`` to the IP address of pqTLS. #. Perform a QKD key creation operation using ``create_key_keyid.sh``. A successful key creation means that the QKDLite node is now connecting to pqTLS using a quantum-safe TLS connection. Thus, the QKDLite node now connects to the QKD KME via the pQCee pqTLS.