Introduction

This guide will help you to get started by obtaining an account-key and setting up your first tunnel between two of your devices. The guide assumes that you are familiar with your system and networking.

Table of contents

• Prerequistises
• The cli tools
• Reliquary setup
• Key Management
• Your first flock
• Joining device-1
• Joining device-2
• Setup device-1
• Setup device-2
• Enabling the tunnel
• The Hymn tool
• Changing Cathedrals

Prerequisites

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

To get started you need the following on all devices you are planning using Reliquary on:

The Reliquary script and its dependencies.

• jq
• xxd
• curl

Dependencies for being able to build the sanctum project:

• make
• GCC/Clang
• libsodium or mbedtls 3.x.

Fetch The Reliquary script and make sure it lives in your PATH somewhere:

$ mkdir ~/reliquary
$ cd ~/reliquary
$ curl -O https://reliquary.se/rlq
$ chmod +x rlq
$ export PATH=~/reliquary:$PATH

Building sanctum is straight-forward:

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

We highly recommend designating two machines with these purposes for a safer setup:

• keyprod - An air-gapped machine on which you produce keys.
• admin - A machine on which you are logged into The Reliquary with.

If you are simply testing, these could all be the same machine.

The rlq script

The Reliquary rlq script provides you with commands and subcommands to help you manage your flocks and devices with ease. It is a simple shell script that can be inspected. The Reliquary stores files under $HOME/.config/reliquary by default. This path may be overwritten by setting RELIQUARY in your environment before executing any tool.

Reliquary Setup

Lets get the admin machine setup by creating a new Reliquary account, or logging into an existing account.

Creating a new account:

$ rlq register https://vessel.reliquary.se/v1

Make sure you remember your api for the future as it is the only way to login to your account from another machine. There are no account recovery methods.

Newly created accounts are limited to 3 flocks and initially valid for only 24 hours, which can be extended via the account page.

- or -

Login to an existing account:

$ rlq login https://vessel.reliquary.se/v1 <accountkey>

Key Management

You are in charge of your keys.

Practically this will mean using the ambry tool from sanctum to generate new KEKs and ambry bundles for distribution. We will see how to do this in the next step.

The Reliquary will never see any of the encryption keys used to protect your traffic. Each device in a Reliquary flock will receive exactly one KEK and is identified by its KEK id (eg b5).

Important: Generate new ambry bundles often and upload them to rollover your shared secrets. Devices will reject ambries who's expiration date has passed.

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

Important: If a KEK for a device is leaked you must immediately renew the KEK and generate a new ambry bundle such that the compromised KEK cannot be used. No traffic will be compromised due to the fact that the key exchange also includes ECDH+ML-KEM-1024.

Creating your first flock

Creating your first flock is done as follows:

$ rlq flock create
flock 350d5c8b33dfb700 created
$

Using the flock-id we just created we generate new KEKs and a wrapped bundle for upload, on your keyprod machine.

Generating new KEKs for our flock:

$ ambry generate 350d5c8b33dfb700
generating device KEKs under 350d5c8b33dfb700 ... done
deriving internal flock KEKs ... done
$

$ ambry bundle 350d5c8b33dfb700 350d5c8b33dfb700 30 ambry.bundle
ambry.bundle: generated 32385 tunnels, generation 0x57f6416c
$

Now move the ambry bundle from keyprod to our admin machine. How you do this is up to you.

Once on the admin machine we can upload it so that The Reliquary can distribute these wrapped secrets to your devices in the future.

Uploading our new ambry bundle to The Reliquary:

$ rlq ambry upload 350d5c8b33dfb700 ambry.bundle
ambry uploaded
$

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

Now that we have a flock and provisioned it with keys we can move on to joining our two devices (device-1 and device-2) into the flock and getting them talking to each other.

Joining device-1

Joining a device into a Reliquary flock does not require the device to be logged into Reliquary.

You use the rlq shell script to initialise The Reliquary on your client devices after which you join them into your newly created flock.

Initialising The Reliquary on a new client:

$ rlq init https://vessel.reliquary.se/v1
reliquary initialised
$

Joining the new client into the flock:

$ rlq flock join 350d5c8b33dfb7db
This device has been joined into 350d5c8b33dfb7db and is pending approval by
the flock administrator.

    Device: 577165a1

Once approved, the flock administrator will send you the device
its KEK, please place this under the following path:

    /home/user/.config/reliquary/a51f2c141258ab00

Important: A device must be approved after joining a flock.

Approving the new client from your admin machine:

$ rlq device approve 350d5c8b33dfb7db 577165a1
device approved, please supply it with 350d5c8b33dfb700/kek-data/kek-0x01
$

The location of the KEK for the newly approved client on your keyprod machine.

$ ls -l 350d5c8b33dfb700/kek-data/kek-0x01
-r-------- 1 archael archael 32 jun 28 10:48 350d5c8b33dfb700/kek-data/kek-0x01
$

The KEK must now be installed on your client device. You do this using rlq kek install.

Installing the device-1 its KEK (kek 01):

$ rlq kek install 350d5c8b33dfb700 01 /path/to/kek-0x01
The KEK is now installed as kek-0x01 in 350d5c8b33dfb700.
$

How to transfer the KEK file from your keyprod machine to your client is not part of this guide as it can be accomplished in many ways.

We recommend a physical approach for the best security.

Joining device-2

Run rlq init and rlq flock join on your second device, approve it in the same way as you did for device-1 and finally distribute and install the requested KEK to said device.

Setup device-1

Configuring the tunnel to device-2 on device-1:

$ rlq tunnel add 350d5c8b33dfb7db 02 172.16.99.1/29
Tunnel 350d5c8b33dfb7db-01-02 has been added.
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

Configuring the tunnel to device-1 on device-2:

$ rlq tunnel add 350d5c8b33dfb7db 01 172.16.99.2/29
Tunnel 350d5c8b33dfb7db-02-01 has been added.
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 rlq tunnel add showed for both device-1 and device-2 we bring up the tunnel.

Bringing up the tunnel on device-1:

$ sudo hymn up 350d5c8b33dfb7db-01-02

Bringing up the tunnel 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
  bridge      - attach to a bridge interface
  cathedral   - change cathedral for a tunnel
  del         - delete an existing tunnel
  down        - kills the given tunnel
  mtu         - change mtu for a given tunnel
  list        - list all configured tunnels
  liturgy     - configure a liturgy
  name        - sets the name for a given tunnel
  status      - show a specific tunnel its info
  remembrance - toggle remembrance on given tunnel
  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.

Important: sanctum will fail-over to another cathedral automatically if it discovers its current cathedral is unresponsive.

Swapping a tunnel to a different cathedral:

$ rlq 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