Example: Local Demo with simulator

Once you've installed the QKD R10, you might want to run a little demo locally.

After Installation, either been done via sudo apt-get install qkd or after a successful build with make package && sudo dpkg --install qkd*.deb, you have the AIT QKD R10 installed.

Add user to qkd group

Since the configuration files of the AIT QKD R10 can hold potentially sensitive information, it is necessary to add the user operating a QKD pipeline to the newly installed qkd user group on the system. This is achieved by (please substitute USER-LOGIN with the corresponding user):

$ sudo usermod -G qkd -a USER-LOGIN

This action may require a user logout/login to be become effective. You can check your group membership by

$ id

Once your user login is part of the qkd group you may read essential and potentially sensitive QKD configuration settings stored in /etc.

Prepare for QKD pipeline outputs

You may want to collect debug information about the running QKD post processing pipeline. Therefore we recommend a dedicated log folder where all modules may place their log files. This step is optional.

$ mkdir log

Launch the QKD pipeline as Alice

The QKD R10 ships with installed working configurations for Alice and Bob on the localhost ( in /etc/qkd. You can now start the Alice pipeline by starting the qkd-pipeline tool pointing to the pipeline configuration file. Note, when you did not created a log folder before, you should omit the '--log FOLDER' option.

$ qkd-pipeline --log log start /etc/qkd/pipeline-alice.xml
modules found: 7
starting modules ...
started module: /usr/bin/qkd-bb84 DBus:
started module: /usr/bin/qkd-cascade DBus:
started module: /usr/bin/qkd-confirmation DBus:
started module: /usr/bin/qkd-buffer DBus:
started module: /usr/bin/qkd-privacy-amplification DBus:
started module: /usr/bin/qkd-statistics DBus:
started module: /usr/bin/qkd-tee DBus:
pipeline entry point: ipc:///tmp/qkd/
pipeline exit point: ipc:///tmp/qkd/default.alice.out
starting modules...
starting modules ... done

This output states the modules which have been started along the full path to the started module's executable and it's DBus service name. Note also the pipeline entry point and the pipeline exit point. Both are IPC (UNIX Domain Sockets) connection points where key data is pumped into the pipeline and from where it is fetched after the data has passed through the pipeline.

The input configuration file of the qkd-pipeline tool is a XML file with easy-to-read syntax:

<pipeline name="default" autoconnect="true" pipein="ipc:///tmp/qkd/" pipeout="ipc:///tmp/qkd/default.alice.out">

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

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

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

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

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

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

    <module path="qkd-tee" >
        <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" />


This file lists all modules of the pipeline and how they are started. If autoconnect is set to true, then this modules are also interconnected on the local machine in order they are specified in this configuration file.

Launch the QKD pipeline as Bob

Likewise you can now start the same pipeline for Bob. Hence the different configuration file.

$ qkd-pipeline --log log start /etc/qkd/pipeline-bob.xml
modules found: 7
starting modules ...
started module: /usr/bin/qkd-bb84 DBus:
started module: /usr/bin/qkd-cascade DBus:
started module: /usr/bin/qkd-confirmation DBus:
started module: /usr/bin/qkd-buffer DBus:
started module: /usr/bin/qkd-privacy-amplification DBus:
started module: /usr/bin/qkd-statistics DBus:
started module: /usr/bin/qkd-tee DBus:
pipeline entry point: ipc:///tmp/qkd/
pipeline exit point: ipc:///tmp/qkd/default.bob.out
starting modules...
starting modules ... done

Start a QKD "source"

In lack of proper physical devices you can now launch our AIT QKD R10 simulator. This is a GUI driven application, which simulates quantum events on paired devices.

With this application you can adjust various properties of the quantum channel. This set of properties may be stored and later loaded back in again for work. The AIT QKD R10 ships with a pre-configured set of properties located at /usr/share/qkd-simulate.

After loading please check, if within the "Output Event Table Options" the out stream of the simulator is set to "Pipe" and holds the same for the pipeline entry point for Alice and Bob. If all went well, then this ought to be "ipc:///tmp/qkd/" for Alice and "ipc:///tmp/qkd/" for Bob.

Clicking now the "Start" button generates quantum events which are passed on to the QKD pipeline.

Observe the AIT QKD pipeline

At any time you can observe current properties of the AIT QKD post processing modules running in the background. You may use any D-Bus aware observer like d-feet or the command line programs qdbus or more flexible busctl (the later works only if your Linux distribution has a recent systemd installation).

If you use these tools be aware that the AIT QKD R10 creates its own system D-Bus to isolate the IPC communication from the rest of the system. The address of this QKD D-Bus is set by the /etc/dbus-1/qkd.conf file and normally points to unix:path=/run/dbus/qkd_dbus_socket. This value is also stored in the user's environment variable QKD_DBUS_SESSION_ADDRESS:

$ env | grep QKD

Alternatively you can fire up the qkd-view command line tool of the AIT QKD R10 (which is much easier to use anyway). A typical output (truncated to the right for ease of reading) shows:

$ qkd-view -s
QKD system investigation results from Fri Jun 26 12:48:14 2015
QKD system investigation took 13ms
type       id                       dbus                                                pipeline    process_id    type    type_name                start_time...    
module:    bb84                                default     10019         1       sifting                  1435314294...
module:    bb84                                 default     9937          1       sifting                  1435314192...
module:    buffer                            default     10026         7       other                    1435314294...
module:    buffer                             default     9943          7       other                    1435314193...
module:    cascade                          default     10021         3       error correction         1435314294...
module:    cascade                           default     9939          3       error correction         1435314193...
module:    confirmation                default     10024         4       confirmation             1435314294...
module:    confirmation                 default     9941          4       confirmation             1435314193...
module:    privacy-amplification    default     10030         5       privacy amplification    1435314294...
module:    privacy-amplification     default     9945          5       privacy amplification    1435314193...
module:    statistics                    default     10034         7       other                    1435314295...
module:    statistics                     default     9947          7       other                    1435314193...
module:    tee                                  default     10037         7       other                    1435314295...
module:    tee                                   default     9949          7       other                    1435314194...

Note: this tool shows all QKD R10 related modules running on the current machine, regardless of which role ("alice" or "bob") or to which pipeline they belong.

Using other typical UNIX tools like awk and grep you may easily find the data of interest.

Collect the final data

When you look into the folder from which you have started the pipelines then you should find 4 new files:

$ ls -l
total 284
drwxrwxr-x 2 dyle dyle   4096 Jun 26 12:24 log
-rw-rw-r-- 1 dyle dyle 157652 Jun 26 12:48 qkd-keys.alice
-rw-rw-r-- 1 dyle dyle   5064 Jun 26 12:48 qkd-keys.alice.statistics
-rw-rw-r-- 1 dyle dyle 111302 Jun 26 12:41 qkd-keys.bob
-rw-rw-r-- 1 dyle dyle   3614 Jun 26 12:41 qkd-keys.bob.statistics

These files (besides the log folder we've created before) hold the resulted, re-conciliated key material which has been created by the qkd-simulator in the first place and some statistics to this. These files are the result of two modules in the pipeline: qkd-tee forking the bypassing keystream into a file (e.g. "qkd-keys.alice") and qkd-statistics which writes various statistical data of the bypassing keystream into a file (e.g. "qkd-keys.alice.statistics").

Examine the resulted keys

The generated key files "qkd-keys.alice" and "qkd-keys.bob" are raw binary files holding the key data. The AIT QKD R10 ships with the qkd-key-dump tool which lets you print the content of such files human readable on stdout:

$ qkd-key-dump -s qkd-keys.alice | head
key        bits     disclosed bits error rate state         crc
0000000001 00032464 00025348       0.0506     amplified     de78b193
0000000005 00038688 00030837       0.0511     amplified     b2e29e65
0000000010 00031744 00025720       0.0515     amplified     3b9db354
0000000014 00037648 00029232       0.0508     amplified     3bd0f3b8
0000000019 00038920 00028449       0.0491     amplified     1902e0a0
0000000024 00039872 00030014       0.0500     amplified     2882cf82
0000000029 00038544 00028572       0.0494     amplified     3b20336b
0000000034 00036088 00027796       0.0505     amplified     dc79c4fb
0000000039 00036528 00027658       0.0505     amplified     fbcd8e55

Note: without the '-s' or '--short' option you also get the full key content.

The output of qkd-statistics is human readable anyway. So you can directly view the properties of the pipeline:

$ head qkd-keys.alice.statistics
timestamp         id         bits       qber   disclosed bits  state         sh.eff. total keys   total bits         keys/second  bps
000000001047728ms 0000000001 0000032464 0.0506 0000025348      amplified     2.70059 000000000001 000000000000032464            1          32464
000000001049838ms 0000000005 0000038688 0.0511 0000030837      amplified     2.73811 000000000002 000000000000071152            1          38688
000000001051513ms 0000000010 0000031744 0.0515 0000025720      amplified     2.76842 000000000003 000000000000102896            1          31744
000000001053528ms 0000000014 0000037648 0.0508 0000029232      amplified     2.68076 000000000004 000000000000140544            1          37648
000000001055588ms 0000000019 0000038920 0.0491 0000028449      amplified     2.58840 000000000005 000000000000179464            1          38920
000000001057689ms 0000000024 0000039872 0.0500 0000030014      amplified     2.62901 000000000006 000000000000219336            1          39872
000000001059657ms 0000000029 0000038544 0.0494 0000028572      amplified     2.60995 000000000007 000000000000257880            1          38544
000000001061514ms 0000000034 0000036088 0.0505 0000027796      amplified     2.66786 000000000008 000000000000293968            1          36088
000000001063437ms 0000000039 0000036528 0.0505 0000027658      amplified     2.62605 000000000009 000000000000330496            1          36528

Check the logs

If you have specified a log folder when running the qkd-pipeline command then you'll probable have some files inside the log folder you specified:

$ ls -1 log/

This is optional and holds the debug information of each module in the pipeline. The content of the log differs from module to module, since these module all have different goals and processing. A sample output from the qkd-cascade may look like this:

$ head -n 40 log/qkd-cascade.alice.log
loading configuration from: file:///etc/qkd/pipeline-default.conf
connecting to DBus:unix:abstract=/tmp/dbus-Lv8F10umwZ,guid=ee70b49064f376580f559a45558cf662
using QKD D-Bus at unix:path=/run/dbus/qkd_bus_socket
connected to DBus:unix:abstract=/tmp/dbus-Lv8F10umwZ,guid=ee70b49064f376580f559a45558cf662 as "" 
module registered on DBus as /Module
run module: in='ipc:///tmp/qkd/' out='ipc:///tmp/qkd/' listen='' peer='tcp://'
input pipe stream set to 'ipc:///tmp/qkd/'
output pipe stream set to 'ipc:///tmp/qkd/'
module setup done - entering ready state
current module config:
              role: alice
       url_pipe_in: ipc:///tmp/qkd/
      url_pipe_out: ipc:///tmp/qkd/
          url_peer: tcp://
          pipeline: default
  synchronize_keys: false
   synchronize_ttl: 10
   terminate_after: 0
   timeout_network: 2500
      timeout_pipe: 2500
working on incoming keys started
key-PULL [000000001047092ms] id: 0000000001 bits: 0000020192 err: 0.0000 dis: 0000000000 crc: a6b80a74 state: sifted
connected to 'tcp://'
cascade done: error rate = 0.0525951, disclosed = 6513/20192, efficiency = 1.08487
key-PUSH [000000001047214ms] id: 0000000001 bits: 0000020192 err: 0.0526 dis: 0000006513 crc: a6b80a74 state: corrected     dur: 000122292305 ns (000122 ms)
key-PULL [000000001047507ms] id: 0000000002 bits: 0000020432 err: 0.0000 dis: 0000000000 crc: faf1d05c state: sifted
cascade done: error rate = 0.0517815, disclosed = 6486/20432, efficiency = 1.08004
key-PUSH [000000001047612ms] id: 0000000002 bits: 0000020432 err: 0.0518 dis: 0000006486 crc: faf1d05c state: corrected     dur: 000105223922 ns (000105 ms)
key-PULL [000000001047932ms] id: 0000000003 bits: 0000020480 err: 0.0000 dis: 0000000000 crc: 5937b37c state: sifted
cascade done: error rate = 0.0503418, disclosed = 6214/20480, efficiency = 1.05409
key-PUSH [000000001048077ms] id: 0000000003 bits: 0000020480 err: 0.0503 dis: 0000006214 crc: 5937b37c state: corrected     dur: 000145950101 ns (000146 ms)
key-PULL [000000001048381ms] id: 0000000004 bits: 0000020368 err: 0.0000 dis: 0000000000 crc: a0691699 state: sifted
cascade done: error rate = 0.0478692, disclosed = 6135/20368, efficiency = 1.08631
key-PUSH [000000001048497ms] id: 0000000004 bits: 0000020368 err: 0.0479 dis: 0000006135 crc: a0691699 state: corrected     dur: 000117001266 ns (000117 ms)
key-PULL [000000001048723ms] id: 0000000005 bits: 0000016424 err: 0.0000 dis: 0000000000 crc: e224ccd1 state: sifted
cascade done: error rate = 0.0472479, disclosed = 4766/16424, efficiency = 1.0568
key-PUSH [000000001048821ms] id: 0000000005 bits: 0000016424 err: 0.0472 dis: 0000004766 crc: e224ccd1 state: corrected     dur: 000097464430 ns (000097 ms)