Repository files navigation

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

Due to its privilege separated design, sanctum guarantees thatall of its important assets are separated from the processesthat talk to the internet or handle non-cryptography relatedthings.

Sanctum tunnels are always peer-to-peer and end-to-end encrypted.

If one or both peers are behind NAT you can use sanctum's cathedralmode as a discovery and relay service (relay only if p2p does notwork due to NAT constraints).

SeeThe Reliquary, a community drivensanctum cathedral setup.

It is entirely possible to set up your own cathedrals.

There are several processes that make up a sanctum instance:

Each process runs as its own user.

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

The guardian process is only monitoring its child processes and has noother external interfaces. The bishop process must be privileged due tothe fact it is fork+exec'ing the hymn configuration tool for setting upnew tunnels when 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 notneed for operating.

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

Sanctum is post-quantum safe due to its unique approach toderiving session keys based on a shared symmetrical secret incombination with a hybridized asymmetrical exchange. It combinesboth classic ECDH (x25519) and the PQ-safe NIST standardizedML-KEM-1024.

Seedocs/crypto.md for details on the key exchange.

Traffic is encapsulated with the sanctum protocol header which in turn iscarried in a UDP packet, using incrementing 64-bit sequence numbers.

Traffic 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 environmentvariable at compile time with one of the following:

• libsodium-aes-gcm (AES256-GCM via libsodium)[default]
• mbedtls-aes-gcm (AES256-GCM via mbedtls 3.x its mbedcrypto lib).
• 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 alwaysa dependency as it is used for x25519.

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

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

In shrine mode, sanctum will be able to verify and decrypt the arriving trafficbut will never receive aTX key from its peer.

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

Note that no asymmetry is available for one-directional tunnels.

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

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

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

This essentially solves the key distribution problem with symmetricalkeys by providing you with a way to allow the cathedrals to hand outblack keys to devices.

Seedocs/crypto.md for details on the ambries anddocs/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

It is entirely possible to swap the underlying kem, ecdh, cipher and randomimplementations used in sanctum, please see themk directory how thisis configured and done.

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

Sanctum uses a configuration file. Find an example ofa 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 joriscontrol /tmp/sanctum-control joris# The tunnel configurationtunnel 1.0.0.1/30 1422# Add additional routes over the tunnelroute 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 _blessrun confess as _confess# Run the internal io processes as one user.run heaven-rx as _heavenrun heaven-tx as _heaven# Run the external io processes as another.run purgatory-rx as _purgatoryrun 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 uselibkyrka to implementthe sanctum protocol and tunnels into your application directly. Note thatthis does not provide the same type of sandboxing as the daemon.