Jessica Tallon — October 15, 2026
\nCreating a direct connection between any two computers (not just from client\nto server) over the internet is notoriously difficult. Many home networks are\nbehind NATs which prevent new inbound connections. Sometimes these NATs are from\nthe ISP (carrier-grade NATs) which are impossible to work around with port\nforwarding and/or UPnP. While\nhole punching techniques\ncan break through NATs, it's far from guaranteed. Thus, we need something that\nworks in the general case: relays.
\nRelays are servers, accessible over the public internet, that act as a proxy\nbetween two computers that cannot directly connect. In\nGoblins 0.12\nwe introduced a federated relay named "prelay". While OCapN traffic is\nencrypted in transit, the prelay crucially lacks\nend-to-end encryption (E2EE).\nE2EE secures all the messages so they can only be read by their intended\nrecipient, preventing intemediatory parties (like the relay) from tampering with\nor reading them. Due to the lack of E2EE, the relay was named "prelay"\n(pre-relay) to dissuade its use. Thanks to a\ngrant from NLnet, we're happy\nto announce that the next release of Goblins will include a federated, E2EE\nrelay implementation!
\nHaving a relay that we could recommend has become even more of a critical part\nof the OCapN story as we've developed Hoot,\nour Scheme to WebAssembly compiler. The web is a challenging environment in\nwhich to build peer-to-peer applications. Most of the patterns and available\nAPIs are designed around client-server architectures and centralized certificate\nauthorities for security. While relays are unsatisfying compared to making\ndirect connections, they enable peer-to-peer applications to communicate in\nthese hostile environments.
\nIn addition to implementing the E2EE relay for Goblins, our NLnet grant also\nincludes writing a specification for the OCapN group so that the relay can be\nbroadly supported by other OCapN implementations.
\nWe wanted OCapN relays to have the following qualities:
\nFederated: reduces the power any one relay holds over the wider
network
End-to-end encrypted: prevents man-in-the-middle and replay
attacks; perfect forward secrecy
Our existing "prelay" already has the first two properties. To get E2EE, we\nchose to build upon the Noise Protocol.
\nNoise is actually a well-established framework of different patterns and\nciphers. This allows applications to pick the pattern which is most suitable to\ntheir needs. It's also a protocol family which has widespread use (WireGuard,\nWhatsApp, etc.) and has been scrutinised a great deal. None of us at Spritely\nare cryptographers by training, so using an off-the-shelf protocol also ensures\nwe're avoiding any mistakes in protocol design.
\nSo how can we use Noise with OCapN? When connecting to an OCapN peer, there is a\nLocator\nwhich encodes three components about the remote peer:
\nTransport: a symbol identifying the kind of netlayer it is (such as
onion)
Each netlayer decides what goes into these fields, and the union of both the\ndesignator and transport should uniquely identify the peer. Noise uses two kinds\nof keys:
\nAn important step each netlayer needs to consider is something called *peer\nauthentication*, which verifies that a peer is who they say they are. OCapN\nrequires that there exists\nat most one connection\nbetween any two peers at a given time. Ensuring there is only ever one\nsession between any two peers is essential to allow for object identity\ncomparison and preventing unnecessary\n3rd party handoffs.\nAn OCapN implementation will enforce this by reusing connections or closing new\ninbound connections if one already exists. Without peer authentication, a\nmalicious peer could impersonate another peer causing a denial of service to the\npeer whose identity was stolen.
\nAs described above, the designator is a public key, which allows the peer to\nprove their identity by using its private key. Noise has a pattern for this\nknown as XK, where the initiator knows the key of the responder and will\nverify it. The X is referring to the initiator's static key being transmitted\nto the responder. The K is referring to the initiator already knowing the\nresponder's public key. The public key of a peer is encoded and placed in the\ndesignator for the initiator to use.
Noise also allows the use of different key generation algorithms, cipher suites,\nand hashes. This is great as we needed to select something which has\nimplementations both in commonly available cryptographic libraries and within\nthe browser (for Hoot). X25519 keys are well supported in all those situations,\nas are AESGCM cipher suites and SHA256 hashes. These are all available in\nGnuTLS (what we're using on the Guile VM) and in the\nSubtleCrypto API\n(that we're using on the web).
\nOf course, to use Noise we need an implementation. Noise is popular enough that\nthere's quite a few implementations for different languages. Unfortunately,\nGuile is not one of them, so that meant writing our own Noise library.
\nThe Guile Noise library we've\nwritten doesn't require users to know the intricate workings of Noise, but Noise\nis interesting and so let's take a brief look at how it works and my\nimplementation experience. The\nNoise specification is actually pretty\napproachable and is built around three conceptual objects:
\nCipherState: holds a key and a hash; provides encryption, decryption, and
rekeying
SymmetricState: holds a chaining key and hash output; uses CipherState
for encryption, as well as deriving new keys and hashes
HandshakeState: holds state for the initial handshake and handles reading
and writing of handshake messages
The Noise protocol starts with a handshake. This is turn-based where the\ninitiator goes first and writes their handshake message. The receiver then reads\nthat message and writes their own. This continues until the handshake is\ncomplete. After which you only need the CipherState which can encrypt and\ndecrypt messages (and if desired\nrekey).
Interestingly, Noise defines a small intepreter which defines a limited set of\noperations. The handshake patterns are then defined in terms of these\noperations. I won't go through all of them (see the spec if you're interested),\nbut the XK pattern is defined as:
pre-message <- s\n-> e es\n<- e ee\n-> s seThis is a handshake consisting of three messages (and a\npre-message). Pre-messages are not exchanged as part of the Noise handshake\nitself, they're messages which are expected to have happened out-of-band prior\nto connection. In this case <- s means the static key from the responder is\nsent to the initiator. This happens by it being encoded in the OCapN peer\nlocator as we discussed above. The arrows show the direction with the left side\nbeing the initiator and the right being the responder.
I'll just cover the first message, -> e es. This message is for the\ninitiator to send to the responder as it starts with ->. The operations are:
e: generates an emphemeral key, transmits the public part, and mixes it into
an internal hash
es: derives a new key (from the ephemeral key and responders static key) and
mixes it into its own key
This allows a Noise library to easily support lots of different patterns. Each\npattern can define it's pre-messages and handshake messages (all of which are\ndefined in the spec) and the implementation just needs to go through and perform\nthe steps.
\nOnce the handshake is complete, the Noise library will create two CipherState\nobjects. The first is used for encrypting and decrypting the initiator's\nmessages, the second for the responder's messages.
The Guile library implements all 12 of the\nfundamental interactive patterns.\nWe built this library to work on both Hoot and the Guile VM. It currently uses\nSubtleCrypto for Hoot and GnuTLS for the Guile VM, but it's written so users\nof the library can add support for other crypto libraries. Our library comes\nwith support for X25519 key generation, AES-GCM ciphers, and SHA256 and\nSHA512 hash functions. Noise not only provides an approachable spec, but also a\nset of\ntest vectors to\nhelp implementation. These are a set of messages which Noise should exchange for\na given pattern and keys. Our library has been tested against all the vectors\nfor patterns and crypto that we support and the test runner checks them on Hoot\nas well as the Guile VM.
OCapN is a layered protocol consisting of CapTP (Capability Transport Protocol)\nand many netlayers. A netlayer sends encoded messages between two peers over a\nparticular medium. This allows the higher-level CapTP to be *transport\nagnostic*. For example, the\nOnion netlayer\nprovides transport over Tor Onion services. However, netlayers can be defined\nnot only in terms of a specific transport protocol, but also in terms of\nanother netlayer. We call these meta netlayers.
\nNoise itself isn't designed with a specific transport protocol in mind, and the\nNoise netlayer isn't either. Indeed many netlayers might want to rely on the\nproperties of Noise for many different reasons. Even netlayers which provide\nstrong encryption, like Tor, may wish to rely on Noise for its bidirectional\npeer authentication properties (Tor authenticates outbound connections to a\nhidden service, but not the reverse).
\nThe Noise netlayer thus composes with any other netlayer. Composing the Noise\nnetlayer and prelay netlayer yields an end-to-end encrypted relay netlayer!
\nHow does this work? The Noise netlayer spawns a sort of "bootstrap" object (not\nthe same\nbootstrap\nif you're familiar with CapTP). The bootstrap object is encoded within the OCapN\npeer locator, and can be enlivened to make a live reference when making a new\noutbound connection. Each side spawns an\ninbox and outbox pair,\nand the initiating peer delivers their outbox to the bootstrap object. The\nbootstrap object sets up its side of Noise and makes its own inbox-outbox pair\nreturning its outbox. Each side is then able to deliver messages to each other\nby sending messages to the remote outbox object. Each side then follows the\nhandshake procedure. Once complete, encrypted messages can be exchanged by using\nthe Noise encrypt procedure and decrypted when read from the inbox.
\nLooking at the test code which uses the\nTCP+TLS netlayer,\nlayering on Noise encryption is just a few lines of code:
\n(define a-mycapn\n (with-vat vat-a\n ;; Spawn the TCP+TLS netlayer\n (define tcp-tls-netlayer (spawn ^tcp-tls-netlayer "127.0.0.1"))\n ;; Spawn the Noise netlayer, passing in the TCP+TLS netlayer\n (define noise-netlayer (spawn ^noise-netlayer tcp-tls-netlayer))\n ;; Spawn the MyCapN object (CapTP)\n (spawn-mycapn noise-netlayer)))So, how does this work with the relay? Well, since we already have an\nnon-E2EE relay and now have seen we can compose Noise and get the properties of\nboth, we can simply pass in the prelay netlayer to Noise netlayer and get an\nE2EE relay. Of course, we don't want to ask users of the netlayer to do\nthis. We'll be replacing the prelay module with a new relay module that is\nalways end-to-end encrypted.
\nWhile the relay design (in its non-E2EE form) isn't new to Goblins, it's\nworth quickly taking a look at how the relay works. The relay itself is built on\nthe idea of a relay client and a relay server. On the relay server there are two\nactors:
\nController: allows the client to steer its own relay accepting
new inbound connections and making new outbound connections
Endpoint: which is encoded in the OCapN locator and is publicly
accessible, a relay server messages this object when establishing a new\n connection to the peer
This makes the relay federated. Two OCapN peers can use different relay\nservers and still communicate using OCapN between the two relay servers. When a\nclient wants to make an outbound connection to a peer on another relay server,\nthe relay can enliven the endpoint sturdyref (getting a live object) and send a\nmessage to it.
\nThe animation above shows the flow between two peers using federation. It starts\nwith two actors on two different peers, Alice (on peer A) and Bob (on peer B).\nAlice has a sturdyref (an OCapN locator specifying an object) to Bob. Here's\nhow the flow works:
\nPeer A first sets itself up with the controller by registering an object
a-incoming with the controller. This object can be used when establishing\n new connections.
Alice has a sturdyref to Bob but wants a a live reference to Bob that she can
message, she asks her MyCapN to /enliven/ it.
MyCapN creates an adeliver object which faciliates the connection. It then
sends a message to the relay controller with the sturdyref and adeliver\n object and asks the relay to make a new connection.
The controller extracts the endpoint object for Peer B's relay from the
sturdyref and enlivens it forming a new connection between the two relays. It\n also spawns a new rarelay object to facilitate communication between these\n two peers and hands this back to adeliver.
The controller then sends the rarelay object to the endpoint on B's
relay. B's relay then spawns its own analog to the object rbrelay.
Peer B's relay reaches out to the b-incoming object, allowing it to
establish a new connection to Peer B. It passes along the rbrelay object.
Peer B's MyCapN object spawns a new bdeliver object which facilitates its
connection.
This gives the two peers a connection to one another, even though neither share\na common relay server. The relay is designed to be completely stateless, i.e. it\ndoesn't hold on to data, configuration, or anything else.
\nOne of the lessons we've learned since co-authoring ActivityPub is it's crucial\nto reduce the impact of servers on their users. In ActivityPub, each instance (a\nserver) stores all the data for its users and performs all the operations their\nbehalf. This means the user needs to trust the server a lot, and if the user's\ninstance shuts down, or they simply wish to migrate, moving to another server is\ndifficult.
\nLearning from those problems, it was critical for us to make sure the server\nwas stateless. The relay itself stores no state/data for a user and, aside from\nconnecting to another peer, the only behavior it's expected to perform is\nrelaying messages. This makes changing relay servers incredibly easy. The user\nsimply needs to find another (or setup their own) relay server and include that\nin their sturdy references instead.
\nThe work isn't done, though. Adding support to Goblins was just one part of the\nNLnet grant. We'll be contributing specifications for the encrypted relay to the\nOCapN standardization group so others can implement\nit. Ridley, who has implemented\nOCapN in Dart, has already implemented\ntheir own Noise library in preparation\nfor the E2EE relay. As part of the grant work within the OCapN group, we'll also\nbe adding support to the test suite\nto allow both testing new relay implementations, and testing the rest of OCapN\nover the relay.
\nAnother milestone of the grant is to implement a Guix service to make it easy to\nrun an instance of the relay. The relay doesn't take many resources to run and\nit has very few dependencies, so it should be easy for others to package for\ntheir distributions and run on the cheapest VPS or old computers users might\nhave around their home. We are looking forward to the deployment of a vast\nnetwork of OCapN relays.
\nYour support makes our work possible! If you like what we do, please\nconsider becoming a Spritely supporter today!
\n