Installation¶

The installation process is done through a Makefile that brings up services in a docker-compose yml file. These are split into intialization and normal services. The initialization parts are [1],

certauth

vault

vault init phase 1

certauth csr

vault init phase 2

vault client auth

qkd [2]

watcher

notifier

Once initialized on both sides, the normal running containers are

rest

vault

traefik

unsealer

The functions of each service/container is documented here for information only and is subject to change in future release

certauth¶

Initialized by certauth Docker service, running certs and install Makefile targets.

Create Local Root Certificate Authority (CA)

Private Key (EC secp384r1)

Public Key (X.509 Certificate)

Create Local Intermediate CA

Private Key (EC secp384r1)

Generate Certificate Signing Request (CSR) - signed by root CA

Public Key (X.509 Certificate) + Certificate Chain

Create Vault Server Key/Certificate

Private Key (EC secp384r1)

Generate CSR - signed by Intermediate CA

Public Key (X.509 Certificate) + Certificate Chain

Create Vault Initialization Client Key/Certificate

Private Key (EC secp384r1)

Generate CSR - signed by Intermediate CA

Public Key (X.509 Certificate) + Certificate Chain

Create PKCS#12 (.p12) file storing certificate chain and private key

vault¶

Creates local vault Docker instance from Hashicorp’s official image, listening on port 8200. Mutual TLS authentication using vault client and server certificates generated by certauth.

This instance is shutdown upon completion of Guardian initialization. The service is eventually restarted, but connected to a private network accessible by the REST service.

vault init phase 1¶

Initialized by vault_init Docker service, running vault_init.py --first.

Create Python hvac client

Start connection between Vault server instance and hvac client

Initialize Vault instance

Generate Shamir secret shares and initial root token

Unseal Vault instance

Use secret shares to decrypt/unseal the local Vault instance

Instance will remain unsealed until stop/restart of service or active call to seal

Authenticate to Vault instance using root token

Enable auditing for Vault instance; written out to audit log

Enable authentication method that uses TLS certificates

Enable intermediate CA functionality

Enable a PKI secrets engine that will become an Intermediate CA to more conveniently issue TLS certificates

Write out local Vault instance CSR to be signed by Root CA

certauth csr¶

Initialized by certauth Docker service, running csr Makefile targets.

Sign Vault instance CSR with Root CA to create Vault Intermediate CA certificate

vault init phase 2¶

Initialized by vault_init Docker service, running vault_init.py --second.

Create Python hvac client

Verify Vault instance is initialized

Unseal Vault instance

Authenticate to Vault instance using root token

Ingest Root CA signed certificate to become Intermediate CA

Create Intermediate CA certificate issuer Access Control List (ACL) policy

Enable Key Value version2 secrets engine for storing QKD key information

Create watcher service ACL policy

Create rest service ACL policy

Generate watcher client private key/certificate and write to Docker volume

Generate rest client private key/certificate and write to Docker volume

Generate local SAE client private key/certificate + .p12 and write to Docker volume

vault client auth¶

Initialized by vault_client_auth Docker service.

This is a workaround that allows for injecting client certificates into the Vault instance cert authentication store. Ideally, this would be done with an hvac Python client in vault_init but at the time of this writing, this functionality did not exist. Therefore, a shell script is used instead. [3]

Authenticate to Vault instance using root token

Inject rest and watcher client TLS certificate into cert authentication endpoint

This enables both clients to authenticate to the local Vault instance using their client-side certificate identities

qkd¶

Note

This step is just simulating keys for use with Guardian. This is done to simplify tests without access to proper QKD hardware.

Different commands are run depending on which KME this initialization step is run on.

KME Host 1¶

Initialized by certauth Docker service, running clean and ctest Makefile targets.

Run the esim binary to completion to generate simulated entangled photons and their detection and timetagging (including noise, delays, etc.) output into binary files

Run the chopper and chopper2 binaries to process the timetagged photons for both Alice and Bob – NOTE: this is all happening locally; no transferd process is started

Run the getrate binary on both Alice and Bob’s photon stream to estimate the number of detected photons per second

Run the pfind binary to determine the time offset between Alice and Bob’s detected photon streams

Run the costream binary to sift entangled photons by recovering coincidences between Alice and Bob

Run the splicer binary to recombine information from both parties to get raw keying material

Run the errcd binary to perform the Cascade error correction algorithm along with privacy amplification to generate the final key material

Copy the final keying material to a Docker volume for further processing by other services

KME Host 2: Transfer Keys¶

On this remote side, final epoch files are rsynced over from the KME host 1 and removed upon successful transfer; see transfer_keys.sh.

No qcrypto or qsim binaries are executed

watcher¶

Initialized by watcher Docker service.

Wait for creation of FIFO pipe and (non-blocking) open as the end reader of this pipe

Listen for data on the pipe in the form of notifications when final epoch files are ready for consumption

When a file notification is ready on the pipe, spawn a thread to read the epoch file and send the secrets to local Vault instance KV v2 secrets engine QKEYs endpoint.

Open and read final epoch key file

Parse the raw keying material

Create Vault secret object with Base64 encoded key, HMAC digest of key, number of bytes, and epoch number; write to Vault instance

Add in new epoch number into Vault instance status file to allow consumption by other services

Remove ingested final epoch file

The watcher Docker service can run indefinitely but it is shut down at this stage

notifier¶

Initialized by notifier Docker service.

Create a FIFO pipe for writing notifications to; watcher service should be on the other end waiting

Find all final epoch files in a specific directory

For each final epoch file; send a notification through the pipe

Note

The notifier Docker service will eventually be replaced by qcrypto which opens its own notification pipe to watcher.