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 tools 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 cli-tools and make sure they live in your PATH somewhere:

$ mkdir ~/reliquary
$ cd ~/reliquary
$ curl -O https://reliquary.se/reliquary-cli.tar
$ tar fvx reliquary-cli.tar
$ 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 tools

The Reliquary cli-tools are shell scripts based around curl to perform the API requests and jq to parse the responses. Below is a list of the most relevant ones and what they do.

• reliquary-status - Display reliquary status on the machine.
• reliquary-init - Initialise reliquary without login.
• reliquary-register - Registers a new account.
• reliquary-login - Login to an existing account.
• reliquary-flock-create - Create a new flock tied to your account.
• reliquary-flock-list - List your current flocks on your account.
• reliquary-flock-join - Join a device into one of your flocks.
• reliquary-device-list - List all devices in one of your flocks.
• reliquary-device-approve - Approve a device that has joined one of your flocks.
• reliquary-device-delete - Removes a device from your flock.
• reliquary-kek-install - Install a KEK for a flock.
• reliquary-ambry-upload - Upload a new ambry bundle for a flock.
• reliquary-cathedral-list - Lists all cathedrals in The Reliquary.
• reliquary-tunnel-configure - Configures a tunnel to another peer in the same flock.

The cli-tools store 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:

$ reliquary-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:

$ reliquary-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:

$ reliquary-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:

$ reliquary-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 cli-tools 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:

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

Joining the new client into the flock:

$ reliquary-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:

$ reliquary-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 reliquary-kek-install.

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

$ reliquary-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 reliquary-init and reliquary-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:

$ 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

Configuring the tunnel to device-1 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.

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:

$ 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