The Reliquary
A setup guide

This guide will help you to get started after you obtain an account key to use the Reliquary. When we said we provide the end-to-end encrypted transport and nothing more we ment it. The guide assumes familiarity with your system and networking.

In this guide we will setup a tunnel between device_1 and device_2 using the reliquary cli tools.

+ Table of contents

+ Prerequisites

To get started you need the following:

Let's start by building sanctum first. The sanctum project will provide several binaries for your system: 

$ git clone https://github.com/jorisvink/sanctum
$ cd sanctum
$ make
$ sudo make install

+ Key Management

Before you setup your network (flock) you need generate Key-Encryption-Keys (KEK). These keys are used for wrapping tunnel shared secrets so that they can be securely distributed by our cathedral to your devices. This also allows you to roll-over keys from time to time.

Using the ambry tool, we will uniformly at random generate KEKs for all your possible devices in a flock (up to 255). It also allows you to generate new shared secrets for all possible tunnels and encrypt them with the correct KEKs automatically. This type of file is a called an ambry bundle and is uploaded to the cathedral.

Each device in your flock will receive exactly one KEK and is identified by its KEK id (eg b5).

Important: We strongly recommend you generate your KEKs and bundles on an air-gapped computer as to prevent them from leaking.

Important: If a KEK for a device is leaked, all traffic from and to that device should be considered comprimised.

The following commands will generate new KEKs under ~/my-infra/kek-data and an ambry bundle for upload under ambry.bundle. 

$ mkdir ~/my-infra
$ cd ~/my-infra
$ ambry generate
$ ambry bundle ambry.bundle

Tip: Generate a new ambry bundle often and upload it so you rollover your shared secrets.

+ Reliquary setup

Setting up reliquary for the first time is done using the reliquary-init script provided by our cli tools. 

$ reliquary-init https://vessel.reliquary.se/v1 <accountkey>

This should be done on each device that will be using reliquary.

+ Creating your first flock

Once you setup reliquary you can create your first flock. A flock is a network of devices that can have tunnels between them. You can create multiple flocks, each flock will need its own unique ambry bundle (and thus unique KEKs).

First, lets create a new flock and upload the ambry bundle we generated earlier for it. By uploading the ambry bundle we allow the automatic shared secret distribution to work between our devices.

How you get your ambry bundle from your air-gapped computer to a computer that is able to upload them is left as an excercise to the reader

Important: We cannot read the wrapped ambry bundle as we do not have any of your KEKs. 

$ reliquary-flock-create
flock 350d5c8b33dfb7db created
$ reliquary-ambry-upload 350d5c8b33dfb7db ~/my-infra/ambry.bundle
ambry uploaded
$

Now that we have setup our flock and uploaded the encrypted shared secrets for tunnels, we can setup a tunnel between two devices. In this guide we will setup a tunnel between device_1 and device_2.

As a key distrubtion point, the cathedral allows you to update your shared secrets for your devices. Note: these are always wrapped with your per-device unique KEK and we cannot see the plaintext keys.

+ Registering device_1 with reliquary

Initialise reliquary on this device as you did earlier (if it was not yet initialised). After that we can register it with our flock we created previously. 

$ reliquary-device-register 350d5c8b33dfb7db
This device has been registered succesfully

Please provide the KEK with the following name: kek-01 by
copying it the file path below:

    $HOME/.config/reliquary/350d5c8b33dfb7db/kek-0x01
$

The reliquary-device-register tool will tell you exactly which KEK you must install (from ~/my-infra/kek-data) and where to place it. How to securely transport this KEK from your air-gapped computer to this device is left as an excercise to the reader.

Take special note to the KEK ID (01) that was mentioned, as this is your peer ID when setting up tunnels to this device. It will be used later on device_2 to configure the tunnel.

+ Registering device_2 with reliquary

Initialise reliquary on this device as you you did earlier (if it was not yet initialised). After that we can register it with our flock we created previously. 

$ reliquary-device-register 350d5c8b33dfb7db
This device has been registered succesfully

Please provide the KEK with the following name: kek-02 by
copying it the file path below:

    $HOME/.config/reliquary/350d5c8b33dfb7db/kek-0x02
$

As for device_1, take note which KEK must be copied to the presented path and make sure it is made available there. The KEK ID (02) will be used on device_1 to configure the tunnel.

+ Configuring the tunnel on device_1

Now we can configure the tunnel on device_1. We specify the KEK ID for device_2 and a local IP address that is to be assigned to the tunnel interface on device_1. 

$ reliquary-tunnel-config 350d5c8b33dfb7db 02 172.16.99.1/29
Tunnel 350d5c8b33dfb7db-01-02 has been configured.
Please use hymn from now on to bring it up, down or to delete it.

    $ sudo hymn up 350d5c8b33dfb7db-01-02
    $ sudo hymn down 350d5c8b33dfb7db-01-02
    $ sudo hymn del 350d5c8b33dfb7db-01-02
$

+ Configuring the tunnel on device_2

We configure the tunnel on device_2 in the same way as on device_1 but we specify the KEK ID for device_1 and a local IP address that is to be assigned to the tunnel interface on device_2. 

$ reliquary-tunnel-config 350d5c8b33dfb7db 01 172.16.99.2/29
Tunnel 350d5c8b33dfb7db-02-01 has been configured.
Please use hymn from now on to bring it up, down or to delete it.

    $ sudo hymn up 350d5c8b33dfb7db-02-01
    $ sudo hymn down 350d5c8b33dfb7db-02-01
    $ sudo hymn del 350d5c8b33dfb7db-02-01
$

+ Bringing up the tunnel

Finally, if you did everything right we can bring up the tunnel using the hymn tool. Using the commands that reliquary-tunnel-config showed for both device_1 and device_2 we bring up the tunnel

On device_1 

$ sudo hymn up 350d5c8b33dfb7db-01-02

On device_2 

$ sudo hymn up 350d5c8b33dfb7db-02-01

If everything works you'll be able to ping the device_2 (172.16.99.2) from device_1 (172.16.99.1) and vise-versa. You can use the hymn status command on both devices to see status about the tunnel.

+ Hymn

The hymn tool is used to manage your tunnels once configured. It can be used to bring up/down tunnels, add routes (requires a restart of tunnels) and see tunnel statistics. 

# hymn
usage: hymn [cmd]
commands:
  add      - add a new tunnel
  del      - delete an existing tunnel
  down     - kills the given tunnel
  list     - list all configured tunnels
  name     - sets the name for a given tunnel
  status   - show a specific tunnel its info
  route    - modify tunnel routing rules
  up       - starts the given tunnel
#