> Si clonaste sin usar `--recurse-submodules`, los submódulos pueden actualizarse ejecutando `git submodule update --init` desde dentro de la carpeta fuente.

Aquí tienes una lista de dependencias que necesitas para compilar el proyecto (lee más abajo para más detalles sobre la instalación):```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

INPUT:```bash
./src/Tools/SiteAgentRunner/SiteAgentRunner -p 8001 &
./src/Drivers/DummyQKDDriver/DummyQKDDriver -r localhost:8001 -b

lo que debería producir algo similar a esto por defecto, si *SiteAgentRunner* y *DummyQKDDriver* se lanzaran sin especificar un argumento de archivo de cadena JSON de configuración:```json
{
 "url": "<hostname>:8000",
 "devices": [
  {
   "config": {
    "id": "dummyqkd__0__16_alice",
    "kind": "dummyqkd"
   },
   "controlAddress": "<hostname>:34219"
  }
 ]
}

- Ahora, la conexión se puede realizar llamando a:```bash
./src/Tools/SiteAgentCtl/SiteAgentCtl -c localhost:8000 -j localhost:8001

El enlace puede detenerse con el comando unjoin:```bash
./src/Tools/SiteAgentCtl/SiteAgentCtl -c localhost:8000 -u localhost:8001

- Ahora inicia el lado de Alice de la VPN, definiendo el túnel a crear. Se abrirán dos puertos, uno para cada lado en 9000 y 9001, cualquier cosa que entre por estos puertos será encriptada, transferida al otro lado, descifrada y producida en el otro puerto.```
./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

y uno en el otro:```
nc localhost 9001

### Ubuntu 18.04+

Puedes instalar paquetes binarios desde [Gitlab](https://gitlab.com/QComms/cqptoolkit/-/jobs/artifacts/master/download?job=package%3Adeb). Extrae el archivo zip e instala las herramientas con `dpkg`, se quejará de dependencias faltantes pero no te preocupes, la segunda línea las solucionará.```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

De lo contrario, compilar desde el código fuente requiere que instales las dependencias listadas en `setup/setupbuild.sh`; actualmente funciona para Ubuntu y Arch Linux.

