README
¶
Katzenpost Mix Network
Post Quantum Anonymous Communication Network
Katzenpost is a software project dedicated to designing and implementing mix network protocols. A mix network is a type of anonymous communication network. An anonymous communication network is also known as a traffic analysis resistant network; that is, it's protocols are designed to resist statistical analysis by passive global adversaries.
Traffic analysis typically refers to the statistical analysis of encrypted traffic. Traffic analysis is worth defending against given that common network protocols leak lots of information such as source and destination IP addresses, message size, message sequence, message delay pattern, geographical locations, social graph etc. Mere end to end encryption alone cannot protect against this type of information leakage.
At the most basic level, mixnets are composed of mix nodes. These are a cryptographic packet switching routers which protect our privacy by mixing many messages together and cryptographically transforming them before routing them on to the next hop. Mix nodes also use shuffling or added latency to create uncertainty for network observers. This uncertainty is in regards to trying to link incoming messages with the outgoing messages.
Project Status
Many excited new changes are forthcoming! You can watch our progress being tracked, here:
https://github.com/orgs/katzenpost/projects/6/views/5
There are essentially two types of interaction with a Katzenpost mixnet:
- clients talk to mixnet services and their traffic stays in the mixnet
- clients talk to Internet services; proxying through the mixnet onto the Internet.
Building Katzenpost
To build all server related components, type "make" when inside this repo:
cd katzenpost
make
Client:
Currently, Katzen is the only client available for use with Katzenpost. However a SOCKS proxy client is forthcoming and you'll be able to use that with many existing applications.
Server Side Usage/Configuration
Our docker configuration is the most comprehensive and up to date place to learn about how to configure a Katzenpost mix network. Run the makefile in the docker directory to get a usage menu:
$ cd katzenpost/docker; make
These make targets allow you to control the test network:
run - run the testnet in the foreground, until ctrl-C
start - start the testnet in the background
stop - stop the testnet
wait - wait for testnet to have consensus
watch - tail -F all logs
status - show testnet consensus status
show-latest-vote - does what it says
run-ping - send a ping over the testnet
clean-local - stop, and delete data and binaries
clean-local-dryrun - show what clean-local would delete
clean - the above, plus cleans includes go_deps images
You can run a docker mixnet locally and then inspect the configuration files to learn how to configure a Katzenpost mixnet.
Documentation is a work in progress:
Expert's Corner
Katzenpost is an unverified decryption mix network that uses a continuous time mixing strategy with client selected exponential delays and a stratified (layered) topology.
Our documentation is in progress, but we have some resources for experts:
-
Our threat model document, work-in-progress, can be found here.
-
Our design specification documents are available here.
Wire protocol based on Noise
Every component in a Katzenpost mix network uses our "wire" protocol, the protocol that sits on top of either TCP or QUIC, is a cryptographic protocol based on Noise:
We believe in the Noise cryptographic protocol framework, that it is good to use it instead of TLS, whenever possible. Noise places all of the protocol decision making during the design phase of the protocol instead of during protocol runtime. This means there are no protocol downgrade attacks, no dynamic selection of ciphersuite and so on.
However, we use a variation of Noise called Post Quantum Noise, from the paper:
@misc{cryptoeprint:2022/539,
author = {Yawning Angel and Benjamin Dowling and Andreas Hülsing and Peter Schwabe and Florian Weber},
title = {Post Quantum Noise},
howpublished = {Cryptology ePrint Archive, Paper 2022/539},
year = {2022},
doi = {10.1145/3548606.3560577},
note = {\url{https://eprint.iacr.org/2022/539}},
url = {https://eprint.iacr.org/2022/539}
}
The precise Noise protocol descriptor string we use is:
Noise_pqXX_Kyber768X25519_ChaChaPoly_BLAKE2s
However the hybrid KEM Kyber768X25519 is constructed using a security preserving KEM combiner and a NIKE to KEM adapter with semantic security so that the resulting hybrid KEM is IND-CCA2 in QROM.
Here's a diagram of the pqXX pattern which we use:
sequenceDiagram
Client-)Server: e
Server-)Client: ekem, s
Client-)Server: skem, s
Server-)Client: skem
Sphinx
We use the Sphinx cryptographic packet format and allow it's geometry to be completely configurable to accomodate various networking requirements. Additionally the Sphinx can use any NIKE (non-interactive key exchange). We also developed a novel post quantum variation called KEM Sphinx. KEM (key encapsulation mechanism) Sphinx is twice as fast on the server side as the original NIKE Sphinx because it only requires one public key operation per hop instead of two. However it has the packet header overhead size penalty that grows linearly with the number of hops.
And here are some Sphinx benchmarks using different KEMs and NIKEs:
| Primitive | Sphinx type | nanoseconds/op | seconds/op |
|---|---|---|---|
| X25519 | KEM | 80093 | 8.009×10−5 |
| X25519 | NIKE | 160233 | 0.000160233 |
| Kyber512 | KEM | 43758 | 4.3758e-5 |
| Kyber768 | KEM | 57049 | 5.7049e-5 |
| Kyber1024 | KEM | 72173 | 7.2173e-5 |
| Kyber768 X25519 Hybrid | KEM | 87816 | 8.7816e-5 |
| CTIDH512 | NIKE | 336995975 | 0.336995975 |
| CTIDH1024 | NIKE | 18599579037 | 18.599579037 |
| CTIDH2048 | NIKE | 17056742100 | 17.0567421 |
| CTIDH1024 | KEM | 11408217346 | 11.408217346 |
We can draw several conclusions from this table of benchmarks:
- KEM Sphinx is about twice as fast as NIKE Sphinx
- Kyber768 is faster than X25519
- Kyber768 X25519 Hybrid KEM Sphinx is almost as fast as X25519 NIKE Sphinx but probably a lot more secure given that it's a post quantum hybrid construction which still uses the classically secure X25519 NIKE.
- CTIDH is very slow and we probably don't want to use it for Sphinx. We instead think it very useful for application level encryption.
Please also note that hybrid KEMs referred to above are constructed using a security preserving KEM combiner and a NIKE to KEM adapter with semantic security so that the resulting hybrid KEM is IND-CCA2 in QROM.
PKI/Directory Authority
Mix network key management and distribution is handled by the directory authority system, a decentralized voting protocol that can tolerate (1/2 * n)-1 node outages. Clients and mix nodes can talk to the dirauth (directory authority) system to get a published PKI document which is essentially a view of the network which contains public cryptographic keys and network connection information.
The mix descriptors are signed by the mix nodes. Each dirauth also signs their interactions in the voting protocol and the final published PKI document.
Mix nodes and dirauth (directory authority) nodes use our hybrid post quantum signature scheme which is currently:
- ed25519 + Sphincs+
Note that we could have just used Sphincs+ since hash based signature schemes have a solid theoretical foundation, however there can still be mistakes in the hyper tree design and so pairing it with ed25519 is prudent defense in dept.
Clients also use this signature scheme to verify PKI documents.
We are using the SHAKE-256f parameterization of Sphincs+ via the reference implementation.
License
AGPLv3
Donations
Your donations are welcomed and can be made through Open Collective here.
Supported By
This project has received funding from:
- European Union’s Horizon 2020 research and innovation programme under the Grant Agreement No 653497, Privacy and Accountability in Networks via Optimized Randomized Mix-nets (Panoramix).
- The Samsung Next Stack Zero grant.
- NGI0 PET Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825310.
- NGI Assure Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 957073.
Directories
¶
| Path | Synopsis |
|---|---|
|
authority
|
|
|
voting/client
Package client implements the Katzenpost voting authority client.
|
Package client implements the Katzenpost voting authority client. |
|
voting/server
Package server implements the Katzenpost voting authority server.
|
Package server implements the Katzenpost voting authority server. |
|
voting/server/config
Package config implements the Katzenpost voting authority server configuration.
|
Package config implements the Katzenpost voting authority server configuration. |
|
Package client provides a Katzenpost client library.
|
Package client provides a Katzenpost client library. |
|
config
Package config implements the configuration for the Katzenpost client.
|
Package config implements the configuration for the Katzenpost client. |
|
internal/proxy
Package proxy implements the support for an upstream (outgoing) proxy.
|
Package proxy implements the support for an upstream (outgoing) proxy. |
|
core
|
|
|
cert
Package cert provides a cryptographic certicate library.
|
Package cert provides a cryptographic certicate library. |
|
epochtime
Package epochtime implements Katzenpost epoch related timekeeping functions.
|
Package epochtime implements Katzenpost epoch related timekeeping functions. |
|
log
Package log provides a logging backend, based around the go-logging package.
|
Package log provides a logging backend, based around the go-logging package. |
|
queue
Package queue implements a priority queue.
|
Package queue implements a priority queue. |
|
sphinx
Package sphinx implements the Katzenpost parameterized Sphinx Packet Format.
|
Package sphinx implements the Katzenpost parameterized Sphinx Packet Format. |
|
sphinx/commands
Package commands implements the Sphinx Packet Format per-hop routing info commands.
|
Package commands implements the Sphinx Packet Format per-hop routing info commands. |
|
sphinx/constants
Package constants contains the Sphinx Packet Format constants for the Katzenpost parameterization.
|
Package constants contains the Sphinx Packet Format constants for the Katzenpost parameterization. |
|
sphinx/internal/crypto
Package crypto provides the Katzenpost parameterization of the Sphinx Packet Format cryptographic operations.
|
Package crypto provides the Katzenpost parameterization of the Sphinx Packet Format cryptographic operations. |
|
sphinx/path
Package path provides routines for path selection.
|
Package path provides routines for path selection. |
|
thwack
Package thwack provides a trivial text based management protocol.
|
Package thwack provides a trivial text based management protocol. |
|
wire
Package wire implements the Katzenpost wire protocol.
|
Package wire implements the Katzenpost wire protocol. |
|
worker
Package worker provides background worker tasks.
|
Package worker provides background worker tasks. |
|
Package ratchet originally written by AGL to implement the axolotl ratchet (designed by Trevor Perrin) for the Pond messaging system but then modified for a Katzenpost decryption mix network messaging system.
|
Package ratchet originally written by AGL to implement the axolotl ratchet (designed by Trevor Perrin) for the Pond messaging system but then modified for a Katzenpost decryption mix network messaging system. |
|
memspool
|
|
|
Package minclient provides a minimal Katzenpost client.
|
Package minclient provides a minimal Katzenpost client. |
|
panda
|
|
|
reunion
|
|
|
client
Package client provides the Reunion protocol client.
|
Package client provides the Reunion protocol client. |
|
commands
Package commands provides commands used by the client and server.
|
Package commands provides commands used by the client and server. |
|
crypto
Package crypto provides core cryptographic functionality for the Reunion protocol.
|
Package crypto provides core cryptographic functionality for the Reunion protocol. |
|
epochtime
Package epochtime provides the Reunion protocol epoch timer.
|
Package epochtime provides the Reunion protocol epoch timer. |
|
epochtime/katzenpost
Package katzenpost provides the Reunion protocol Katzenpost epoch timer.
|
Package katzenpost provides the Reunion protocol Katzenpost epoch timer. |
|
server
Package server provides the Reunion protocol server.
|
Package server provides the Reunion protocol server. |
|
transports/http
Package http provides the client transport for Reunion DB queries over http.
|
Package http provides the client transport for Reunion DB queries over http. |
|
transports/katzenpost
Package katzenpost provides the client ACN transport for Reunion DB queries on a katzenpost decryption mix network.
|
Package katzenpost provides the client ACN transport for Reunion DB queries on a katzenpost decryption mix network. |
|
Package server provides the Katzenpost server.
|
Package server provides the Katzenpost server. |
|
cborplugin
Package cborplugin is a plugin system allowing mix network services to be added in any language.
|
Package cborplugin is a plugin system allowing mix network services to be added in any language. |
|
config
Package config provides the Katzenpost server configuration.
|
Package config provides the Katzenpost server configuration. |
|
internal/constants
Package constants defines internal constants for the Katzenpost server.
|
Package constants defines internal constants for the Katzenpost server. |
|
internal/cryptoworker
Package cryptoworker implements the Katzenpost Sphinx crypto worker.
|
Package cryptoworker implements the Katzenpost Sphinx crypto worker. |
|
internal/debug
Package debug implements useful helper routines to aid debugging.
|
Package debug implements useful helper routines to aid debugging. |
|
internal/decoy
Package decoy implements the decoy traffic source and sink.
|
Package decoy implements the decoy traffic source and sink. |
|
internal/glue
Package glue implements the glue structure that ties all the internal subpackages together.
|
Package glue implements the glue structure that ties all the internal subpackages together. |
|
internal/incoming
Package incoming implements the incoming connection support.
|
Package incoming implements the incoming connection support. |
|
internal/mixkey
Package mixkey provides persistent mix keys and associated utilities.
|
Package mixkey provides persistent mix keys and associated utilities. |
|
internal/outgoing
Package outgoing implements the outgoing connection support.
|
Package outgoing implements the outgoing connection support. |
|
internal/packet
Package packet implements the Katzenpost server side packet structure.
|
Package packet implements the Katzenpost server side packet structure. |
|
internal/pki
Package pki implements the server PKI handler.
|
Package pki implements the server PKI handler. |
|
internal/pkicache
Package pkicache provides a rudimentary cached representation of a PKI Document suitable for server use.
|
Package pkicache provides a rudimentary cached representation of a PKI Document suitable for server use. |
|
internal/provider
Package provider implements the Katzenpost sever provider.
|
Package provider implements the Katzenpost sever provider. |
|
internal/provider/kaetzchen
Package kaetzchen implements support for provider side auto-responder agents.
|
Package kaetzchen implements support for provider side auto-responder agents. |
|
internal/scheduler
Package scheduler implements the Katzenpost server scheduler.
|
Package scheduler implements the Katzenpost server scheduler. |
|
internal/sqldb
Package sqldb interfaces the Katzenpost server with a SQL database.
|
Package sqldb interfaces the Katzenpost server with a SQL database. |
|
spool
Package spool defines the Katzenpost server user message spool abstract interface.
|
Package spool defines the Katzenpost server user message spool abstract interface. |
|
spool/boltspool
Package boltspool implements the Katzenpost server user message spool with a simple boltdb based backend.
|
Package boltspool implements the Katzenpost server user message spool with a simple boltdb based backend. |
|
userdb
Package userdb defines the Katzenpost server user database abstract interface.
|
Package userdb defines the Katzenpost server user database abstract interface. |
|
userdb/boltuserdb
Package boltuserdb implements the Katzenpost server user database with a simple boltdb based backend.
|
Package boltuserdb implements the Katzenpost server user database with a simple boltdb based backend. |
|
userdb/externuserdb
Package externuserdb implements the Katzenpost server user database with http calls to a external authorization source (expected to run in localhost).
|
Package externuserdb implements the Katzenpost server user database with http calls to a external authorization source (expected to run in localhost). |
|
server_plugins
|
|