Project

General

Profile

Configuration

The AIT QKD R10 configuration consist of four elements:

  • System environment configuration
  • Module configuration
  • Pipeline configuration
  • Node configuration

The system environment configuration sets up the operating system features needed to let the QKD modules interact and to manage them.

Each module picks its configuration from the dedicated module configuration setting. Additionally, a series of QKD Modules–a QKD Pipeline–has its own dedicated configuration setting.

Finally, the Q3P node has its own set of configuration values.

System environment

The QKD R10 post processing consists of loosely coupled programs: the QKD modules. Each module serves a dedicated task in the QKD post-processing stack: sifting, error correction,...

Note: only system users which are member of the qkd system group or root may invoke qkd installed programs. When working with the AIT QKD R10 be sure that your current user is member of this qkd group.

In order to let the module configure itself and to fit itself nicely into a series of modules, a QKD pipeline, the AIT QKD R10 heavily depends on the existence of a sound and fast inter-process communication technique. This is DBus.

DBus is an essential part of modern Linux/Unix desktop environments like Gnome or KDE. Today, when a user logs into Linux/Unix desktop environment, he is confronted with two concurrent running DBus instances: a system DBus and a session DBus. The system DBus provides objects for operating system managing like hardware, network management and such. The session DBus is dedicated to a single user seat on the system and deals with objects serving user needs like mail agents, address book, volume control, and others.

From the various tools available to examine and browse DBus objects, you can use the qdbus command line tool or d-feet for more GUI oriented users.

From this perspective, QKD related objects ought to be placed and managed inside the system DBus. However, as this is a security centered endeavor, we do not want to interfere with other core system management tasks and objects on a superuser privilege level. This is why the AIT QKD R10 sets up its own DBus: qkd-dbus.

The installed components for the system environment are now:

/etc/
├── dbus-1
│   └── qkd.conf
├── default
│   └── qkd-dbus
├── init.d
│   └── qkd-dbus
├── profile.d
│   └── qkd_dbus_address.sh
└── systemd
    └── system
        ├── qkd-dbus.service
        └── qkd-dbus.socket
  • /etc/dbus-1/qkd.conf: This file contains the configuration of the qkd-dbus. This is a DBus configuration file as used by the dbus-daemon. You can find the documentation for this file by running:
    $ man dbus-daemon
    

    The most important directive in this file is the address of the qkd-dbus which has to be known by every QKD module:
    <listen>unix:path=/run/dbus/qkd_dbus_socket</listen>
    
  • /etc/profile.d/qkd_dbus_address.sh: This file declares the environment variable QKD_DBUS_SESSION_ADDRESS which points to the qkd-dbus address.
    export QKD_DBUS_SESSION_ADDRESS="unix:path=/run/dbus/qkd_bus_socket" 
    

    Any user process related to the AIT QKD R10 should have this variable declared, otherwise the local session DBus is queried for AIT QKD R10 modules.
    Hint: if you log in to a system please check if this environment variable is set like this:
    $ env | grep QKD_DBUS_SESSION_ADDRESS
    QKD_DBUS_SESSION_ADDRESS=unix:path=/run/dbus/qkd_bus_socket
    
  • /etc/default/qkd-dbus and /etc/init.d/qkd-dbus: these files declare the qkd-dbus service when installed into a SysV-style operating system. Once installed, you can start the qkd-dbus with:
    # /etc/init.d/qkd-dbus start
    

    and stop it via:
    # /etc/init.d/qkd-dbus stop
    

    Note: the installation via Debian packages sets the qkd-dbus service to start on boot per default.
  • /etc/systemd/system/qkd-dbus.service and /etc/systemd/system/qkd-dbus.socket: these files declare the qkd-dbus service when installed into a modern systemd setting.
    You can start qkd-dbus with:
    # systemctl start qkd-dbus
    

    and stop it via:
    # systemctl stop qkd-dbus
    

    Note: the installation via Debian packages sets the qkd-dbus service to start on boot per default.

Module configuration

Each module needs some configuration in order to fulfill its task. Modules now pick their configuration values from a config file which is written in the well-known INI-file syntax.

As an example, take a look at the following configuration of a bb84 module instance:

[module]

# bb84
bb84.alice.url_peer = tcp://127.0.0.1:7120
bb84.alice.url_pipe_in = ipc:///tmp/qkd/bb84.alice.in
bb84.alice.url_pipe_out = ipc:///tmp/qkd/cascade.alice.in
bb84.bob.url_listen = tcp://127.0.0.1:7120
bb84.bob.url_pipe_in = ipc:///tmp/qkd/bb84.bob.in
bb84.bob.url_pipe_out = ipc:///tmp/qkd/cascade.bob.in
bb84.key_id_pattern = 0/0
bb84.rawkey_length = 2048
bb84.pipeline = default
bb84.synchronize_keys = false

This module configuration file is normally located in /etc/qkd/ and has no standard name, though a /etc/qkd/pipeline-default.conf is installed. This configuration file holds the definition of a simple QKD pipeline.

Every module can be given the same configuration file. Using the module's name and its role, the module itself picks the key-value pairs meant for it and discards all other lines in the file. This is why besides the module's name, which is intrinsic to the module, the module's role has to be set before the module loads the configuration file.

