evolutionQ proposal for enhancements to ETSI GS QKD 004 version 2.1.1

AlignTrailingComments: true

AllowShortIfStatementsOnASingleLine: true

AllowShortLoopsOnASingleLine: true

IndentWidth: 4

SortIncludes: false

# Distribution / packaging

.Python

build/

build*/

develop-eggs/

dist/

downloads/

FROM docker.io/debian:bookworm

ARG PACKAGES=" g++ \

    pkg-config clang clang-format make cmake cppcheck \

    ninja-build \

    libssl-dev uuid-dev \

    gcc-i686-linux-gnu \

    libc6-i386 lib32stdc++6 \

    libssl-dev:i386 uuid-dev:i386 \

    gcc-arm-linux-gnueabihf \

    libc6-armhf-cross \

    libssl-dev:armhf uuid-dev:armhf \

    "

RUN dpkg --add-architecture i386 && dpkg --add-architecture armhf

RUN apt-get update && apt-get -y install --no-install-recommends $PACKAGES

** WORK IN PROGRESS -- STAY TUNED FOR INTERESTING THINGS TO COME **

# QKD Application Interface

# ETSI QKD 004 Reference Implementation {#mainpage}

This repository contains sample implementations that are currently under development along with an update to

**This reference implementation is under development and subject to change.**

## Overview

This repository contains a C-based ETSI GS QKD 004 reference implementation under development.

It is intended to correspond to an update of

