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 GS QKD 014¶

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` method¶

Summary

Get status information of a target KME. Status information includes key size and SAE IDs of the paired KMEs.

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.

Request

GET /api/v1/keys/{remote_SAE_id}/status

Path Parameters

remote_SAE_id (string) - SAE ID of a remote KME paired with target KME.

Response Status Codes

200 OK
- Successful response.
503 Service Unavailable
- remote_SAE_id provided to KME does not match with KME’s setting.

Example

Use cURL to perform a HTTP GET to the Get status method at KME designated as SAE_A.

Listing 8.1 cURL command for Get status¶

curl --cacert CA.crt --cert client.crt --key client.key \
https://13.76.73.12:8443/api/v1/keys/SAE_B/status

A successful response will contain data similar to the following.

Listing 8.2 JSON response for Get status GET 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` method¶

Summary

Request for a QKD quantum key from the target KME.

Note

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

Request

GET /api/v1/keys/{remote_SAE_id}/enc_keys

Path Parameters

remote_SAE_id (string) - SAE ID of a remote KME paired with target KME.

Response Status Codes

200 OK
- Successful response.
503 Service Unavailable
- remote_SAE_id provided to KME does not match with KME’s setting.
- Internal error occurred when KME tried to provision key.

Example

Use cURL to perform a HTTP GET to the Get key method at KME designated as SAE_A.

Listing 8.3 cURL command for Get key¶

curl --cacert CA.crt --cert client.crt --key client.key \
https://13.76.73.12:8443/api/v1/keys/SAE_B/enc_keys

A successful response will contain data similar to the following.

Listing 8.4 JSON response for Get key GET method¶

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

8.1.3. `Get key with key ID` (GET) method¶

Summary

Request for the same QKD quantum key from the remote KME.

Note

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

Note

{key_ID} is obtained from the Get key method response in the earlier section.

Request

GET /api/v1/keys/{remote_SAE_id}/dec_keys?key_ID={key_ID}

Path Parameters

remote_SAE_id (string) - SAE ID of a remote KME paired with target KME.

Query Parameters

key_ID (string, UUID v4) - Unique identifier of a key.

Response Status Codes

200 OK
- Successful response.
400 Bad request
- Missing or invalid {key_ID} provided to KME.
503 Service Unavailable
- remote_SAE_id provided to KME does not match with KME’s setting.
- Internal error occurred when KME tried to provision key.

Example

Use cURL to perform a HTTP GET to the Get key with key ID method at KME designated as SAE_B.

Listing 8.5  cURL command for Get key with key ID¶

curl --cacert CA.crt --cert client.crt --key client.key \
https://52.230.80.113:8443/api/v1/keys/SAE_A/dec_keys?key_ID=52414e44-ccbd-8949-486d-29ec2a2d17fc

A successful response will contain data similar to the following.

Listing 8.6  JSON response for Get key with key ID GET method.¶

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

8.1.4. `Get key with key ID` (POST) method¶

Summary

Request for the same QKD quantum key from the remote KME.

Note

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

Note

{key_ID} is obtained from the Get key method response in the earlier section.

Request

POST /api/v1/keys/{remote_SAE_id}/dec_keys

Path Parameters

remote_SAE_id (string) - SAE ID of a remote KME paired with target KME.

Request Body

JSON object that contains one key_ID.
- key_ID (string, UUID v4) - Unique identifier of a key.

The JSON object will contain data in the following structure.

{
   "key_IDs":[
      {
         "key_ID":"{key_ID}"
      }
   ]
}

Response Status Codes

200 OK
- Successful response.
400 Bad request
- Request body contains JSON object that has invalid data structure, missing or invalid key_ID.
- Request body contains JSON object that has more than one key_ID.
503 Service Unavailable
- remote_SAE_id provided to KME does not match with KME’s setting.
- Internal error occurred when KME tried to provision key.

Example

Use cURL to perform a HTTP POST to the Get key with key ID method at KME designated as SAE_B.

Listing 8.7  cURL command for Get key with key ID¶

curl --cacert CA.crt --cert client_test.crt --key client_test.key \
-X POST https://52.230.80.113:8443/api/v1/keys/SAE_A/dec_keys \
-H "Content-Type: application/json" \
-d '{"key_IDs":[{"key_ID":"52414e44-ccbd-8949-486d-29ec2a2d17fc"}]}'

