> `--recurse-submodules` を使用せずにクローンした場合、ソースフォルダ内で `git submodule update --init` を実行することでサブモジュールを更新できます。

プロジェクトをコンパイルするために必要な依存関係のリストは以下の通りです（インストールの詳細については、さらに下の方をお読みください）：```bash
sudo apt install pkg-config ca-certificates file build-essential cmake ninja-build libusb-1.0-0-dev libcurl4-openssl-dev \
	libcrypto++-dev libcap-dev uuid-dev libssl-dev libsqlite3-dev libprotobuf-dev libgrpc++-dev \
	libssl-dev protobuf-compiler protobuf-compiler-grpc checkinstall
mkdir build-cqptoolkit
cd build-cqptoolkit
cmake -G Ninja ../cqptoolkit && ninja

以下のパッケージが必要です:

- [Python3](https://www.python.org/downloads/release/python-397/) - Python インタプリタ、YAML と Jinja2 の組み込みサポート
- [rsync](https://rsync.samba.org/) - リモートのファイルとフォルダの同期
- [aria2c](https://aria2.github.io/) - 高速ダウンロードユーティリティ
- [fzf](https://github.com/junegunn/fzf) - コマンドラインのあいまいファインダー
- [md5sum](http://www.microbrew.org/tools/md5sum/)

これらは任意ですが推奨します:

- [rofi](https://github.com/davatorium/rofi) - アプリケーションランチャー、ウィンドウスイッチャー、および dmenu 代替
- [tmux](https://github.com/tmux/tmux) - ターミナルマルチプレクサ
- [megatools](https://megatools.megous.com/) - Mega 向けコマンドラインクライアントアプリケーション
- [gallery-dl](https://github.com/mikf/gallery-dl) - イメージギャラリーやコレクションをダウンロードするためのコマンドラインプログラム

すべての機能を利用するには、上記のすべてのパッケージが必要です。```bash
./src/Tools/SiteAgentRunner/SiteAgentRunner -p 8001 &
./src/Drivers/DummyQKDDriver/DummyQKDDriver -r localhost:8001 -b

これにより、デフォルトでは、*SiteAgentRunner* と *DummyQKDDriver* が設定JSON文字列ファイル引数を指定せずに起動された場合、これに似たものが生成されるはずです：```json
{
 "url": "<hostname>:8000",
 "devices": [
  {
   "config": {
    "id": "dummyqkd__0__16_alice",
    "kind": "dummyqkd"
   },
   "controlAddress": "<hostname>:34219"
  }
 ]
}

- これで、呼び出して接続できるようになりました:```bash
./src/Tools/SiteAgentCtl/SiteAgentCtl -c localhost:8000 -j localhost:8001

リンクは unjoin コマンドで停止できます:```bash
./src/Tools/SiteAgentCtl/SiteAgentCtl -c localhost:8000 -u localhost:8001

では、VPNのAlice側を起動し、作成するトンネルを定義します。2つのポートが開かれ、各側に9000と9001が割り当てられます。これらのポートに入力されたものはすべて暗号化され、相手側に転送され、復号化されて相手側のポートに出力されます。```
./src/Tools/QTunnelServer/QTunnelServer --keystore-url=`hostname`:8000 --remote=localhost:9010 --start-node=tcpsrv://0.0.0.0:9000 --end-node=tcpsrv://0.0.0.0:9001

