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
KME A (SAE ID = SAE_A):
https://13.76.73.12:8443
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.
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.
{
"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.
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.
{
"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.
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.
{
"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.