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.

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

.. code-block:: text

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

Broken link to custom quantum-safe libcurl library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Diagnosis**

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

.. code-block:: bash

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

.. code-block:: text

   +--------------------------+
   | 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

.. code:: bash

   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

.. code-block:: bash

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

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

.. code-block:: bash

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

.. code-block:: text

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