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¶
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"
}
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.
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.
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.
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.
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.
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.
{
"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.
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.
{
"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.
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.
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.
{
"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.
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.
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.
{
"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.
https://<kp_ip>:<kp_port>/entropy?minentropy=256