All AIT QKD R10 modules do understand a minimum set of shared configuration keys. These are (substitute IDs properly):

  • [ID].alice.url_peer: Address of Alice's remote peer module (== Bob).
  • [ID].alice.url_pipe_in: Local input for pulling keys from the previous module, Alice version.
  • [ID].alice.url_pipe_out: Address of next module to push keys to, Alice version.
  • [ID].bob.url_listen: Address of locale port to listen for connections of the remote module (== Alice)
  • [ID].bob.url_pipe_in: Local input for pulling keys from the previous module, Bob version.
  • [ID].bob.url_pipe_out: Address of next module to push keys to, Bob version.
  • [ID].pipeline: Name of pipeline to participate.
  • [ID].random_url: URL of random number source.
  • [ID].synchronize_keys: "true" or "false" to enable or disable key synchronization.
  • [ID].synchronize_ttl: Time To Live for out of sync keys.
  • [ID].timeout_network: Timeout in milliseconds for peer-remote module communication.
  • [ID].timeout_pipe: Timeout in milliseconds when pulling from the previous module in the pipe.

Note: these keys have to be placed inside the "[module]" section. If not, the module won't recognize its keys.

Besides these standard configuration values, each module may introduce new configuration keys dedicated to the module's own working goals.

Pipeline configuration

Orchestrating a whole pipeline is done via the qkd-pipeline tool. This program requires a pipeline configuration file, which essentially lists all modules to participate, in a single pipeline. Neither this configuration line nor the qkd-pipeline tool do interconnect the modules. This is solely done with the url_pipe_in and url_pipe_out values in the module configuration file. Instead, a pipeline configuration lists all modules in the pipeline and how to start them.

A pipeline configuration file is an XML-based file which looks like this:

<pipeline name="default">

    <module path="qkd-bb84" start="yes">
        <config path="/etc/qkd/pipeline-default.conf" />
        <role value="alice" />
        <args value="--debug" />
        <log path="qkd-bb84.alice.log" />
    </module>

    <module path="qkd-cascade" start="yes">
        <config path="/etc/qkd/pipeline-default.conf" />
        <role value="alice" />
        <args value="--debug" />
        <log path="qkd-cascade.alice.log" />
    </module>

    <module path="qkd-confirmation" start="yes">
        <config path="/etc/qkd/pipeline-default.conf" />
        <role value="alice" />
        <args value="--debug" />
        <log path="qkd-confirmation.alice.log" />
    </module>

    <module path="qkd-buffer" start="yes">
        <config path="/etc/qkd/pipeline-default.conf" />
        <role value="alice" />
        <args value="--debug" />
        <log path="qkd-buffer.alice.log" />
    </module>

    <module path="qkd-privacy-amplification" start="yes">
        <config path="/etc/qkd/pipeline-default.conf" />
        <role value="alice" />
        <args value="--debug" />
        <log path="qkd-privacy-amplification.alice.log" />
    </module>

    <module path="qkd-tee" start="yes">
        <config path="/etc/qkd/pipeline-default.conf" />
        <role value="alice" />
        <args value="--debug" />
        <args value="--file">qkd-keys.alice</args>
        <log path="qkd-tee.alice.log" />
    </module>

</pipeline>

As such a pipeline is a series of modules. Each module has a unique path attribute which points to the binary executable. If not fully specified, the system looks up the location within the PATH environment variable. Also, each module may be started immediately.

Two crucial elements are added to the module definition then: config holds the path to the module's configuration file whereas role states if the module acts either as Alice or as Bob.

Additional command line arguments can be passed along the with the args tag.

Finally all log output may be directed to the file specified. If this is a relative path, this value is concatenated with the overall log path of the qkd-pipeline itself. Log output is created whenever inside the module stderr, qkd::utility::syslog or qkd::utililty::debug methods are invoked.

E.g. having such configuration placed in a file my-pipeline.xml, one can start it like this:

$ mkdir qkd-logs-test-0001
$ qkd-pipeline --log qkd-logs-test-0001 start my-pipeline.xml

This will start all modules defined in my-pipeline.xml. Additionally, modules will write their debug output to files inside the qkd-logs-test-0001 folder separately for each module.

Hint: debug output can be turned on and off during runtime at any time by using DBus calls on the module. Turning off debug output increases performance.

Node configuration

The Q3P node configuration file is trivial in comparison. The node is a collection of Q3P links which each needs to now these values:

  • What is the link's ID?
  • Where is the key store?
  • Act the node as master or slave?
  • What is my public port to listen to remote nodes?
  • What is the address of my peer node?
  • What is my initially shared secret?
  • What are my IPSec specifications?

All these questions are directly covered by /etc/q3p/q3pd.conf, which holds the configuration of each link inside a Q3P node. E.g.:

[link.alice_to_bob]
id = alice_to_bob
db = file:///var/lib/q3p/alice_to_bob.db
master = true
listen.uri = tcp://127.0.0.1:10011
peer.uri = tcp://127.0.0.1:10021
#secret = "Place here the shared secret to connect to the peer instance" 
secret_file = /var/q3p/alice_to_bob.secret
ipsec = 172.0.0.1 172.0.0.2 blowfish-448