For the application, kpclientd and gateway arrangement, see client software and configuration. kpclientd verifies consensus documents using the directory authority protocol.
Thin client specification
Abstract
This document describes the design of the new Katzenpost mixnet thin client. In particular we discuss its multiplexing and privilege-separation design elements as well as the protocol used by the thin-client library.
Introduction
A Katzenpost mixnet client has several responsibilities at a minimum:
-
composing Sphinx packets
-
decrypting SURB replies
-
sending and receiving Noise protocol messages
-
keeping up to date with the latest PKI document
The thin-client library enables applications to talk with the connector daemon and in that way interact with the mix network. The library itself does not do any mixnet-related cryptography since that is already handled by the thin-client daemon. In particular, the daemon strips cryptographic signatures from the PKI document before passing data to clients using the connector library. Noise- and Sphinx-related cryptography are also handled by the daemon.
Thin-client library and daemon protocol
The thin-client daemon protocol uses a local network socket, either a Unix domain socket or TCP.
Messages
There are two protocol message types, both CBOR encoded.
-
The client sends
Requestmessages. -
The daemon sends
Responsemessages.
Messages are length-prefixed CBOR blobs, that is, a blob is prefixed with a big-endian unsigned four-byte integer (uint32) that encodes the blob length.
Protocol description
The protocol has two phases.
Phase 1
Upon connecting to the daemon socket, the thin client waits for two messages.
-
First message
-
The
is_statusfield must be set to true -
The
is_connectedfield must indicate whether or not the daemon has a mixnet PQ Noise protocol connection to a mixnet gateway node.
-
-
Second message
-
The message contains the PKI document in its
payloadfield. This marks the end of the initial connection sequence. -
The PKI document is stripped of cryptographic signatures as noted above.
-
Phase 2
-
The thin client may send
Requestmessages to the daemon, which encapsulates the provided payload in a Sphinx packet and sends it to the gateway node. -
The daemon may send
Responsemessages to the client at any time during this phase.Responsemessages may communicate a connection status change, a new PKI document, or a message-sent or message-reply event.