Table of contents

Manual setup

This guide is aimed at people wanting to manually setup sanctum between two machines where at least one machine has a public IP.

Let's call this a client-to-server setup.

For this example we will use the following parameters:

Building

On both client and server: 

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

Using the CIPHER environment variable, one can control what AEAD cipher is used for traffic protection. By default it is AES256-GCM using the low level OpenSSL APIs.

Other alternatives are:

Environment

Create a directory for sanctum, set the right permissions on it. You will want to do this on both client and server. 

# mkdir -p /etc/sanctum
# chmod 0700 /etc/sanctum

The shared secret

Generate the shared secret on either the client or the server and figure out a way to securely transfer it to the other peer :) 

# dd if=/dev/urandom of=/etc/sanctum/secret bs=32 count=1

Note that the wrapping of session keys is done using a symmetrical key derived from a strong shared secret and is thus by itself not PFS. The underlying shared secret may be swapped out via an OOB mechanic while sanctum is running however.

It is therefor imperative that you have good control over your hardware and that you find a good OOB method to update your underlying shared secrets.

Configurations

We will configure both the client and server in such a way so that the process talking to the outside world (purgatory-*) is running as a seperate user, while the others run as root.

Note: You may configure a different user for each process.

Configuring the client

Create the following configuration file under /etc/sanctum/client.conf. Make sure you replace user with your own username. 

instance to-server

tunnel 10.0.0.1/24 1422
secret /etc/sanctum/secret

peer 1.2.3.4:1234

run heaven-rx as user
run heaven-tx as user
run purgatory-rx as user
run purgatory-tx as user

run control as user
control /tmp/sanctum.control user

run bless as root
run chapel as root
run confess as root

Now start it. 

# sanctum -d -c /etc/sanctum/client.conf

Configuring the server

Create the following configuration file under /etc/sanctum/server.conf. Make sure you replace user with your own username. 

instance to-client

tunnel 10.0.0.2/24 1422
secret /etc/sanctum/secret

local 1.2.3.4:1234

run heaven-rx as user
run heaven-tx as user
run purgatory-rx as user
run purgatory-tx as user

run control as user
control /tmp/sanctum.control user

run bless as root
run chapel as root
run confess as root

Now start it. 

# sanctum -d -c /etc/sanctum/server.conf

Up and running

If everything went well you now have a tunnel between both devices and can ping each others tunnel addresses. 

$ ping 10.0.0.1
64 bytes from 10.0.0.1: icmp_seq=0 ttl=255 time=21 ms
64 bytes from 10.0.0.1: icmp_seq=1 ttl=255 time=22 ms
64 bytes from 10.0.0.1: icmp_seq=2 ttl=255 time=21 ms
$

Hymn setup

You can also use the hymn tool to more easily get up and running. The hymn tool is part of the sanctum repository and acts as a system configuration tool.

These next few steps depend on you having generated and shared the secret just as done before.

Tunnel configuration

Configure the client using the hymn tool: 

$ sudo hymn add 01-02 tunnel 10.10.0.1/24 mtu 1422 peer 1.2.3.4:1234 \
    secret /etc/sanctum/secret

And now the server side: 

$ sudo hymn add 02-01 tunnel 10.10.0.2/24 mtu 1422 local 1.2.3.4:1234 \
    peer 0.0.0.0:0 secret /etc/sanctum/secret

Tunnel up

Now that you've done that you can bring up the instances. You do this by running the hymn up command with the correct instance name.

For example on the client: 

$ sudo hymn up 01-02

And on the server side: 

$ sudo hymn up 02-01

After a few seconds the tunnel will be alive.

Tunnel status

You can see tunnel status using the hymn status command. 

$ sudo hymn status 01-02
hymn-01-02:
  local         0.0.0.0:0
  tunnel        10.0.0.1/24 (mtu 1422)
  peer          1.2.3.4:1234

  routes
    10.0.0.0/24

  accepts
    10.0.0.0/24

  tx
    spi            0x0201c23d (age: 1943 seconds)
    pkt            9929
    bytes          1034939
    last packet    3 seconds ago

  rx
    spi            0x0102a866 (age: 1943 seconds)
    pkt            6151
    bytes          2050832
    last packet    6 seconds ago
$

Useful hymn commands

Some other useful commands: