QKDLite KME - ETSI Protocol
================================================================================

Quantum secret keys can be generated from quantum key distribution (QKD)
protocols between a pair of QKD entities. The European Telecommunications
Standards Institute's (ETSI) QKD standards specifies a protocol for an external
Security Application Entity (SAE) to request for QKD quantum keys from a Key
Management Entity (KME).

QKDLite can be configured to expose a KME interface for an external SAE to
request for QKD quantum keys via the ETSI protocol. A usual setup involves two
SAEs that request for the same one-time-use quantum key from each of the two
QKD KMEs, which is hosted by two QKDLite nodes respectively.

This section is a guide to setting up and enabling the ETSI KME interface on the
QKDLite node.

Build ETSI Server from Source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The binaries we provide are built for 64-bit Ubuntu 22.04 LTS. You can skip this
section if your QKDLite node is using Ubuntu 22.04 LTS. Otherwise, you will need
to build the binary from source for a different Debian-based Linux distribution.

Steps to build from source:

#. In our QKDLite repository, change directory to ``QKDLite_API/etsi``.

   .. code-block:: bash
      :caption: console

       cd QKDLite_API/etsi

#. Install the library dependency `CROWCPP <https://crowcpp.org/master/>`__
   using our pre-defined shell script.

   .. code-block:: bash
      :caption: console

      ./setup_Crow_CPP.sh

#. Build ``QKDLite_ETSI`` binary.

   .. code-block:: bash
      :caption: console

      cd ..
      make libQKDLite_API.so
      cd ../hsm
      make libQKDLite_HSM.so
      cd ../QKDLite_API/etsi
      make

   .. note::

      ``QKDLite_ETSI`` binary depends on ``libQKDLite_API.so`` and
      ``libQKDLite_HSM.so`` libraries. If you have already built these libraries
      earlier, you can skip the command lines above to build them.

``QKDLite_ETSI`` Usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Once you have the ``QKDLite_ETSI`` binary, execute the binary on your deployed
QKDLite node to test if a desired configuration works in your environment.

The arguments of ``QKDLite_ETSI`` are

.. code-block:: bash
   :caption: QKDLite_ETSI arguments and parameters

   ./QKDLite_ETSI \
      -port <listening_port> \
      -kme <kme_url> \
      -password <hsm_password> \
      -local <local_SAE_id> \
      -remote <remote_SAE_id>

**Parameter Explanation**

==================== ========================================================
``listening_port``   HTTP port number to listen for incoming ETSI requests.

                     If argument ``-port`` is specified, ``QKDLite_ETSI``
                     listens to port number ``<listening_port>``. Otherwise,
                     ``QKDLite_ETSI`` defaults to listening on port number
                     ``18080``.

``kme_url``          URL of KME for ``QKDLite_ETSI`` to request for quantum
                     secret keys.

                     The URL is a string that can contain either an IP address
                     or hostname of a QKD entity KME (e.g.,
                     ``"https://1.2.3.4"``) or a specific string sequence
                     describing a HSM slot accessible by the QKDLite node (e.g.,
                     ``"hsm:0"`` for Slot 0 of local HSM).

``hsm_password``     Password to access HSM.

                     This argument ``-password`` is only required when argument
                     ``-kme`` is provided and parameter ``<kme_url>`` specifies
                     a HSM slot.

``local_SAE_id``     SAE identifier of local KME.

                     This parameter contains the SAE identifier of the local
                     KME. Creation of QKD quantum keys are invoked from the
                     local KME. E.g., ``"SAE_A"``.

``remote_SAE_id``    SAE identifier of remote KME.

                     This parameter contains the SAE identifier of the remote
                     KME that is paired with the local KME to produce the QKD
                     quantum keys. E.g., ``"SAE_B"``.
==================== ========================================================

**Example Scenario Setup**

We will configure two QKDLite nodes to expose KME ports that support ETSI
protocol for key consumption. Both nodes will use port 8000 and the pair of KMEs
will have names "SAE_A" and "SAE_B".

#. On QKDLite node A, we configure ``QKDLite_ETSI`` to listen to port 8000 and
   get QKD quantum keys from HSM slot 0 with KME SAE ID "SAE_A". We can call
   this KME A.

   .. code-block:: bash
      :caption: console

      ./QKDLite_ETSI \
         -port 8000 \
         -kme "hsm:0" \
         -password <hsm_password> \
         -local "SAE_A" \
         -remote "SAE_B"

