Description

This project provides a reference implementation to the ETSI GS QKD 014 v1.1.1 standard.

Installation

Reference OS

Ubuntu 22.04.1 LTS

This implementation has been developed and tested on Ubuntu 22.04.1 LTS. While no OS specific components are present in this implementation, no guarantees are made that it works on other OSs. If you encounter issues deploying this implementation on another OS, reach out and we will try our best to make it work on your setup.

Required OS packages

The server requires the following packages to be installed:

• build-essential
• pkg-config
• libssl-dev

On Ubuntu, these can be installed using

sudo apt install build-essential pkg-config libssl-dev

Rust

The implementation has been developed in Rust and requires the rust toolchain to be installed. This is typically done using an installation script downloaded with curl.

If curl is not already installed, run the command

sudo apt install curl

The installation script can then be downloaded and executed using the command

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the on-screen instructions to install rust.

Database management packages

The SQLx rust library is used to handle database operations, including migrations.

To install the SQLx command line interface, run the command

cargo install sqlx-cli --no-default-features --features rustls,postgres

To confirm that installation was successful, run the command

sqlx --version

The output should be similar to

sqlx-cli 0.7.4

Docker Compose

The implementation runs on docker compose. To install docker compose run the command

sudo apt install docker-compose-v2

To verify the installation was successful, run

docker run hello-world

You should see the output:

Hello from Docker!

You may need to add your user to the docker group and start the docker service, to do so run

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

This will add your user to the docker group.

sudo systemctl start docker

This will start the docker service. Note, if the docker service was already running, you may need to run

sudo systemctl restart docker

for the group changes to take effect.

Set up

Start database

Run

make db_start

This will create and launch a docker container running a postgres database running at DATABASE_URL.

SQLx migrations

To run the diesel migration SQL scripts and set-up the database, run the following command:

make db_migration

This command will execute the up.sql scripts in the migrations folder that have not yet been executed on the database.

ETSI QKD 014 Standard

The ETSI QKD 014 standard requires that mutual TLS (mTLS) authentication is performed. This requires both the server and the client to authenticate each other. Most commonly, only the server's certificate is authenticated by the client, with the server doing no such authentication. Due to the sensitivity of the application, mTLS is required.

Secure Application Entity (SAE)

The SAE, is referred to the client, because it is the entity that will be issuing the requests.

Key Management Entity (KME)

The KME, is the application that this server aims to emulate. It will be referred to as the server.

Certificates

A root CA will be generated and used to sign both the SAE (client) and KME (server) certificates. This is to emulate a certificate that is signed by a trusted Certificate Authority (CA).

Generate a self-signed certificate

The generation of a certificate involves the

• Generation of a private key,
• Generation of a certificate signing request, and
• Signing of the certificate.

The generation of a private key and self-signed certificate can be done using a single command. The nodes option is set such that the private key is not passphrase protected.

openssl req -x509           \
    -newkey rsa:4096        \
    -days 3650              \
    -nodes                  \
    -keyout test.key        \
    -out test.crt           \
    -subj "/CN=test_123456" \
    -addext "subjectAltName=IP:127.0.0.1"

Certificate generation

All the below commands are part of the included makefile in the certs directory. Certificates can be generated by issuing the command

make certs

Note: the makefile uses the 'ts' command which is a part of the moreutils package. To install this command run

sudo apt install moreutils

Root CA

Generate a password protected root certificate.

openssl req -x509                                            \
    -newkey rsa:4096                                         \
    -days 365                                                \
    -subj "/C=MT/CN=www.merqury.eu/O=Merqury\ Cybersecurity" \
    -keyout root.key                                         \
    -out root.crt

KME Certificate

Generate the KME private key and a Certificate Signing Request (CSR).

openssl req                                          \
    -newkey rsa:4096                                 \
    -nodes                                           \
    -days 365                                        \
    -subj "/C=MT/O=Key Management Ltd/CN=kme_123456" \
    -keyout kme.key                                  \
    -out kme.csr

Create an extensions file to specify the alternative names

echo "subjectAltName = IP:127.0.0.1" >> kme.ext

Sign the certificate using the root CA's key

openssl x509 -req    \
    -in kme.csr      \
    -CA root.crt     \
    -CAkey root.key  \
    -set_serial 01   \
    -days 365        \
    -extfile kme.ext \
    -out kme.crt

SAE Certificate

Generate the sae private key and a Certificate Signing Request (CSR).

openssl req                                              \
    -newkey rsa:4096                                     \
    -nodes                                               \
    -days 365                                            \
    -subj "/C=MT/O=Secure Application Ltd/CN=sae_123456" \
    -keyout sae.key                                      \
    -out sae.csr

Create an extensions file to specify the alternative names

echo "subjectAltName = IP:127.0.0.1" >> sae.ext

Sign the certificate using the root CA's key

openssl x509 -req    \
    -in sae.csr      \
    -CA root.crt     \
    -CAkey root.key  \
    -set_serial 01   \
    -days 365        \
    -extfile sae.ext \
    -out sae.crt

Utilities

To view the private key contents

openssl pkey -in test.key -text -noout

To extract the public key from the private key

openssl pkey -in test.key -pubout -out server-public.key

To view the Certificate Signing Request (CSR) contents

openssl req -text -in test.csr -noout

To examine the certificate

openssl x509 -text -in test.crt -noout

Environment variables

Variable name	Description
ETSI_014_REF_IMPL_IP_ADDR	Ip address the server will bind to.
ETSI_014_REF_IMPL_PORT_NUM	The port number the server listens on.
ETSI_014_REF_IMPL_DB_URL	Database URL.
ETSI_014_REF_IMPL_TLS_ROOT_CRT	Root CA certificate.
ETSI_014_REF_IMPL_TLS_PRIVATE_KEY	Private key.
ETSI_014_REF_IMPL_TLS_CER	TLS certificate (public key).
ETSI_014_REF_IMPL_NUM_WORKER_THREADS	Number of threads the server will use.

Examples

The examples folder contains multiple bash scripts that show the user how to launch and interact with the reference implementation. The enc_keys.sh and dec_keys.sh scripts send requests using curl to the web service. The run_server.sh script launches a server instance with the required environment variables.

The Makefile allows the user to run these scripts in a coordinated way.

make run_server

Runs the server using the same database created with make db_start.

make get_enc_key

Retrieves an encryption key.

make post_enc_key

Retrieves 3 encryption keys.

make get_dec_key KEY=XXX

Retrieves the decryption key with key-id XXX.

make post_get_key KEYS='XXX YYY ZZZ ...'

Retrieves the decryption keys with IDs XXX, YYY, ZZZ and so on.

License

© 2023 Merqury Cybersecurity Ltd.

This project is licensed under the GNU Affero General Public License v3.0 only. If you would like to use this product under a different license, kindly contact us on info@merqury.eu.

Acknowledgements

This software has been developed in the projects EQUO (European QUantum ecOsystems) which is funded by the European Commission in the Digital Europe Programme under the grant agreement No 101091561 and PRISM (Physical Security for Public Infrastructure in Malta) which is co-funded by the European Union under the Digital Europe Programme grant agreement number 101111875.