Skip to content
katzenpost mix network encrypted messaging client
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


the catshadow client

Catshadow is a mix network messaging system. This respoitory contains a client library and a client program which can be used with a Katzenpost mix network. It not only uses strong modern end to end encryption (PANDA + Signal Double Ratchet), but it is also designed to reduce the amount of metadata leaked onto the network.


It is my understanding that in terms of the analysis presented in this blog post ( Brian Warner's "Petmail mailbox-server delivery protocol" ), the catshadow messaging system can be described as:

S1, M0, R1, Rev0

Here I rephrase the definitions of the above messaging system properties: Catshadow clients can compare delivery tokens to determine if they share contacts. However the message spool server cannot tell which message came from which sender, not even that two messages came from the same sender, nor can it determine how many senders might be configured for each recipient. The recipient cannot use the transport information to identify the sender. The recipient depends upon information not visible to the mailbox server to identify the sender, which means a legitimate (but annoying) sender could flood the server without revealing which sender they are. Finally, the revocation behavior is such that the recipient can revoke one or more senders without involving the remaining senders.

Clients make use of a Sphinx SURB based protocol to retreive messages from their remote spool service. The mix network has several Providers which operate spool services which clients can interact with. The spool service is in fact a seperate process which uses our CBOR/HTTP over unix domain socket plugin system to communicate with the mix server.

Over time I plan on replacing the spool services with gradually more sophisticated spool services until I finally have a replicating CRDT based spool service which can help eliminate single points of failure in this messaging system.

Clients make use of the PANDA protocol for exchanging spool identities and the Signal Double Ratchet keys. That is, this messaging system creates bidirectional metadata leakage resistant communications channels which are composed with two unidirection channels. Each unidirectional channel contains the required information to write to a correspondant's remote message spool.

Katzenpost is a variant of the Loopix design and as such makes use of the Poisson mix strategy and therefore must be properly tuned. Tuning of the Poisson mix strategy as not been publicly solved yet but I suspect the solution has something to do with a descrete network event simulator and possibly some machine learning algorithms as well. Perhaps we all should consider the tuning of this mixnet messaging system as half of it's design.

Another unfinished design area is: The Catshadow client periodically polls the client's remote message spool where the intervals between polling are the result of a Poisson process. Currently, tuning this Poisson procress is left unfinished, however, I can state that the goal in tuning this would be to reduce vulnerability to a long term statistical disclosure attack where the passive adversary or compromised Provider tries to link clients with their spool service. Furthermore, I suspect the tuning for this Poisson process can be determined as a sufficiently small fraction of the mean frequency of λPLD which is the aggregate of λP, λD and λL as mentioned in "The Loopix Anonymity System":

the longer design overview

The design of this messaging is not yet fully specified but is partially specified in these specification documents:

Whereas all those specifications assume the existence of the core Katzenpost specifications here which mostly covers the design of the server infrastructure:

There is an older copy of our core Katzenpost specifications rendered in Latex if you prefer to read it that way:

code organization

This repository contains a small amount of high level client code. This client depends on lots of code in other Katzenpost repositories including my fork of agl's PANDA and agl's Signal Double Ratchet:






AGPL: see LICENSE file for details.


  • I would like to thank Leif Ryge for feedback during the design of this client and many of it's protocols.
  • I would like to also thank Adam Langely for writing Pond ( ) which has very obviously inspired a few of our design choices and has provided some code that we use such as the PANDA cryptographic protocol and the Signal Double Ratchet.

supported by

The development of the Catshadow Katzenpost client has been supported by the Samsung Next Stack Zero grant. See Announcing the Samsung NEXT Stack Zero Grant recipients.

You can’t perform that action at this time.