そしてもう一方には：```
nc localhost 9001

### Ubuntu 18.04+

[Gitlab](https://gitlab.com/QComms/cqptoolkit/-/jobs/artifacts/master/download?job=package%3Adeb) からバイナリパッケージをインストールできます。zip ファイルを展開し、`dpkg` でツールをインストールします。依存関係が不足していると警告されますが、心配はいりません。2行目で修正されます。```bash
sudo dpkg -i setup/*.deb build/gcc/CQP-*-Linux-{Algorithms,Networking,CQPToolkit,KeyManagement,QKDInterfaces,CQPUI,Simulate,Tools,UI,Drivers,IDQDevices}.deb
sudo apt install -fy

そうでなければ、ソースからビルドするには `setup/setupbuild.sh` にリストされた依存関係をインストールする必要があります。現在はUbuntuとArch Linuxで動作します。

ソースを [gitlab](https://gitlab.com/QComms/cqptoolkit.git) から [git][] でクローンし、[CMake][] と [gnu make](https://www.gnu.org/software/make/) でビルドします:
`--recurse-submodules` はオプションのエクストラを追加します。これらの一部へのアクセスはUoBとそのパートナーに制限されていますが、それらがなくてもビルドは動作します。```bash
git clone --recurse-submodules https://gitlab.com/QComms/cqptoolkit.git

これで、ローカルリポジトリに移動し、スクリプトを使って依存関係をインストールできます（ファイルのパーミッションを変更する必要があるかもしれません）：```bash
cd cqptoolkit/setup
./setupbuild.sh

ビルドは[CMake][]を使用して、さまざまなプラットフォーム向けのmakefile/ソリューションなどを生成し、空のビルドフォルダから実行されます。このフォルダにはすべての出力ファイルが含まれます。デバッグビルドでは、パッケージ名の末尾に「D」が付加されます。

ビルドはcmakeにオプションを渡すことで制御できます（例：`-DBUILD_TESTING=OFF`）。利用可能なスイッチを確認するには、cmakeに`-LH`オプションを指定して実行してください。

ライブラリの変更や開発を行う場合は、[QT Creator](http://doc.qt.io/qtcreator/)をインストールし、[CMakeLists.txtファイルを選択](https://codeyarns.com/2016/01/26/how-to-import-cmake-project-in-qt-creator/)してプロジェクトを開くことを推奨します。並列ビルドを使用するには、Projects→Build Steps→Detailsに移動し、ツールパラメータに`-j<数値>`を追加することをお勧めします（[参考](https://stackoverflow.com/questions/8860712/setting-default-make-options-for-qt-creator)）。
デフォルトでは、ビルド後のファイルはプロジェクトフォルダと同じ階層の`build-<プロジェクト名>-<プラットフォーム>-<ターゲット>`というフォルダに格納されます。

> **Ubuntuにおけるprotobuf + QTに関する注意**
> ライブラリ`qt5-gtk-platformtheme`は古いバージョンのprotobufにリンクされており、これによりQTプログラムが実行できなくなります。
> このオプション依存関係は`apt-get remove qt5-gtk-platformtheme`で削除できます。

## ライブラリの探索

    @startuml
        title Applicaiton Overview

        component "QKD Device Drivers" as drv
        interface IDevice as idev
        drv - idev

        component "Device contol and\n Key storage" as sa
        interface IKey as ikey
        sa - ikey
        sa ..> idev

    package "Key consumers" as kc {
        component "Custom VPN" as tun
        component "Custom\nWeb Server" as nginx
        component "HSM bridge" as hsm
    }
    tun ..> ikey
    nginx ..> ikey
    hsm ..> ikey

    package Utilities {
        component "Config/Control GUI" as gui
        component "Simulators/Testing" as sim
        component "Data extraction" as stats

        gui -[hidden]down- sim
        sim -[hidden]down- stats
    }
    @enduml

以下は、このプロジェクトがQKDと鍵管理のさまざまな側面をカバーしているため、あなたに関連する領域を見つけるためのフローチャートです。コントリビューターの皆様がこのプロジェクトをより専門的なものに発展させることを歓迎します。
QKDには、何らかの[非クローン](https://en.wikipedia.org/wiki/No-cloning_theorem)通信が必要であり、通常は光ファイバーケーブルを介して単一光子を使用します。ポイントツーポイントまたは1対多で動作できますが、本質的に物理的な位置（光ファイバーが終端する場所）を持ちます。仮想化することはできません！光子が送信または検出されるポイントが、セキュアシステムの境界であり、ネットワークの[ファイアウォール](https://en.wikipedia.org/wiki/Firewall_(computing))にほぼ相当します。分割不可能な光子がビット列に変換され、[対称鍵](https://en.wikipedia.org/wiki/Key_(cryptography))を形成すると、認証、アクセス制御などの標準的なコンピュータセキュリティのルールが適用されます。違いは、それらの鍵が生成されると、各QKDデバイスには[他の誰も知らない](https://en.wikipedia.org/wiki/Shared_secret)[科学的に証明された](https://arxiv.org/pdf/quant-ph/0003004.pdf)数値が含まれることです。

この「ファイアウォール」効果の性質上、QKDデバイスを制御するシステムは安全であり、信頼できるもの（「トラステッドノード」とも呼ばれる）と見なされる必要があります。どこでどのように線を引くかは、武装した警備員から[サーバールームのドアに鍵をかけるだけ](https://www.youtube.com/watch?v=rnmcRTnTNC8)までさまざまです。

以下の図が表示されない場合は、[オンラインドキュメント](https://qcomms.gitlab.io/cqptoolkit/)を参照してください。`doc`ターゲットでビルドすることもできます。

    @startuml
    title Where to start \n

    skinparam activity {
      StartColor #EF476F
      BarColor #FFD166
      EndColor #EF476F
      BackgroundColor #06D6A0
      BorderColor #118AB2
    }

    start
    if (Do you have a QKD Device?) then (Yes)
        if (Does your QKD device have a driver?) then (No)
            :You will need to [[./index.html#CreatingDrivers create a driver]] which implements the
            <b>IDriver</b> and <b>IReporting</b> interfaces.;
            if (Use the library?) then (Yes)
                :See the [[./index.html#RunningDummyQKDDriver DummyQKDDriver]] for an example.;
            else (No)
            endif
        else (Yes)
        endif
    else (No)
        :Check out how to run the
        [[./index.html#RunningDummyQKDDriver DummyQKDDriver]];
    endif

    if (Do you want keys for multiple
    locations in a network?) then (Yes: Sites)
        :[[./index.html#Registering Register your driver]] with the site agent
        using the <b>ISiteAgent</b> Interface
        Keys can be obtained by using the [[./index.html#IKeyInterface IKey]] interface;

        if(Do you want keys to be stored/persist between restarts?) then (Yes)
            if (Do the keys need to be secured?) then (Yes)
                :Use the [[./index.html#HSMs HSM storage]] options;
                if (Is your HSM supported?) then (No)
                    :Create a driver that implements
                    the <b>IBackingStore</b> interface.
                    Add the driver creation to the
                    <b>BackingStoreFactory</b>;
                else (Yes)
                endif
            else (No)
                : When running SiteAgentRunner,
                use the option ""-b file"" or
                set ""backingStoreUrl"" to
                ""file:///filename.db"";
            endif
        else (No)
        endif
    else (No: Point-to-Point)
        :Use the [[./index.html#IDeviceInterface IDevice interface]] to
        control the driver for your system.
        As keys become available they will
        be sent via the call to <b>WaitForSession</b>.;
    endif

    if (Do you want to use the key for anything?) then (Yes)
        :See the [[./index.html#Encryption encryption section]]
        for an example of using the [[./index.html#IKeyInterface IKey interface]];
    else (No)
    endif
    stop

    @enduml


### DummyQKDDriverの実行 <a name="RunningDummyQKDDriver" />

このセクションでは、QKDデバイスの出力をシミュレートするためのDummyQKDDriverの便利な機能についてコメントします。次のセクションでは、それらを使用してシンプルなリンクをセットアップするためのガイド付き例を参照してください。
ほとんどのプログラムと同様に、`-h`を渡すと利用可能なオプションが表示されます。DummyQKDDriverは、cqp::DummyQKDクラスを使用して、シミュレートされた光子検出に対して一連の標準的な後処理手順を実行します。プログラムの2つのインスタンス（Alice用とBob用）を実行する必要があります。

最初にBobをポート8000で実行します。以下のコマンドを呼び出します:```bash
DummyQKDDriver -b -k 0.0.0.0:8000

正常に動作すると、次のようなエラーメッセージが大量に表示されます: `ERROR: OnKeyGeneration No listener for generated key`。これは、このようにシステムを実行すると動作していることが確認できる点では便利ですが、生成された鍵の格納先がないためあまり有用ではないからです。ドライバーは何かによって使用されるように設計されています。
このプロジェクトには、[Site Agents](#SiteAgents) と呼ばれる鍵を管理するシステムがあるか、[IDevice interface](#IDeviceInterface) を使用してドライバーと直接通信することもできます。

### Site Agents の設定 <a name="SiteAgents" />

Site Agents、ドライバー、VPNトンネルは、ネットワークの各ノードに対してJSON文字列ファイルでパラメータ化する必要があります。デフォルトのコマンド（引数なし）は、必要なすべてのフィールドを既定で指定せず、同じローカルマシンでのテストにのみ機能します。

Site Agents は SiteAgentRunner で実行できます。2つのサイトを実行するには、次のようにします:```bash
SiteAgentRunner -c site-a.json

各JSONファイルがAliceとBobに異なるポート（例：9000/9001）を適切に示している。JSON文字列は次のようになります：```json
		{
		    "name":"",
		    "id":"",
		    "netManUri":"",
		    "bindAddress":"0.0.0.0",
		    "listenPort":9000,
		    "connectionAddress":"",
		    "credentials": {},
		    "useAutoDiscover":false,
		    "backingStoreUrl":"",
		    "fallbackKey":""
		}

そして:```bash
DummyQKDDriver -c driver_config-b.json # run as Bob, register with site agent

> 制御アドレスフィールドは、ファイアウォールが存在しない場合は0.0.0.0:0に設定できます。その場合、ホストの実際のIPを指定し、ファイアウォールがブロックしない適切なポートを選択する必要があります。

まだ何も起こりません。サイトエージェントはこれらのデバイスの扱い方を知らないためです。cqp::ISiteAgent::StartNode コマンドを送信することで、キーの生成を開始するよう指示できます（-b は開始を意味します）。```bash
SiteAgentCtl -c localhost:9000 -b '{"hops":[{"first":{"site":"'hostname':9000","deviceId":"dummyqkd__0__16_alice"},"second":{"site":"'hostname':9001","deviceId":"dummyqkd__0__16_bob"}}]}'

> リンクを*開始*する代わりに*終了*するために、`-b`ではなく`-e`を使用することに注意してください。

より複雑なセットアップは、cqp::remote::INetworkManagerインターフェースを自分で実装してコマンドを発行することで実現できます。デバイスからのフィードバックは、同じソケット上のcqp::remote::IReportingインターフェースを介して送られるため、システムの変更に反応できます。[こちら](#Reporting)で、StatsDumpツールを使用してレポートインターフェースから情報を抽出する方法を確認できます。

### ドライバーの作成 <a name="CreatingDrivers" />

ドライバーアプリケーションは、内部デバイスインターフェース（cqp::IQKDDevice）と外部cqp::remote::IDeviceインターフェースの間のブリッジです。cqp::RemoteQKDDeviceクラスはほとんどの作業を処理しますが、アプリケーションはデバイスの設定と作成を処理する必要があります。

実際の作業は、デバイスをセットアップして鍵を読み取るドライバーを作成することです。デバイスが生の検出値のみを生成する場合は、cqp::DummyQKDやcqp::PhotonDetectorMk1、cqp::LEDAliceMk1のような[処理パイプライン](#ProcessingPipelines)を設定する必要があります。cqp::Clavis3Deviceのように使用可能な鍵を生成するデバイスの場合は、鍵を読み取り、cqp::IKeyCallbackインターフェース（cqp::KeyPublisherを使用）を介して公開する必要があります。

これらの両方のアプローチには、cqp::session::SessionControllerおよびcqp::session::AliceSessionControllerによって提供されるセッション管理の形式が必要です。これらはcqp::ISessionControllerおよびcqp::remote::ISessionインターフェースを実装し、cqp::RemoteQKDDeviceによってデバイスとそのピアを開始および停止するために使用されます。通常はこれで十分ですが、状況によってはデバイスの要件に対応するために特化する必要があります。

    @startuml Readme_Drivers
    title Anatomy of a driver
        package Application {
            namespace cqp #DDDDDD {
                class RemoteQKD
                interface IQKDDevice {
                    GetSessionController()
                }
                class "SessionController" as session
                interface "IDetector::Service" as detServ {
                    StartDetecting()
                    StopDetecting()
                }
                class "Provider<IDetectionEventCallback>" as provider {
                    Attach()
                    Dettach()
                    Emit()
                }

                RemoteQKD .r.> IQKDDevice : uses
                IQKDDevice -r[hidden]-> session
            }
            class Main {
                main()
            }
            class MyDriver
            class Detector

            MyDriver .u.|> cqp.IQKDDevice
            MyDriver o-u-> cqp.session
            Detector .u.|> cqp.detServ
            Detector -u-|> cqp.provider

            Main o-> MyDriver
            MyDriver o-> Detector
            Main o-u-> cqp.RemoteQKD

            note bottom of MyDriver
                In this case the driver is a simple detector
                which produces detection. Post processing detail not shown.
                MyDriver pull together all the parts to run the driver.
            end note

            note bottom of Detector
                The detector controls the device
                and outputs the data using the Provider
            end note
        }
    @enduml

### ドライバーの登録 <a name="Registering" />

執筆時点では、すべてのドライバーは`-r`スイッチを使用してサイトエージェントに登録できます。これにより、cqp::RemoteQKDDeviceはcqp::SiteAgentのcqp::remote::ISiteAgent::RegisterDeviceを呼び出し、その後cqp::remote::ISessionインターフェースを使用してデバイスを開始/停止します。

### IDeviceインターフェース <a name="IDeviceInterface" />

このインターフェースは、サイトエージェントを経由するよりもデバイスへのより直接的なアクセスを可能にします。デバイスによって生成された鍵は、呼び出し元に即座にフィードバックされます。最初にcqp::remote::IDevice::WaitForSessionを呼び出し、次にcqp::remote::IDevice::RunSessionを呼び出します。鍵の生成を停止するにはcqp::remote::IDevice::EndSessionを呼び出します。

### HSM <a name="HSMs" />

[HSM](https://en.wikipedia.org/wiki/Hardware_security_module)は、物理的に安全なデジタル金庫であるストレージデバイスです。これらには[PKCS#11](https://en.wikipedia.org/wiki/PKCS_11)と呼ばれる標準インターフェースがあります。各メーカーは独自のインターフェースを持ち、PKCS#11のサポートは不完全ですが、リファレンスとして使用する[SoftHSM2](https://www.opendnssec.org/softhsm/)というソフトウェア実装があります。cqp::keygen::HSMStoreクラスは、cqp::SiteAgentとcqp::IBackingStoreインターフェースをリンクする実装を提供します。

### IKeyインターフェース <a name="IKeyInterface" />

サイトは多くのエンドポイントに鍵を提供します（利用可能な鍵ストアはcqp::remote::IKey::GetKeyStoresを呼び出すことで取得できます）。鍵はcqp::remote::IKeyインターフェースを使用して要求できます。新しい鍵が要求されると、相手側は既存の鍵としてのみ取得できます。これにより鍵の競合や誤用を防ぎます。

### 暗号化 <a name="Encryption" />

特定の実装の詳細は以下を参照してください:
* [トンネル](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/Tunnels.md)

### レポート <a name="Reporting" />

システム内の値の変更は、外部にはcqp::remote::IReportingインターフェースを介して、内部にはcqp::stats::Statクラスを使用して公開されます。すべての統計情報を登録するには、cqp::remote::ReportingFilter::listIsExcludeフィールドを`true`に設定してcqp::remote::IReporting::GetStatisticsを呼び出すか、特定のフィルターを指定できます。

### 処理パイプライン <a name="ProcessingPipelines" />

標準の[BB84 QKDプロトコル](https://en.wikipedia.org/wiki/BB84)では、生の検出値を使用可能な鍵に変換するために後処理ステップが必要です。

- **アライメント** 実際の送信の開始と終了を見つける
    + タイミングの差異/ドリフトなどを調整する
    + 送信機と受信機間の位相やその他の差異を補償するなど
- **シフティング** 無効な検出値を捨てる
- **誤り訂正** 間違った検出値を訂正する（値を漏洩させずに）
- **秘密増幅** 鍵をハッシュ化して、漏洩したビットを役に立たなくする

処理パイプラインの例は、cqp::DummyQKD::ProcessingChainで確認できます。

## ビルド

ビルドは、`.gitlab-ci.yml`ファイルで定義されたgitlab[継続的インテグレーションシステム](https://about.gitlab.com/product/continuous-integration/)によって管理されています。

Dockerイメージは、`setup/makeDocker.sh`を実行して手動でビルドできます。

### Windows

これは作業中です。このセットアップは、Visual Studio 15（2016）を使用してWindows 10およびWindows Server 2016でテストされています。以下の構成がサポートされています。

| OS        | VS 2017   | QT Creator    | Codeblocks    |
|:----------|-----------|---------------|---------------|
| Linux     |           | gcc           | gcc           |
| Windows   | MSVC      | MSVC / MSYS2  | MSYS2-Mingw   |

#### IDE

- [Visual Studio 2016][]
    + [InstallVcPkg.bat](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/build/vs2017_x64/InstallVcPkg.bat)スクリプトを1回実行して、vcpkgをC:\vcpkgにインストールします。
    + [SetupMSBuild.bat](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/build/vs2017_x64/SetupMSBuild.bat)スクリプトを実行します。
    + [cqp.sln](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/build/vs2017_x64/cqp.sln)ソリューションを開きます。
    + ビルド→ソリューションのビルドを選択します。
- [QT Creator for windows][]
    + QT Creatorは、ネイティブのMicrosoftコンパイラまたはMSYS2のいずれかを使用できます。MSYS2は別途インストールしてください。QT Creatorインストーラに付属のminGWコンパイラをインストールする必要はありません。または[Windows 10 SDK][]をインストールします。
    + コンポーネントメニューで、使用するコンパイラのコンポーネントを選択します。例：msvc2017
    + 「プロジェクトを開く」を使用して、ソースツリーのルートにある`CMakeLists.txt`ファイルを選択します。
- [MSYS2][] and [Codeblocks][]
    + [MSYS2][]パッケージをインストールします。
    + [installMSYS2Dependencies.bat](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/build/installMSYS2Dependencies.bat)スクリプトを実行します。
    + 設定→デバッガーで、「MSYS2 GDB」という名前の「Create config」（設定を作成）をクリックします。
        - デバッガーをgdb.exeの場所に変更します（例：C:\\msys64\\mingw64\\bin\\gdb.exe）。
    + 設定→コンパイラで、
        + GCCコンパイラ設定をコピーし、「GCC - Old」という名前を付けます。
        + ツールチェーンインストールディレクトリをMSYS2のmingw64インストール場所に変更します（例：C:\\msys64\\mingw64）。
        + 「Program Files」以下の各フィールドで、「make」プログラムを除いて、`mingw32-`プレフィックスを削除します。
        + makeフィールドで、マルチコアビルドを可能にするために-jスイッチを追加します：`mingw32-make.exe -j`
        + 先ほど作成した「MSYS2 GDB」デバッガーを選択します。
        + コンパイラの出力を読みやすくしたい場合は、「その他の設定」→「コンパイラログ」を「タスクの説明」に変更します。
    + CodeBlockビルドディレクトリ（\\build\\CodeBlocks）で、
    + `SetupCodeBlocks-MSYS2.bat`ファイルを実行します。
    + 「CQP.cbp」CodeBlocksプロジェクトファイルを開きます。

プロジェクトファイルのフォルダ構造が深すぎる場合（これはバグです）、ワークスペースを右クリックして以下の操作で改善できます：

- 「ディスク上のフォルダとして表示」のチェックを外す
- 「フォルダ名を隠す」にチェックを入れる

## このソフトウェアの引用```
@Manual{,
title = {CQPToolkit: A QKD toolkit library},
author = {{Richard Collins, University of Bristol, UK}},
organization = {University of Bristol},
address = {Bristol, UK},
year = 2018,
url = {https://gitlab.com/QComms}
}