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

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

  1. KME A (SAE ID = SAE_A): https://13.76.73.12:8443

  2. KME B (SAE ID = SAE_B): https://52.230.80.113:8443

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

Listing 9.1  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.

Listing 9.2  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"
}

9.1.2. Get key

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

Listing 9.3  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.

Listing 9.4  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.

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

Listing 9.5  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.

Listing 9.6  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.