9. 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.

9.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.

9.1.1. Broken link to custom quantum-safe libcurl library¶

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 “failed setting curves list” (shown below), this means the link to the custom quantum-safe libcurl library has been broken.

+--------------------------+
| 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...
* Connected to 1.2.3.4 (1.2.3.4) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* failed setting curves list: 'mlkem768:x25519'
* Closing connection 0
error curl_easy_perform Couldn't use specified SSL cipher
Error [3] in QKD connectivity
./QKD2HSM executed with rc = 1

Solution

To fix the link to the custom quantum-safe libcurl library, execute the commands

cd /lib/x86_64-linux-gnu
sudo ln -fs /opt/oqssa/lib/libcurl.so.4.8.0 libcurl.so.4

Verification

Perform a create key operation again without the debug flag

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

Your create key operation should execute successfully now.

9.1.2. pQCee pqTLS service is down¶

Note

This solution applies if you deploy the pQCee pqTLS in front of your QKD Entity 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 pqTLS 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

Depending on the pqTLS operating mode you are using, you will need to restart the pqTLS service or restart the Docker container for pqTLS.