10. Troubleshooting Guide

In this section, you will find step-by-step instructions on resolving common issues that may arise in while using QKDLite solution. The sub-sections are categorised according to components in the QKDLite solution that are the likely root cause of the issue.

10.1. Receive “Error [3] in QKD connectivity” error message when creating a new key

Symptom

During key creation operation, you received the following error from the QKDLite Utility in the console

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
Error [3] in QKD connectivity
./QKD2HSM executed with rc = 1

Likely Cause

This error means that QKDLite Utility was unable to connect to the IP address of the supplied QKD KME. There are several possible causes and we can use the -debug flag for QKD2HSM to gather more information to identify the root cause.

10.1.2. Quantum-safe TLS Proxy service is down

Note

This solution applies if you deploy the pQCee Quantum-safe TLS Proxy in front of your quantum KME.

Diagnosis

Perform a create key operation with the debug flag, similar to the example below

./QKD2HSM c \
   -slot 0 \
   -keyID "MyKey" \
   -password "abc123" \
   -kme "https://1.2.3.4" \
   -remote "SAE_B" \
   -debug

If you see a line mentioning about “Connection refused” (shown below), this means the container for the quantum-safe TLS proxy container may have stopped running.

+--------------------------+
| QKD2HSM utility by pQCee |
|                          |
|    Copyright (c) pQCee   |
|      info@pqcee.com      |
+--------------------------+
GET_KEY URL is [https://1.2.3.4/api/v1/keys/SAE_B/enc_keys?number=1&size=256]
*   Trying 1.2.3.4:443...
* connect to 1.2.3.4 port 443 from 192.168.1.100 port 44386 failed: Connection refused
* Failed to connect to 1.2.3.4 port 443 after 1 ms: Could not connect to server
* closing connection #0
error curl_easy_perform Could not connect to server
Error [3] in QKD connectivity
./QKD2HSM executed with rc = 1

Solution

You need to restart the Docker container for the quantum-safe TLS proxy. Follow the steps described below

  1. Login (via SSH) to the VM running the container for the quantum-safe TLS proxy.

  2. Check to make sure your Docker image is located in the root of your user home directory. For this example, we will use oqs-nginx-a as the filename of the image.

  3. Attempt to restart the Docker image.

    sudo docker run \
   --detach \
   --restart always \
   --name oqs-nginx-a \
   -p 443:443 oqs-nginx-a

  4. If you receive an error similar to the one below, please delete the container first and attempt restart of the Docker image again.

    docker: Error response from daemon: Conflict. The container name
"/oqs-nginx-a" is already in use by container
"some-hexadecimal-container-id". You have to remove (or rename) that
container to be able to reuse that name.

    1. Delete existing container.

      sudo docker container rm "some-hexadecimal-container-id"

    2. Restart the Docker image using the earlier docker run command.

Verification

  1. Check that the Quantum-safe TLS Proxy container is running.

    sudo docker ps -a

  2. Get the <proxy IP address> of the VM hosting the Docker image for the quantum-safe TLS proxy.

    hostname -i

  3. Verify that the quantum-safe TLS proxy is working as expected by executing the following command from your QKDLite node.

    curl -k https://<proxy IP address> --curves mlkem768

    A successful connection will return a HTML homepage reply to the console.

  4. Verify that your key creation operation now works as per normal.

    ./QKD2HSM c \
   -slot 0 \
   -keyID "MyKey" \
   -password "abc123" \
   -kme "https://<proxy IP address>" \
   -remote "SAE_B"