#. On the other QKDLite node B, we configure ``QKDLite_ETSI`` to listen to the
   same port number, but get QKD quantum keys from HSM slot 1 with KME SAE ID
   "SAE_B". We can call this KME B.

   .. code-block:: bash
      :caption: console

      ./QKDLite_ETSI \
         -port 8000 \
         -kme "hsm:1" \
         -password <hsm_password> \
         -local "SAE_B" \
         -remote "SAE_A"

#. We will create a QKD quantum key on both HSM slots using
   QKDLite Script ``replicate_create_key.py`` on QKDLite node A. The QKD quantum
   key will be labelled with keyID "ETSI-2_SAE_B", stored in HSM slot 0 (at KME
   A) and subsequently replicated to HSM slot 1 (at KME B).

   .. code-block:: bash
      :caption: console

      ./replicate_create_key.py QKDLITE_B ETSI-2-SAE_B

#. We can request a QKD quantum key from KME A, followed by KME B using ``curl``
   with the REST API to Get key.

   .. code-block:: bash
      :caption: Get key from KME A

      curl http://<kme_a_ip>:8000/api/v1/keys/SAE_B/enc_keys

   We will receive a key_ID string in the REST API response. Note it down for
   the key request to KME B.

   .. code-block:: bash
      :caption: Get key with key ID from KME B

      curl http://<kme_b_ip>:8000/api/v1/keys/SAE_A/dec_keys?key_ID=<key_ID_string>

Enable ETSI Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this section, we will configure ``QKDLite_ETSI`` to run as a user service to
enable ``QKDLite_ETSI`` to start automatically in the background when QKDLite
node is rebooted.

Configuration steps:

#. Create a new file ``qkdlite-etsi-d.service`` in ``systemd`` directory with
   the following content.

   .. code-block:: text
      :caption: /etc/systemd/system/qkdlite-etsi-d.service

      [Unit]
      Description=QKDLite ETSI server
      After=network.target auditd.service

      [Service]
      Type=simple
      ExecStart=/home/pqcee/QKDLite/QKDLite_ETSI -port 8000 -kme "hsm:0" -password <hsm password> -local SAE_A -remote SAE_B
      Restart=on-failure
      User=pqcee

      [Install]
      WantedBy=multi-user.target
      Alias=qkdlite-etsi-d.service

   The above configures QKDLite_ETSI server to listen to port 8000, to retrieve
   keys from HSM slot 0 in the QKDLite node. The ETSI KME is associated with
   QKD Entity "SAE_A", which is paired with another ETSI KME associated with
   QKD Entity "SAE_B" for the QKD generation of quantum secret keys.

#. Replace one line in ``logind.conf`` in ``/etc/systemd`` directory with the
   following content.

   .. code-block:: text
      :caption: /etc/systemd/logind.conf

      [Login]
      ...
      UserStopDelaySec=infinity
      ...

   The above updates ``systemd`` login configuration not to terminate the user
   service after a user logout event.

#. Reboot the system to register the new login settings for ``systemd``.

   .. code-block:: bash
      :caption: console

      sudo reboot

#. Reload the ``systemd`` daemon to load the new service, enable service to
   autostart and start the service.

   .. code-block:: bash
      :caption: console

      sudo systemctl daemon-reload
      sudo systemctl enable --now qkdlite-etsi-d.service
      sudo systemctl start qkdlite-etsi-d.service

Verify ETSI Server status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Once the ETSI Server has been configured to start, you can verify it is indeed
running with the following steps.

#. Check the status of the service. Ensure that the service is active (running).

   .. code-block:: bash
      :caption: console

      systemctl status qkdlite-etsi-d.service

   .. tip::
      Any stdout output from the service is written to ``journald``. If you
      encounter issues with the service, you can check the logs to troubleshoot.

      .. code-block:: bash
         :caption: console

         journalctl -xeu qkdlite-etsi-d.service

#. Check that ``QKDLite_ETSI`` responds to a HTTP request.

   .. code-block:: bash
      :caption: console

      curl http://localhost:8000

   You should see the following HTTP response.

   .. code-block:: text
      :caption: console

      <html><body>pQCee QKDLite ETSI API service. Please contact info@pqcee.com
      for more details.<p>Test links:<ul><li><a href="/api/v1/keys/SAE_B/status"
      >Status</a></li><li><a href="/api/v1/keys/SAE_B/enc_keys">get key</a></li>
      <li><a href="/api/v1/keys/SAE_A/dec_keys?key_ID=">decrypt</a></li></body><
      /html>

#. (Optional) If required, you can stop the service.

   .. code-block:: bash
      :caption: console

      sudo systemctl stop qkdlite-etsi-d.service