This is a small, reviewable, capable, pq-safe and fully privilege separated VPN daemon for OpenBSD, Linux and MacOS.

Due to its privilege separated design, sanctum guarantees that all of its important assets are separated from the processes that talk to the internet or handle non-cryptography related things.

Additionally when making use of sanctum's cathedrals one can get peer-to-peer tunnels that are able to traverse NAT, allowing your devices to talk to each other directly no matter where they are without having to open pesky firewall ports or fiddle with forward rules.

See The Reliquary for an example on this.

There are several processes that make up a sanctum instance:

Each process should be run as its own user.

Each process is sandboxed and only has access to the system calls required to perform its task. There are two exceptions: guardian (the main process), and bishop (liturgy manager), neither of these are sandboxed due what they are responsible for.

The guardian process is only monitoring its child processes and has no other external interfaces. The bishop process must be privileged due to the fact it is fork+exec'ing the hymn configuration tool for setting up new tunnels (only if using liturgy mode).

The processes share packets between each other in a very well defined way.

For incoming packets:

purgatory-rx (black) -> confess (decryption) -> heaven-tx (red)

For outgoing packets:

heaven-rx (red) -> bless (encrypt) -> purgatory-tx (black)

When the processes start they will remove any of the queues they do not need for operating.

As an example of why this is important, it is impossible for a packet that arrives on the plaintext interface to be moved to the ciphertext interface without passing the encryption process.

Sanctum is post-quantum safe due to its unique approach to deriving session keys based on a shared symmetrical secret in combination with a hybridized asymmetrical exchange. It combines both classic ECDH (x25519) and the PQ-safe NIST standardized ML-KEM-1024.

See docs/crypto.md for details on the key exchange.

Traffic is encapsulated with ESP in tunnel mode, using incrementing 64-bit sequence numbers. It is encrypted under AES256-GCM using keys negotiated as described above.

A 96-bit nonce is used, constructed as follows:

nonce = 32-bit salt from key exchange || 64-bit packet counter

You can select what cipher sanctum will use by specifying a CIPHER environment variable at compile time with one of the following:

• libsodium-aes-gcm (AES256-GCM via libsodium) [default]
• intel-aes-gcm (AES256-GCM via Intel its highly performant libisal_crypto lib).
• nyfe-agelas (Agelas via nyfe, an AEAD cipher based on Keccak).

Note that no matter which CIPHER is selected libsodium is always a dependency as it is used for x25519.

Sanctum supports one-directional tunnels, this is called the pilgrim and shrine mode.

In pilgrim mode, sanctum will be able to send encrypted traffic to its shrine peer. It will however never send an RX key to its peer (a shrine).

In shrine mode, sanctum will be able to verify and decrypt the arriving traffic but will never receive a TX key from its peer.

This allows one-way traffic to flow from a pilgrim to the shrine with a strong guarantee that the shrine cannot send data back (there are no keys nor are there any processes to do so).

A cathedral is a sanctum mode that can run on a machine somewhere and is an authenticated relay and key distribution point. A cathedral can never read, modify or inject valid traffic as it does not hold any of the session keys.

Peers can use a cathedral to move to a peer-to-peer end-to-end encrypted connection if both peers are behind a not too restrictive NAT.

A cathedral may also be used as an Ambry distribution point for shared secret rollover. These ambry bundles are wrapped with unique per-device KEKs and are unable to be read by the cathedral.

This essentiallys solves the key distribution problem with symmetrical keys by providing you with a way to allow the cathedrals to hand out black keys to devices.

See docs/crypto.md for details on the ambries and docs/cathedral.md for details on a cathedral.

A default build requires pkg-config and libsodium.

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

If this is to complicated for you, this isn't your software.

Sanctum builds on MacOS 13+, OpenBSD 6.8+ and Linux-y things like Ubuntu 22.04.

Sanctum uses a configuration file. Find an example of a simple configuration below.

# Name of this sanctum instance.
instance laptop

# Uncomment if you want l2 instead of l3.
#tap yes

# Path to the shared secret.
secret /etc/sanctum/laptop_secret.key

# The control socket for pontifex.
run control as joris
control /tmp/sanctum-control joris

# The tunnel configuration
tunnel 1.0.0.1/30 1422

# Add additional routes over the tunnel
route 2.0.0.0/24

# The local address to which sanctum binds.
local x.x.x.x:2333

# Optional peer address, ignore if you have a peer that
# moves networks a lot.
peer y.y.y.y:2333

# The encryption and decryption processes.
run bless as _bless
run confess as _confess

# Run the internal io processes as one user.
run heaven-rx as _heaven
run heaven-tx as _heaven

# Run the external io processes as another.
run purgatory-rx as _purgatory
run purgatory-tx as _purgatory

# Run the bishop as privileged root.
run bishop as root

# Run chapel for the key exchange as yet another user.
run chapel as _chapel

You can use libkyrka to implement the sanctum protocol and tunnels into your application directly. Note that this does not provide the same type of sandboxing as the daemon.