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

8.1. ETSI Protocol¶

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

The ETSI standard requires KMEs to use a 2-way TLS communication with SAEs. If you wish to access these KMEs for Product Trial, please contact us for the necessary client key and certificates.

8.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 8.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 8.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"
}

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

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