[ /howto/ssb/index ]

In my previous article about Patchwork, I provided some basic installation instructions that people could use to get started using the distributed social network software.

Now, having used the software for a while, I've learned a bit about the underlying technology.

Secure-Scuttlebutt (SSB)

This is the underlying protocol used by the applications that further articles will cover.

It is based on dominictarr's earlier work on scuttlebutt, a peer-to-peer replicatable data structure, with the added benefit of various cryptographic techniques.

These techniques make it such that the data structure can be safely replicated by peers that you don't necessarily trust.


The most important thing to understand is that the protocol assumes that you have a private-public keypair. The private key is effectively your identity with regard to the rest of the SSB protocol's behaviour. Anyone with access to the private key will be able to impersonate you.

Once you've generated your keypair, it's recommended that you create a backup of the private key, and store it in a secure fashion.

With that keypair, you are able to encrypt and sign messages. Each message that you publish has a unique id. Each subsequent message references the unique id of the message that preceded it.

If you have the most recent message, you can follow the link to the previous message, and so on, all the way back to the first message published. While this recursive method is fairly simple to explain, the actual details of how this is accomplished may differ between implementations.

Applications can be built which subscribe to new messages, and present them to the user as a feed, or some other arrangement other than their natural ordering. Any application using the SSB protocol is structured around this notion of a feed.


It can be verified or refuted that a message was published using a particular secret key. Since the ordering of messages cannot be changed without invalidating the following messages, and only someone with the secret key can modify messages, the result is a data feed with a high degree of integrity.

Since older messages cannot be changed without destroying the integrity of a feed, once you have downloaded a message, you can save it to your disk and avoid having to download it again. You only need to be able to check for the latest message, and trace it back until you reach a message id that you already know about.


The assumption that older messages cannot be changed makes SSB especially efficient as a synchronization protocol. As an added benefit, applications which cache messages are able to operate offline, since they have access to all past information.

Interestingly, once a message is published, the publisher doesn't need to be the one to distribute it, as its integrity is already cryptographically assured. The initial publisher can go offline, and anyone who has access to their public key can verify messages retrieved from other sources.

SSB applications can take advantage of the fact that they've cached the feeds of those they follow, and spread those messages to other interested parties through what is known as a gossip protocol.

Using feeds and gossip in this way, applications construct a network of nodes which cooperate to distribute cryptographically verified feeds. It's up to each node to decide which messages they should store, retrieve, and redistribute.

There are many ways this could be done, so we should look at a particular implementation. See my follow up article about Scuttlebot.