The Reliquary
Secure tunnels between your devices
for hackers, by hackers
The Reliquary
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 that you are familiar with your system and networking.
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:
Fetching 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:
If you are simply testing, these could all be the same machine.
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.
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.
Lets get the admin machine setup by creating a new Reliquary account, or logging into an existing account.
Creating a new account machine:
$ 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>
You are in charge of your own 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.
Create your first flock using your admin machine:
$ 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 do as follows:
$ 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.
$ 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 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.
Initialise The Reliquary on your client, unless the client is the admin machine:
$ reliquary-init https://vessel.reliquary.se/v1 reliquary initialised $
Now we join it into the flock we created earlier:
$ 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.
On your admin machine approve the newly joined device:
$ reliquary-device-approve 350d5c8b33dfb7db 577165a1 device approved, please supply it with 350d5c8b33dfb700/kek-data/kek-0x01 $
You will find the KEK 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 can do this using
reliquary-kek-install.
In the example in the guide device-1 receives kek-id 01 and thus
we run the following command on the client:
$ reliquary-kek-install 350d5c8b33dfb700 01 /path/to/kek-0x01 The KEK is now installed as kek-0x01 in 4e9dc3b4f8a3af00. $
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.
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.
Configure a tunnel from device-1 to device-2 using the reliquary-tunnel-config command.
$ 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
$
Configure a tunnel from device-2 to device-1 in the same way.
$ 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
$
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 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 #
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