The bash scripts in this repository are intended to be used in conjunction with QuKayDee (https://qukaydee.com) which is a cloud-based Quantum Key Distribution (QKD) network simulator.

The simulated QKD network running in QuKayDee consists of simulated QKD devices that produce encryption keys. These encryption keys are stored in simulated Key Management Systems (KMSs) that also run in QuKayDee.

The users of QuKayDee have encryption devices at their own location, outside of QuKayDee. These encryption devices consume the keys that are produced by QuKayDee.

The simulated KMS devices in QuKayDee provide a standard REST API defined in ETSI QKD 014 for delivering the generated encryption keys to the user's encryptors.

See the QuKayDee tutorial (https://qukaydee.com/pages/tutorial) for more details.

The ETSI QKD 014 standard uses the following terminology:

• The key management system (KMS) device is called a Key Management Entity (KME).

• The encryptor device is called a Secure Application Entity (SAE).

Furthermore, the ETSI QKD 014 standard uses mutual authentication transport layer security (mTLS) between the KME (which is the server) and the SAE (which is the client).

This means that the KME servers running in QuKayDee need client certificates to authenticate each SAE client that is allowed to retrieve keys.

One approach would be to upload those client certificates for each authorized SAE to QuKayDee, but that would be very cumbersome.

Instead, we use the following simpler approach:

1. The user generates one single self-signed certificate authority (CA) certificate and key. We refer to this as the client CA certificate and key. It is used as the root of trust for all SAEs that are under control of that user.

2. Also, the user generates one additional client certificate for each SAE under control of that user. We refer to these as the client SAE certificates and keys. The client SAE certificates are signed using the client CA key from step 1 above.

3. The user uploads only the client CA from step 1 certificate to QuKayDee (using the Upload Client CA Certificate button in the API screen).

4. The KME server running in QuKayDee can authenticate the SAE client using the client CA certificate uploaded in step 3. The client SAE certificate generated in step 2 does not need to be uploaded; the ETSI QKD 014 REST API client provides it as part of the initial TLS protocol handshake.

The bash script generate-client-root-ca-certificate-and-key.sh generates the client CA certificate and key.

You only need to run this script once, regardless of how many SAEs there are.

You must have openssl installed on your computer to run this script.

The script takes no arguments and produces no output:

$ generate-client-root-ca-certificate-and-key.sh
$

It creates two files that contain the client CA certificate and key:

$ ls
...
client-root-ca.crt
client-root-ca.key
...

Upload the generate filed client-root-ca.crt to QuKayDee by selecting API in the menu and clicking on the Upload Client CA Certificate button.

Once you have created the client CA certificate and key, you also need to generate one client SAE certificate for each SAE (i.e. for each encryptor) that consumes keys generated by QyKayDee.

The script takes the SAE identifier (SAE ID) as its only argument and produces no output:

$ generate-client-sae-certificate-and-key.sh sae-1
$

It creates three files that contain the client SAE certificate and key:

$ ls
...
sae-1.crt
sae-1.key
sae-1.pem
...

The .crt file contains the SAE certificate, the .key file contains the SAE private key, and the .pem file contains the SAE private key plus the entire certificate chain (client CA certificate and SAE certificate).

None of these three files is uploaded to QuKayDee; instead they are used when the client invokes an ETSI QKD API (see curl example below).

So far, we have described how to generate the client certificates and client keys that the SAE uses to authenticate itself to the KME.

Since there is mutual authentication (mTLS) between the KME and the SAE, each KME also needs a server certificate and a server key to authenticate itself to the SAE.

The bash scripts in this repository are not intended to generate these server certificates and keys. Instead, the cloud-hosted QuKayDee software generates the server certificate and the key for each KME.

Once again, one possible approach would be to download a separate server certificate for each KME, but that would be cumbersome.

Instead, QuKayDee generates one single self-signed server root certificate authority (CA) certificate and key for all KMEs. We refer to this as the server CA certificate and key.

You can download this server CA certificate by going to the API menu and clicking on the Download Server CA Certificate button.

This downloads the following file into the Downloads folder on your computer:

$ ls
account-1-server-ca-qukaydee-com.crt

The account-1 in the filename is the account identifier for your account in QuKayDee (each user gets a different server CA certificate).

Move this file to the same directory where your client certificates and keys are.

Internally, QuKayDee also generates a server KME certificate and key for each KME but those cannot be downloaded; they are only used internally by QuKayDee during the mTLS initial handshake.

Now that we know how to generate both the client and server certificates and keys, we explain how to use them to invoke the ETSI QKD 014 API provided by QuKayDee.

There are multiple ways to invoke the API; here we will use curl.

This example assumes that you have already:

• Created a free account in QuKayDee (https://qukaydee.com/account/create)
• Configured two KMEs (kme-1 and kme-2).
• Configured two SAEs (sae-1 and sae-2).
• Configured one key stream (ks-1) between sae-1 and sae-2.
• Downloaded the server CA certificate.
• Generated and uploaded the client CA certificate.
• Generated the client SAE certificates and keys for at least sae-1.

See the QuKayDee getting started guide https://qukaydee.com/pages/getting_started for more details on how to configure the KMEs, the SAEs, and the key stream, and how to generate, upload, and download the various certificates and keys.

That same guide also contains examples of how to invoke the other APIs and describes other tools for invoking the API (e.g. using Postman)

The following curl command invokes the ETSI QKD 014 API to retrieve the status of the sae-1 to sae-2 key stream:

$ curl \
  --silent \
  --cacert account-1-server-ca-qukaydee-com.crt \
  --cert sae-1.crt \
  --key sae-1.key \
  --header "Accept: application/json" \
  https://kme-1.acct-1.etsi-qkd-api.qukaydee.com/api/v1/keys/sae-2/status \
  | jq

This produces output 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
}

We pipe the output into jq (Jason Query) to pretty-print the output. If you don't have jq installed, you can leave that out.