[ETSI GS QKD 004 V2.1.1 (2020-08)](https://www.etsi.org/deliver/etsi_gs/QKD/001_099/004/02.01.01_60/gs_QKD004v020101p.pdf)

"Quantum Key Distribution (QKD); Application Interface" by

[ETSI ISG QKD](https://www.etsi.org/committee/qkd) in work item

[RGS/QKD-004ed3_AppIntf](https://portal.etsi.org/webapp/WorkProgram/Report_WorkItem.asp?WKI_ID=68576).

**IMPORTANT: These sample implementations are under development and subject to change.**

## Proposed Changes to ETSI GS QKD 004 Version 2.1.1 (2020-08)

We propose a number of clarifications, simplifications, and enhancements to ETSI QKD version 2.1.1.

These are summarized in [CHANGES.md](CHANGES.md).

Module that enables ETSI GS QKD 004 in C projects. The implementation consists of TLS socket connections using a packet

The given reference implementation takes these changes into account.

## Main Elements

The main elements provided in this repository include:

* A reusable library that enables ETSI GS QKD 004 in C projects.

  The implementation consists of TLS socket connections using packets

  with an ETSI GS QKD 004 compliant structure.

* A simple example of a client application (focusing on key retrieval).

* A mock-up implementation of a key management server.

* Examples of different use cases and error scenarios.

## Target Platform Support

# Contents

During initial development, we target Debian based GNU/Linux based systems running on x86 architectures.

* [Dependencies](#dependencies)

    * [Cmake](#cmake)

    * [Libexplain](#libexplain)

* [Build](#build)

* [Usage](#usage)

    * [Library location](#library-location)

    * [Server example](#server-example)

    * [Client example](#client-example)

One of the reasons for using Cmake as a cross-platform, compiler-independent

build system generator is to be able to add Windows support prior to releasing

a stable version.

## Dependencies <a name="dependencies"></a>

## Multithreading

### Cmake <a name="cmake"></a>

This reference implementation focuses on the ETSI QKD 004 interface.  It does not strive to

deliver optimized implementations of ETSI QKD 004 client and server.  In particular, the

reference implementation of the client is not MT-safe (multithread safe) in the sense that

one must not call its interface routines from concurrent threads.  Calls to the interface

routines of the ETSI QKD 004 reference implementation need to happen in a sequential fashion.

## Dependencies

To build this reference code, you will need the following tools and libraries

installed on your system. Alternatively, you can use a development container to

build the project (see [this section](#building-in-a-development-container)).

### CMake

Cmake is used to build the library and the examples.

sudo apt install cmake

```

### Libexplain <a name="libexplain"></a>

### ClangFormat

Libexplain is used to provide detailed info about the socket connection problems.

clang-format is used to ensure a consistent look & feel of the source code.

```shell

sudo apt install libexplain-dev

sudo apt install clang-format

```

## Build <a name="build"></a>

### Doxygen

The user can build both the library and the examples using the following commands.

Doxygen is used to generate documentation.

```shell

cd etsi-gs-qkd-004-c

mkdir cmake-build-dir

cd build-dir

cmake ..

make

cd ..

sudo apt install doxygen

```

## Usage <a name="usage"></a>

### Library location <a name="library-location"></a>

### Cppcheck

You can find the ETSI GS QKD 004 library in:

Cppcheck is used for static code analysis.

```shell

sudo apt install cppcheck

```

etsi-gs-qkd-004-c/build-dir/libetsi-gs-qkd-004.a

```

### Server example <a name="server-example"></a>

There is a server example using the ETSI GS QKD 004 library with a simple data processing, please adapt this server

example to your needs.

### Libuuid

The server example can be found at:

Libuuid is used to implement KSIDs (Key Stream IDs).

```shell

sudo apt install uuid-dev

```

etsi-gs-qkd-004-c/src/server_example.c

## Build, Test, and Documentation

The user can build library, tests, and examples using the following commands.

```shell

cd etsi-gs-qkd-004-c

mkdir build-dir

cd build-dir

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..

make

make test

cd ..

```

It can be executed using the following command:

For a debug build, use

  `cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..`

instead of

  `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..`

Documentation can thereafter be generated using the following commands.

```shell

etsi-gs-qkd-004-c/cmake-build-dir/server_example

cd build-dir

make docs

cd ..

```

IMPORTANT NOTE: As in any TLS server the server needs a certificate files (private key and certificate).

You can generate self-signed certificates using:

We use CTest as a top-level test driver.  Tests can be run after

building library, examples, and tests (see above).  The following

commands will run the complete set of tests.

```shell

# Generate CA

CA_NAME_=your_name_CA # CA name

openssl req -x509 -nodes -newkey rsa:4096 -sha256 -days 3650 -keyout $CA_NAME_.key -out $CA_NAME_.pem -subj "/CN=$CA_NAME_"

cd etsi-gs-qkd-004-c

cd build-dir

make test

cd ..

```

# Generate certificate

CN_=127.0.0.1  #localhost

openssl req -new -newkey rsa:4096 -nodes -keyout $CN_.key -out $CN_.csr -subj "/CN=$CN_" -addext "subjectAltName=IP:$CN_" || openssl req -new -newkey rsa:4096 -nodes -keyout $CN_.key -out $CN_.csr -subj "/CN=$CN_" -addext "subjectAltName=DNS:$CN_"

Note that some tests take several minutes to complete.  To run tests

more selectively, please take a look at

`etsi-gs-qkd-004-c/CMakeLists.txt` and choose the subset of tests

you are interested in.

# Sign certificate with the CA

openssl x509 -req -in $CN_.csr -CA $CA_NAME_.pem -CAkey $CA_NAME_.key -CAcreateserial -out $CN_.pem -days 3650 -sha256

If you fancy contributing changes and enhancements to the code back to

ETSI, please ensure that the code is properly formatted.  This is how

you check for proper formatting.

# Check certificate

openssl x509 -in $CN_.pem -text -noout  # openssl x509 -in file.pem -enddate -noout

```shell

cd etsi-gs-qkd-004-c

cd build-dir

make check_formatting

cd ..

```

The CA public certificate can be used in the client to validate the server.

You can also auto-format all of the code in your clone of the ETSI

QKD 004 repository with the following commands.

### Client example <a name="client-example"></a>

```shell

cd etsi-gs-qkd-004-c

cd build-dir

make format_code

cd ..

```

There is a client example using the library at:

## Building in a development container

```

etsi-gs-qkd-004-c/src/client_example.c

If you have Docker or Podman installed, you can use the provided  `Dockerfile`

to create a development container. This container can build the project for

Linux on the `amd64 (x86_64)`, `i386 (x86)`, and `armhf` architectures. A

shell script has been provided to build and start the development container.

```shell

./build_and_start_dev_container.sh

```

It can be executed using the following command:

Using the development container, a (native) Linux 64-bit build can be started

as follows.

```shell

podman exec etsi-004-builder cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build-linux-64 .

podman exec etsi-004-builder cmake --build build-linux-64

```

For the `i386` and `armhf` architectures, use the provided toolchain files,

e.g.:

```shell

etsi-gs-qkd-004-c/cmake-build-dir/client_example

podman exec etsi-004-builder cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build-linux-armhf --toolchain=/workspace/builder/etsi-gs-qkd-004-c/cmake/toolchain-armhf.cmake .

podman exec etsi-004-builder cmake --build build-linux-armhf

```

In the case of the client the certificate is not mandatory but can be also added and checked in the server.

## Directory structure

### Repository

These directories are located under etsi-gs-qkd-004-c.

* `src`: source code

    * `qkd`: reusable libraries

        * `client`: client-specific code

        * `server`: server-specific code

        * `shared`: shared code used by both client and server

    * `examples`: client and server examples (mock-ups)

* `include`: header files

    * `qkd`: headers pertaining to reusable libraries

* `examples`: examples of different use cases and error scenarios,

              also used for testing

    * `scripts`: reusable helper scripts used in more than one example

    * One directory per example.

Each example in the `examples` directory should contain

* a `README.md` file,

* a driver script for automatic execution (and testing!) of the example, and

* example-specific configuration files and helper scripts, if any.

### Build Directory

Assuming `build-dir` is the name of the build directory.

* `build-dir`: libraries (archives) and executables

    * `docs`: Doxygen-generated documentation

## Top-level Client API

See [include/interfaces.h](etsi-gs-qkd-004-c/include/qkd/interfaces.h).

## Protocol Implementation Notes

We use TLS sessions to establish connections between client and server.

The next section provides some more information regarding authentication,

authorization, confidentiality, and integrity of client-server sessions.

Clients can issue multiple commands per session.  However, it is not

required to send all commands (OPEN_CONNECT, GET_KEY, ..., CLOSE)

pertaining to a particular KSID using the same TLS session.

Within a TLS session, commands must be processed in order though.  That

is, after submitting a request, a client must first wait for the server

to send the complete response prior to transmitting the next request.

The network representation (a.k.a. byte buffer protocol) is rather

straightforward.

See [include/serializers.h](etsi-gs-qkd-004-c/include/qkd/serializers.h)

and [src/qkd/shared/serializers.c](etsi-gs-qkd-004-c/src/qkd/shared/serializers.c)

for details.

## Authentication, Authorization, Confidentiality, and Integrity

The following describes best practices.  It should be noted that the

ETSI QKD 004 reference implementation, in particular as far as example

code is concerned, does not follow most of these guidelines.  This is

done in order to keep the code short so that the reader can more

easily focus on the ETSI QKD 004 interface.

In general, it is expected that the client application is co-located with

the key management server in a secure environment.  Still, it is good practice

to use strong cryptographic means to ensure mutual authentication of client

application and key management server as well as encryption (confidentiality,

integrity) of data packets in order to protect against incorrect wiring and

inside attackers.

The communication between client application and key management server is based

on a TLS connection.  In order to keep example code concise and focus on implementation

and use of the ETSI GS QKD 004 interface, we did cut corners in some examples as far as

TLS connection parameters are concerned.  Here are some recommendations for real-life

examples aimed at providing long-term security (LTS) against record-now-decrypt-later attacks:

* Use cipher suites based on strong cryptographic algorithms and key sizes such as

  AES-256 GCM and SHA-256/384.

* Consider using strong RSA keys (4096 bit) keys for TLS authentication.

  While RSA is not entirely safe against future attacks mounted with a

  sufficiently powerful quantum computer, it does require more than 4x the

  number of qubits to crack RSA-4096 compared to an 256bit ECC key.

* For LTS, use pre-shared keys (PSKs) in addition to an (EC)DHE key exchange.

  (Do not use PSKs without the (EC)DHE key exchange as you would lose the

  benefit of whatever forward secrecy classic asymmetric key exchanges will

  offer in the long run.)  Be aware of RFC 8773 in this context.

* Keep an eye open for post-quantum crytography (PQC) extensions to

  TLS.  (OpenSSL 3.2 already offers plugable signature algorithms and

  key establishment mechanisms (KEMs) in conjunction with TLS 1.3.)

  Hybrid modes combining classical asymmetric cryptography (e.g., RSA)

  and PQC are preferred.  Mind that the use of PSKs is still required

  to achieve LTS, even in the presence of PQC extensions.

* Use mutual authentication and, hence, require client authentication

  (i.e., verification of the client certificate).

* Consider implementing an authorization scheme, i.e., in addition to requiring

  clients to authenticate themselves, maintain some type of access control

  to determine whether a particular client is entitled to opening connections

  and submitting requests.  (Policing and accounting may play into this.)

## Contact