Getting Started
This getting started guide provides step-by-step instructions describing how to configure QuKayDee to start producing keys and how to retrieve those keys using the ETSI QKD 014 interface.
Topology
We will create a very simple topology consisting of two key management entities (KMEs), two secure application entities (SAEs), and one point-to-point key stream (KS). For clarity, we also show two QKD entities (QKDEs), but these are not configured in QuKayDee.
Create an account
On the login page click on the Create Free Account button.
In the Create a Free Account screen enter your information and click on the Create Account button.
QuKayDee sends an email to you to confirm your email address:
Wait for the email to arrive and click on the confirmation link to activate the account. If the email does not arrive, check your spam folder. If it is also not there, send an email to support@qukaydee.com. When you click on the link, the account is activated:
Log in
At this point you can login with your chosen username and password:
Create Key Management Entities (KMEs)
Click on Key Management Entities in the menu. The list of existing key management entities (which is initially empty) appears.
Click on the Add button to add a new key management entity.
In the Key Management Entity form:
- Leave the KME ID field set to its default value which is kme-1.
- Set the Name field to KME Alice.
Click the Save button.
This create a key management entity with KME ID kme-1 and name KME Alice which provides an ETSI QKD 014 Key Delivery API. Later in this getting started guide we will see how secure application entities can get keys using this API.
Add a second key management entity with name KME Bob.
At this point, there are two key management entities: KME Alice and KME Bob:
Create Secure Application Entities (SAEs)
Click on Secure Application Entities in the menu. The list of existing secure application entities (which is initially empty) appears.
Click on the Add button to add a new secure application entity.
In the Secure Application Entity form:
- Leave the SAE ID field set to its default value which is sae-1.
- Set the Name field to SAE Alice.
- In the Key management entity field select KME Alice from the drop-down meny.
- Leave the Certificate distinguished name set to its default value which is CN=sae-1. It is important that you don't change it because the scripts that we will use to generate the certificates will use this format.
Click the Save button.
This defines a secure application entity with SAE ID sae-1 and name SAE Alice which is an external client that is authorized to get keys from KME Alice using the ETSI QKD 014 Key Delivery API.
Add a second secure application entity with name SAE Bob and associated with KME Bob.
At this point, there are two key management entities: SAE Alice and SAE Bob:
Create Key Stream (KS)
Click on Key Streams in the menu. The list of existing key streams (which is initially empty) appears.
Click on the Add button to add a new key stream.
In the Key Stream form:
- In the secure application entities field, select both SAE Alice and SAE Bob.
- Set the key rate field to 1000 bits per second.
- Change the key expiry time field from its default value of 60 seconds to 600 seconds. Later on, that will give us more time to follow the getting started guide when we invoke the API.
Click the Save button.
This creates a point-to-point key stream between secure application entities SAE Alice and SAE Bob. This key stream produces key material at a rate of 1000 key bits per second. After the master secure application entity retrieves a key using the ETSI QKD 014 get-key API call, the slave secure application entities have up to 60 seconds to retrieve the key using the ETSI QKD 014 get-key-with-key-ids API call before the key is flushed.
At this point, there is one key stream, namely the key stream between SAE Alice and SAE Bob. This key stream has already begun producing key material; in this screen shot we can see that 27 key bits have been produced. If you refresh the screen in your browser, you will see this number go up at a rate of 1000 key bits per second.
View Details of Key Management Entity Alice
In the menu click on Key Management Entities and then click on the View button for KME Alice:
Here we can see that KME Alice has been assigned Server API Hostname kme-1.acct-2.etsi-qkd-api.qukaydee.com. The is the URL for the ETSI QKD 014 API which client SAEs can use to retrieve keys.
And we can see that KME Alice has one associated secure application entity, namely SAE Alice, which is allowed to get keys from KME Alice. Other secure application entities are not allowed to get keys.
Download the Server CA Certificate
The ETSI QKD 014 API uses mutual authentication transport layer security (mTLS): the key management entities (who are the servers) and the secure application entities (who are the clients) use certificates and keys to authenticate each other. See the tutorial for more details on authentication, certificates, and keys.
To download the server CA certificate, click on API in the menu and then click on the Download Server CA Certificate button.
For the purpose of this getting started guide, we are going to create a test directory to gather all the required certificate and key files. Create the test directory and copy the downloaded server CA certificate into it:
Note: The downloaded file contains your account ID. In the following example the account ID is 2, but it is likely different for your account.
$ cd ~ $ mkdir test $ cd test $ cd cp ~/Downloads/account-2-server-ca-qukaydee-com.crt .
Later on, when we invoke the ETSI QKD 014 APIs, we will use this downloaded server CA certificate to authenticate the key management entity running in QuKayDee.
Generate and Upload the Client CA Certificate
In this step we generate the client CA certificate and key. These are used in the next step to sign the client SAE certificates.
We use bash scripts stored in the public GitHub repository brunorijsman/qukaydee-generate-client-certificates to generate the certificates and keys.
First clone this repository:
$ git clone https://github.com/brunorijsman/qukaydee-generate-client-certificates.git Cloning into 'qukaydee-generate-client-certificates'... ...
Enter the cloned directory:
$ cd qukaydee-generate-client-certificates
Invoke the following bash script to generate the client CA certificate and key:
$ ./generate-client-root-ca-certificate-and-key.sh
This script doesn't have any output but it does produce the following two files:
$ ls ... client-root-ca.crt client-root-ca.key ...
Copy the generate client CA certificate and key file to the test directory where we are gathering all certificates and files:
$ cp client-root-ca.* ~/test
Upload Client CA Certificate
Upload the generate client CA certificate by clicking on API in the menu and then clicking on the Upload Client CA Certificate button:
In the Upload Client CA Certificate screen click on Choose File, navigate to the generate client-root-ca.crt file, click Open, and finally click on Upload.
Generate Client SAE Certificates
In this step we generate the client SAE certificates and keys for each of the two secure application entities that we have created: SAE Alice (with SAE ID sae-1) and SAE Bob (with SAE ID sae-2). Once again, we use the bash scripts from the repository that we cloned in the previous step.
Invoke the following bash script to generate the client CA certificates and keys:
$ ./generate-client-sae-certificate-and-key.sh sae-1 $ ./generate-client-sae-certificate-and-key.sh sae-2
This script doesn't have any output but it does produce the following files:
$ ls ... sae-1.crt sae-1.key sae-1.pem sae-2.crt sae-2.key sae-2.pem ...
The .crt files contain the SAE certificate, the .key files contain the SAE private key, and the .pem files contain the CA + SAE certficate chain and the private key.
The client SAE certificates do not need to be uploaded; we will use them later when we invoke the ETSI QKD API.
Copy the generate client CA certificate and key file to the test directory where we are gathering all certificates and files:
$ cp sae-* ~/test
View API Documentation
QuKayDee provides the REST API for key delivery which is defined in standard ETSI GS QKD 014 V1.1.1 (2019-20) . To see the OpenAPI speficiation of that same API select API in the menu and then click on the ETSI QKD 014 API Documentation link in the API Documentation panel:
Invoke the ESTI QKD API using Curl
In this section we use curl to invoke the ETSI QKD 014 API. Make sure that you have curl installed.
We also use JSON query (jq) to pretty-print the JSON return value of the API calls. If you don't have jq installed, just don't pipe the output through jq.
Change into the directory where we gathered all the certificate and key files:
$ cd ~/test
Earlier, when you downloaded the server CA certificate, we mentioned that the downloaded filename contains your account ID which is a number. Here, we store the account ID in a shell variable which makes it easier to copy and past the example curl commands.
$ export ACCOUNT_ID=your-account-id-here
The account ID is not a secret value. The client authenticates itself using the client certificate and key.
Get status
The following curl command calls the "Get status" method in the ETSI QKD 014 API to ask kme-1 for the status of the key stream between sae-1 and sae-2:
$ curl \
--silent \
--cacert account-$ACCOUNT_ID-server-ca-qukaydee-com.crt \
--cert sae-1.crt \
--key sae-1.key \
--header "Accept: application/json" \
https://kme-1.acct-$ACCOUNT_ID.etsi-qkd-api.qukaydee.com/api/v1/keys/sae-2/status \
| jq
The output should be similar to this:
{
"source_KME_ID": "kme-1",
"target_KME_ID": "kme-2",
"master_SAE_ID": "sae-1",
"slave_SAE_ID": "sae-2",
"key_size": 512,
"stored_key_count": 1953,
"max_key_count": 1953,
"max_key_per_request": 100,
"max_key_size": 100000,
"min_key_size": 1,
"max_SAE_ID_count": 9
}
Get key
The following curl command calls the "Get key" method in the ETSI QKD 014 API to ask kme-1 to deliver two keys of 1024 bits each. The local client to which the key is being delivered (the so-called master SAE) is sae-1. The remote client on the other side of the key stream (the so-called slave SAE) is sae-2.
$ curl \
--silent \
--cacert account-$ACCOUNT_ID-server-ca-qukaydee-com.crt \
--cert sae-1.crt \
--key sae-1.key \
--header "Accept: application/json" \
https://kme-1.acct-$ACCOUNT_ID.etsi-qkd-api.qukaydee.com/api/v1/keys/sae-2/enc_keys?number=2&size=1024 \
| jq
Note: If you followed along with the instructions, you configured the key stream to expire keys after 600 seconds (10 minutes). Because of this, you have to invoke the "Get key with key IDs" described in the next section within 10 minutes for it to succeed.
The output should be similar to this:
{
"keys": [
{
"key_ID": "16fb8915-e50e-4212-8c34-a4b780297f8f",
"key": "DyVFM+ftKRkfAWHLOjJN3sZ4D4GN6//PoU0URZpiou2bTZEajF3v9pPs3xeNzmUwDtK4v32seeCO+xagr8cCOyMKTLUjlFN4ao6WTLCqxE5q5C685S8QbyLnqtshvsmibCHRrt8GUZ60Ax3i05Wer2JYh5mh4+1ZQj7zh90EX4w="
},
{
"key_ID": "2b1754c1-c827-4345-b933-b28014d47a5f",
"key": "0RTGk5ttV93b+SiEXgIKfBueiiDHI7dVT9pIwuU88tAFaIei4G+0e9ptUH4Pilngdi+EPGl4adtJa7AcyA6MUMDdsgWuz4U3fSjrtqK0+7wK7WkCRnI5F+omD9cMBR9gSIF/E/1cPBb9sZ99LXEXHdbOATGXdSnrL4oD66szZCI="
}
]
}
Get key with key IDs
The "Get key" call was used to KME kme-1 to produce two keys for the master SAE, which is sae-1. We got two keys, each with their own key ID. In this section, we are going to ask the other KME, which is kme-2, to retrieve one of those two keys for the slave SAE, which is sae-2.
For the "Get key with key IDs" API call we need the key ID of one of the keys that was returned by the previous "Get key" API call. In the above example output "16fb8915-e50e-4212-8c34-a4b780297f8f" is the key ID of the first returned key. To make it easier to copy and paste the curl command below, store they key ID that was returned in an environment variable:
$ export KEY_ID="your-key-id-here"
The following curl command calls the "Get key with key IDs" method in the ETSI QKD 014 API to ask kme-2 to deliver the key with a given key ID:
$ curl \
--silent \
--cacert account-$ACCOUNT_ID-server-ca-qukaydee-com.crt \
--cert sae-2.crt \
--key sae-2.key \
--header "Accept: application/json" \
https://kme-2.acct-$ACCOUNT_ID.etsi-qkd-api.qukaydee.com/api/v1/keys/sae-1/dec_keys?key_ID="$KEY_ID" \
| jq
The output should be similar to this:
{
"keys": [
{
"key_ID": "16fb8915-e50e-4212-8c34-a4b780297f8f",
"key": "DyVFM+ftKRkfAWHLOjJN3sZ4D4GN6//PoU0URZpiou2bTZEajF3v9pPs3xeNzmUwDtK4v32seeCO+xagr8cCOyMKTLUjlFN4ao6WTLCqxE5q5C685S8QbyLnqtshvsmibCHRrt8GUZ60Ax3i05Wer2JYh5mh4+1ZQj7zh90EX4w="
}
}
View key store
It is interesting to look at the contents of the key store at this point. To do so, select Key Streams in the menu and then click on the View button for the key stream (there is only one). You will see something similar to this (assuming you do this within 10 minutes of creating the keys):
There is still one key in the key store. This is one of the two keys produced by the "Get key" call above, namely the key which was not yet retrieved by the "Get key with key IDs" call. We can see that "Pending Slave SAEs" is "SAE Bob", which means that QuKayDee is still waiting for SAE Bob to get the key. If he doesn't do so within the configured 10 minutes, the key will be flushed.
Previously we produced two keys, but we only see one key here. That is because the other key was already retrieved by SAE Bob using the "Get key with key IDs" call.