Clona el código fuente desde [gitlab](https://gitlab.com/QComms/cqptoolkit.git) con [git][] y compílalo con [CMake][] y [gnu make](https://www.gnu.org/software/make/):
La opción `--recurse-submodules` añade los extras opcionales: el acceso a algunos de ellos está restringido a la UoB y sus socios; la compilación funcionará sin ellos.```bash
git clone --recurse-submodules https://gitlab.com/QComms/cqptoolkit.git

Ahora, puedes ir a tu repositorio local e instalar las dependencias con el script (quizás sea necesario cambiar los permisos del archivo):```bash
cd cqptoolkit/setup
./setupbuild.sh

La compilación utiliza [CMake][] para generar archivos make/soluciones/etc para muchas plataformas diferentes y se invoca desde una carpeta de compilación vacía que contendrá todos los archivos de salida. Las compilaciones de depuración producen paquetes con el sufijo 'D'.
La compilación se puede controlar pasando opciones a cmake, por ejemplo `-DBUILD_TESTING=OFF`. Ejecute cmake con las opciones `-LH` para listar los interruptores disponibles.

Para hacer cambios y desarrollar la biblioteca, se recomienda instalar [QT Creator](http://doc.qt.io/qtcreator/) y abrir el proyecto [seleccionando el archivo CMakeLists.txt](https://codeyarns.com/2016/01/26/how-to-import-cmake-project-in-qt-creator/). Es aconsejable usar compilaciones paralelas yendo a Projects->Build Steps-> Details y agregando `-j<número>` a los parámetros de la herramienta, consulte [so](https://stackoverflow.com/questions/8860712/setting-default-make-options-for-qt-creator).
Una vez compilados, los archivos, por defecto, están al mismo nivel que la carpeta del proyecto llamada `build-<nombre del proyecto>-<plataforma>-<destino>`.

> **Nota sobre protobuf + QT en Ubuntu**
> La biblioteca `qt5-gtk-platformtheme` está enlazada contra una versión antigua de protobuf que impedirá que nuestros programas QT se ejecuten.
> Esta dependencia opcional se puede eliminar con `apt-get remove qt5-gtk-platformtheme`

## Explorando la Biblioteca

    @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

A continuación se muestra un diagrama de flujo para ayudarle a encontrar el área relevante para usted, ya que el proyecto abarca muchos aspectos diferentes de QKD y la gestión de claves; los colaboradores son bienvenidos para impulsar este proyecto a ser más especializado.
QKD requiere alguna forma de comunicación [no clonable](https://en.wikipedia.org/wiki/No-cloning_theorem), usualmente usando fotones individuales a través de un cable de fibra óptica. Pueden operar punto a punto o como uno-a-muchos pero inherentemente tienen una ubicación física (donde termina la fibra); ¡no pueden virtualizarse! El punto en el que se transmite o detecta el fotón es el límite del sistema seguro, casi como el [firewall](https://en.wikipedia.org/wiki/Firewall_(computing)) de una red. Una vez que los fotones indivisibles se han convertido en una cadena de bits para formar una [clave simétrica](https://en.wikipedia.org/wiki/Key_(cryptography)), se aplican las reglas estándar de seguridad informática como autenticación, control de acceso, etc. La diferencia es que una vez que se han producido esas claves, cada uno de los dispositivos QKD tiene un número que [nadie más conoce](https://en.wikipedia.org/wiki/Shared_secret) [probado por la ciencia](https://arxiv.org/pdf/quant-ph/0003004.pdf).

La naturaleza de este efecto de "firewall" es que los sistemas que controlan los dispositivos QKD deben ser seguros y considerados de confianza - también llamado "nodo de confianza" - dónde y cómo se traza la línea puede variar desde guardias armados hasta simplemente [cerrar la puerta de la sala de servidores](https://www.youtube.com/watch?v=rnmcRTnTNC8).

Si no puede ver el diagrama a continuación, vaya a la [documentación en línea](https://qcomms.gitlab.io/cqptoolkit/), también se puede compilar con el objetivo `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


### Ejecutando DummyQKDDriver <a name="RunningDummyQKDDriver" />

Esta sección es solo un comentario sobre la funcionalidad útil de DummyQKDDriver para simular la salida de un dispositivo QKD. Por favor, consulte la siguiente sección para ver un ejemplo guiado de cómo configurar un enlace simple con ellos.
Como con la mayoría de los programas, pasarle `-h` mostrará las opciones disponibles. El DummyQKDDriver ejecuta un conjunto estándar de pasos de postprocesamiento en detecciones de fotones simuladas utilizando la clase cqp::DummyQKD. Es necesario que se ejecuten dos instancias del programa, una para Alice y otra para Bob.

Ejecute Bob primero en el puerto 8000 llamando a:```bash
DummyQKDDriver -b -k 0.0.0.0:8000

Si funcionó, obtendrás una avalancha de mensajes de error como este: `ERROR: OnKeyGeneration No listener for generated key`. Esto se debe a que, aunque ejecutar el sistema de esta manera es agradable para verlo hacer algo, no es muy útil; no hay un lugar donde poner la clave generada. Los controladores están diseñados para ser utilizados por algo.
El proyecto tiene un sistema para gestionar las claves llamado [Site Agents](#SiteAgents) o puedes hablar directamente con los controladores usando la [interfaz IDevice](#IDeviceInterface)

### Configuring the Site Agents <a name="SiteAgents" />

Los Site agents, controladores y túneles VPN deben ser parametrizados para cada nodo de la red con archivos de cadenas JSON, ya que el comando predeterminado sin argumentos no especifica todos los campos necesarios por defecto y solo funciona para pruebas en la misma máquina local.

Los Site agents pueden ejecutarse con SiteAgentRunner; podemos ejecutar dos sitios con:```bash
SiteAgentRunner -c site-a.json

con cada archivo JSON indicando apropiadamente un puerto diferente para Alice y Bob (ej. 9000/9001). La cadena JSON se ve así:```json
		{
		    "name":"",
		    "id":"",
		    "netManUri":"",
		    "bindAddress":"0.0.0.0",
		    "listenPort":9000,
		    "connectionAddress":"",
		    "credentials": {},
		    "useAutoDiscover":false,
		    "backingStoreUrl":"",
		    "fallbackKey":""
		}

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

> El campo de dirección de control puede ser 0.0.0.0:0 si no hay firewall que gestionar. Si es así, se debe indicar la IP real del host y elegir un puerto apropiado que el firewall no bloquee.

Nada sucederá todavía porque los agentes del sitio no saben qué hacer con estos dispositivos. Podemos instruirlos para que comiencen a generar claves (-b como begin) enviando el comando cqp::ISiteAgent::StartNode:```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"}}]}'

> Nota: se usa `-e` en lugar de `-b` para *finalizar* el enlace en lugar de *iniciarlo*.

Se pueden lograr configuraciones más complejas implementando usted mismo la interfaz cqp::remote::INetworkManager para emitir los comandos. La retroalimentación de los dispositivos llega a través de la interfaz cqp::remote::IReporting en el mismo socket para que pueda reaccionar a los cambios en el sistema. [Aquí](#Reporting) puede ver cómo extraer información de la interfaz de reportes con la herramienta StatsDump.

### Creación de controladores <a name="CreatingDrivers" />

La aplicación controladora es un puente entre las interfaces internas del dispositivo (cqp::IQKDDevice) y la interfaz externa cqp::remote::IDevice. La clase cqp::RemoteQKDDevice maneja la mayor parte del trabajo por usted; la aplicación debe manejar la configuración y creación del dispositivo.

El trabajo real consiste en crear un controlador para configurar el dispositivo y leer la clave. Si su dispositivo solo produce detecciones brutas, entonces necesitará configurar una [tubería de procesamiento](#ProcessingPipelines) como cqp::DummyQKD o cqp::PhotonDetectorMk1 y cqp::LEDAliceMk1. Si su dispositivo genera claves listas para usar como el cqp::Clavis3Device, necesita leerlas y publicarlas a través de la interfaz cqp::IKeyCallback (use cqp::KeyPublisher).

Ambos enfoques requieren una forma de gestión de sesiones, proporcionada por cqp::session::SessionController y cqp::session::AliceSessionController; estos implementan las interfaces cqp::ISessionController y cqp::remote::ISession y son utilizados por cqp::RemoteQKDDevice para iniciar y detener el dispositivo y su par. Normalmente esto es todo lo que se necesita, pero en algunas situaciones es necesario especializarlos para satisfacer los requisitos del dispositivo.

    @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

### Registro de un controlador <a name="Registering" />

En el momento de redactar este documento, todos los controladores se pueden registrar con un agente de sitio utilizando el modificador `-r`. Esto hace que cqp::RemoteQKDDevice llame a cqp::remote::ISiteAgent::RegisterDevice en cqp::SiteAgent, que luego usará la interfaz cqp::remote::ISession para iniciar/detener el dispositivo.

### Interfaz IDevice <a name="IDeviceInterface" />

Esta interfaz permite un acceso más directo al dispositivo que a través de los agentes de sitio. Las claves generadas por el dispositivo se devuelven inmediatamente a la persona que llama. Primero llame a cqp::remote::IDevice::WaitForSession, luego a cqp::remote::IDevice::RunSession. Llame a cqp::remote::IDevice::EndSession para detener la generación de claves.

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

Los [HSM](https://en.wikipedia.org/wiki/Hardware_security_module) son dispositivos de almacenamiento que actúan como bóvedas digitales físicamente seguras. Existe una interfaz estándar para ellos llamada [PKCS#11](https://en.wikipedia.org/wiki/PKCS_11). Cada fabricante tiene sus propias interfaces y el soporte para PKCS#11 es irregular, sin embargo, existe una implementación de software que usamos como referencia llamada [SoftHSM2](https://www.opendnssec.org/softhsm/). La clase cqp::keygen::HSMStore proporciona una implementación que vincula el cqp::SiteAgent con la interfaz cqp::IBackingStore.

### Interfaz IKey <a name="IKeyInterface" />

Los sitios proporcionan claves para muchos puntos finales (los almacenes de claves disponibles se pueden obtener llamando a cqp::remote::IKey::GetKeyStores); se pueden solicitar utilizando la interfaz cqp::remote::IKey. Una vez que se ha solicitado una nueva clave, el otro lado solo puede recuperarla como una clave existente; esto evita conflictos y mal uso de las claves.

### Cifrado <a name="Encryption" />

Se pueden encontrar más detalles sobre implementaciones específicas en:
* [Tunnels](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/Tunnels.md)

### Reportes <a name="Reporting" />

Los cambios en los valores del sistema se publican externamente a través de la interfaz cqp::remote::IReporting e internamente con la clase cqp::stats::Stat.
Puede registrarse para todas las estadísticas llamando a cqp::remote::IReporting::GetStatistics con el campo cqp::remote::ReportingFilter::listIsExclude establecido en `true` o se pueden especificar filtros específicos.

### Tuberías de procesamiento <a name="ProcessingPipelines" />

El protocolo QKD [BB84](https://en.wikipedia.org/wiki/BB84) estándar requiere pasos de posprocesamiento para convertir las detecciones brutas en claves utilizables.

- **Alineación** Encontrar el inicio y el final de la transmisión real.
    + Ajustes por diferencias de tiempo/deriva, etc.
    + Compensación de diferencias de fase u otras entre el transmisor y el receptor, etc.
- **Cribado** Descartar detecciones no válidas
- **Corrección de errores** Corregir detecciones incorrectas - sin revelar los valores
- **Amplificación de privacidad** Hashing de la clave para que cualquier bit revelado sea inútil

Se puede ver un ejemplo de una tubería de procesamiento en cqp::DummyQKD::ProcessingChain.

## Compilación

Las compilaciones son gestionadas por el [sistema de integración continua](https://about.gitlab.com/product/continuous-integration/) de gitlab definido en el archivo `.gitlab-ci.yml`.

Las imágenes docker se pueden compilar manualmente ejecutando `setup/makeDocker.sh`.

### Windows

Esto es un trabajo en curso.
Esta configuración se ha probado en Windows 10 y Windows Server 2016 con Visual Studio 15 (2016).
Se admiten las siguientes configuraciones

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

#### IDE

- [Visual Studio 2016][]
    + Ejecute el script [InstallVcPkg.bat](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/build/vs2017_x64/InstallVcPkg.bat) una vez para instalar vcpkg en C:\vcpkg
    + Ejecute el script [SetupMSBuild.bat](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/build/vs2017_x64/SetupMSBuild.bat)
    + Abra la solución [cqp.sln](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/build/vs2017_x64/cqp.sln)
    + Seleccione Compilación -> Solución
- [QT Creator for windows][]
    + QT Creator puede usar tanto el compilador nativo de Microsoft como MSYS2. Instale MSYS2 por separado, no necesita instalar el compilador MinGW que viene con el instalador de QTCreator. O instale el [SDK de Windows 10][]
    + En el menú de componentes, seleccione los componentes para el compilador que esté usando. Por ejemplo, msvc2017
    + Usando "Abrir proyecto", seleccione el archivo `CMakeLists.txt` en la raíz del árbol de fuente.
- [MSYS2][] y [Codeblocks][]
    + Instale el paquete [MSYS2][].
    + Ejecute el script [installMSYS2Dependencies.bat](https://gitlab.com/qcomms/cqptoolkit/-/blob/master/build/installMSYS2Dependencies.bat)
    + En Configuración -> Depurador -> "Crear configuración" llamada "MSYS2 GDB"
        - Cambie el depurador para que apunte a gdb.exe (ej. C:\\msys64\\mingw64\\bin\\gdb.exe)
    + En Configuración -> Compilador
        + Copie la configuración del compilador GCC, llámela "GCC - Old"
        + Cambie el directorio de instalación de la cadena de herramientas a la ubicación de instalación mingw64 de MSYS2 (ej. C:\\msys64\\mingw64)
        + En cada uno de los campos bajo "Program Files" excepto el programa "make", elimine el prefijo `mingw32-`.
        + En el campo make, agregue el modificador -j para permitir compilación multinúcleo: `mingw32-make.exe -j`
        + Seleccione el depurador "MSYS2 GDB" creado anteriormente
        + Si prefiere una salida legible del compilador, en "Otras configuraciones" -> "Registro del compilador" seleccione "Descripción de tarea"
    + En el directorio de compilación de CodeBlock (\\build\\CodeBlocks)
    + Ejecute el archivo `SetupCodeBlocks-MSYS2.bat`
    + Abra el archivo de proyecto "CQP.cbp" de CodeBlocks.

Si su archivo de proyecto tiene una estructura de carpetas profunda (esto es un error), se puede mejorar haciendo clic derecho en el espacio de trabajo y:

- Desmarcando "Mostrar carpetas como en el disco"
- Marcando "Ocultar nombre de carpeta"

## Cómo citar este software```
@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}
}