REST APIs
================================================================================

This section describes Application Programming Interfaces (APIs), that external
Security Application Entities (SAEs) can access using ``HTTPS`` requests over
the internet or within organisational private networks, to request for quantum
secret keys.

QKDLite can function as a Key Management Entity (KME) for SAEs to request for
quantum secret keys via Quantum Key Distribution (QKD) protocols or via QKDLite
nodes equipped with Quantum Random Number Generators (QRNGs).

Each supported key request protocol is described in the sections below.

ETSI Protocol
--------------------------------------------------------------------------------

QKDLite supports using European Telecommunications Standards Institute's (ETSI)
QKD 014 protocol to obtain quantum secret keys, which were generated from
quantum key distribution (QKD) protocols.

The ETSI standard requires KMEs to use a 2-way TLS communication with SAEs. We
set up two QKDLite ETSI KMEs in the internet to facilitating integration testing
with others. If you need to access these KMEs, please contact us for the
necessary client key and certificates.

Our public KMEs can be found at

#. KME A (SAE ID = SAE_A): ``https://13.76.73.12:8443``
#. KME B (SAE ID = SAE_B): ``https://52.230.80.113:8443``

Get status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To get status information on QKD quantum keys available for requesting from a
KME, connect to the KME with the ``Get status`` method listed below.

.. code-block:: bash
   :caption: ``Get status`` method

   https://<kme_ip>:<kme_port>/api/v1/keys/<remote_SAE_id>/status

An example of the above would be
``https://13.76.73.12:8443/api/v1/keys/SAE_B/status``.

.. tip::

   These QKD quantum keys are generated by the KMEs with SAE identifiers
   <local_SAE_id> and <remote_SAE_id>. The key creation process is initiated by
   <local_SAE_id>.

A successful request will receive the following ``JSON`` response.

.. code-block:: json
   :caption: Example JSON response for ``Get status`` method

   {
      "max_SAE_ID_count": 0,
      "max_key_size": 256,
      "max_key_count": 1,
      "key_size": 256,
      "min_key_size": 256,
      "stored_key_count": 1,
      "slave_SAE_ID": "SAE_B",
      "master_SAE_ID": "SAE_A",
      "max_key_per_request": 1,
      "target_KME_ID": "hidden",
      "source_KME_ID": "hsm:0"
   }

Get key
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To obtain a QKD quantum key from the KME, connect to the KME with the
``Get key`` method listed below.

.. code-block:: bash
   :caption: ``Get key`` method

   https://<kme_ip>:<kme_port>/api/v1/keys/<remote_SAE_id>/enc_keys

An example of the above would be
``https://13.76.73.12:8443/api/v1/keys/SAE_B/enc_keys``

A successful request will receive the following ``JSON`` response.

.. code-block:: json
   :caption: Example JSON response for ``Get key`` method.

   {
      "keys": [
         {
            "key": "kg8GWnwhOmLVQfg574bBC5u4MtQ1losXPcX2Ja68ryk=",
            "key_ID": "52414e44-ccbd-8949-486d-29ec2a2d17fc"
         }
      ]
   }

.. note::

   This method only returns 1 key of size 256 bits.
   No other option is provided.

Get key with key ID
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To obtain a the same QKD quantum key from the remote KME, connect to the remote
KME with the ``Get key with key ID`` method. Note that ``<key_ID>`` is obtained
from the ``Get key`` method response in the earlier section.

.. code-block:: bash
   :caption: ``Get key with key ID`` method

   https://<kme_ip>:<kme_port>/api/v1/keys/<remote_SAE_id>/dec_keys?key_ID=<key_ID>

An example of the above would be
``https://52.230.80.113:8443/api/v1/keys/SAE_A/dec_keys?key_ID=52414e44-ccbd-8949-486d-29ec2a2d17fc``

A successful request will receive the following ``JSON`` response.

.. code-block:: json
   :caption: Example JSON response for ``Get key with key ID`` method.

   {
      "keys": [
         {
            "key": "kg8GWnwhOmLVQfg574bBC5u4MtQ1losXPcX2Ja68ryk=",
            "key_ID": "52414e44-ccbd-8949-486d-29ec2a2d17fc"
         }
      ]
   }

.. note::

   This method only returns 1 key of size 256 bits.
   No other option is provided.