A successful response will contain data similar to the following.

Listing 8.8  JSON response for Get key with key ID POST method.¶

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

8.2. Cisco SKIP¶

QKDLite supports using Cisco Secure Key Integration Protocol (SKIP) to obtain quantum keys, which were generated from quantum key distribution (QKD) protocols.

2-way TLS is required between the SKIP Key Provider (KP) and the SAE. If you wish to access these KPs for Product Trial, please contact us for the necessary client key and certificates.

8.2.1. Get Capabilities¶

To get information on the capabilities of the SKIP KP, connect to the KP with the Get capabilities method listed below.

Listing 8.9 Get capabilities method¶

https://<kp_ip>:<kp_port>/capabilities

An example of the above would be https://13.76.73.12:9443/capabilities.

A successful request will receive the following JSON response.

Listing 8.10 Example JSON response for Get capabilities method¶

{
   "remoteSystemID": "SAE_B",
   "localSystemID": "SAE_A",
   "algorithm": "PRF",
   "key": true,
   "entropy": true
}

8.2.2. Get key¶

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

Listing 8.11 Get key method¶

https://<kp_ip>:<kp_port>/key?remoteSystemID=<remote_SAE_id>

An example of the above would be https://13.76.73.12:9443/key?remoteSystemID=SAE_B

A successful request will receive the following JSON response.

Listing 8.12 Example JSON response for Get key method¶

{
   "key": "F3CE78B9D2649850AB660DD93626E68356C4FB475AF448422E8748478508F78A",
   "keyID": "f6c79ea6480745928cc8b27ed1009e35"
}

Note

This method only returns 1 key of size 256 bits. It is equivalent to the Get key method with key size parameter below. No other option is provided.

Listing 8.13 Get key method with key size parameter¶

https://<kp_ip>:<kp_port>/key?remoteSystemID=<remote_SAE_id>&size=256

8.2.3. Get key with associated keyID¶

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

Listing 8.14 Get key method with associated keyID¶

https://<kp_ip>:<kp_port>/key/<keyID>?remoteSystemID=<remote_SAE_id>

An example of the above would be https://52.230.80.113:9443/key/f6c79ea6480745928cc8b27ed1009e35?remoteSystemID=SAE_A

A successful request will receive the following JSON response.

Listing 8.15 Example JSON response for Get key method with associated keyID¶

{
   "key": "F3CE78B9D2649850AB660DD93626E68356C4FB475AF448422E8748478508F78A",
   "keyID": "f6c79ea6480745928cc8b27ed1009e35"
}

Note

This method only returns 1 key of size 256 bits. It is equivalent to the Get key method with associated keyID and key size parameters below. No other option is provided.

Listing 8.16 Get key method with associated keyID and key size parameters¶

https://<kp_ip>:<kp_port>/key/<keyID>?remoteSystemID=<remote_SAE_id>&size=256

8.2.4. Get entropy¶

SAEs can request an entropy sample from KPs for its internal consumption. To obtain a quantum random generated entropy string from the KP, connect to the KP with the Get entropy method listed below.

Listing 8.17 Get entropy method¶

https://<kp_ip>:<kp_port>/entropy

An example of the above would be https://13.76.73.12:9443/entropy

A successful request will receive the following JSON response.

Listing 8.18 Example JSON response for Get entropy method¶

{
   "randomStr" : "8F49C464F122FE5AF80422BE3042BEA131DABEADA6D15E3D64C6A153E00F7FD5",
   "minentropy" : 256
}

Note

This method only returns 1 entropy string of size 256 bits. It is equivalent to the Get entropy method with minimum entropy parameter below. No other option is provided.

Listing 8.19 Get entropy method with minimum entropy parameter¶

https://<kp_ip>:<kp_port>/entropy?minentropy=256

8. REST APIs¶

8.1. ETSI GS QKD 014¶

8.1.1. Get status method¶

8.1.2. Get key method¶

8.1.3. Get key with key ID (GET) method¶

8.1.4. Get key with key ID (POST) method¶

8.2. Cisco SKIP¶

8.2.1. Get Capabilities¶

8.2.2. Get key¶

8.2.3. Get key with associated keyID¶

8.2.4. Get entropy¶

8.1.1. `Get status` method¶

8.1.2. `Get key` method¶

8.1.3. `Get key with key ID` (GET) method¶

8.1.4. `Get key with key ID` (POST) method¶