The Reliquary
A setup guide

This guide will help you to get started with obtaining an account-key and setting up your first tunnel between your device_1 and device_2. The guide assumes familiarity with your system and networking.

+ Table of contents

+ Prerequisites

Important: Your devices must have a clock that is in sync.

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

+ Reliquary setup

To register an account that is valid for 24 hours you use the reliquary-register tool. If on the other hand you already have an account-key, use the reliquary-init cli tool instead to setup up a new device. 

$ reliquary-register https://vessel.reliquary.se/v1
Your new account-key is:
    abcdef01234567890

This account-key is valid for 24 hours and will automatically
deactivate unless you extend its lifetime.

Extending its lifetime can be done by mailing help@reliquary.se
and requesting more time.

Please store this key somewhere safe as we do not save it locally
on your disk and you will lose access to this account with it.
$

- or - 

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

The reliquary-init cli tool should be run on all devices that will be using the reliquary.

+ 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 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 compromised.

The following commands will generate new KEKs under ~/my-infra/kek-data and an ambry bundle for upload called 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.

+ 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 your devices, 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 distribution 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.

+ Register device_1

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.

+ Register device_2

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
$

Just like 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.

+ Setup 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
$

+ Setup 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
$

+ Enabling 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.

+ The Hymn tool

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
  cathedral - change cathedral for a 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
  restart   - restart a tunnel (down, up)
  route     - modify tunnel routing rules
  up        - starts the given tunnel
#

+ Changing Cathedrals

The reliquary provides several different cathedrals that can all be used to discover peers or relay traffic. It is possible to change to any cathedral at any time by using the hymn tool. This makes the reliquary very resilient against cathedrals going offline by allowing you to quickly just swap to another one.

You can use the reliquary-cathedral-list cli tool to see what cathedrals are currently available in the reliquary. After swapping cathedral restart the tunnel. 

$ reliquary-cathedral-list
de-1 157.90.25.232:4500
fi-1 37.27.200.90:4500
$ sudo hymn cathedral 350d5c8b33dfb7db-02-01 37.27.200.90:4500
$ sudo hymn restart 350d5c8b33dfb7db-02-01