Components

Components and configuration of the Katzenpost mixnet

Components and configuration of the Katzenpost mixnet

Table of Contents

Understanding the Katzenpost components
Directory authorities (dirauths)
Mix nodes
Gateway nodes
Service nodes
Clients
Configuring Katzenpost
Configuring directory authorities
Configuring mix nodes
Configuring gateway nodes
Configuring service nodes

This section of the Katzenpost technical documentation provides an introduction to the software components that make up Katzenpost and guidance on how to configure each component. The intended reader is a system administrator who wants to implement a working, production Katzenpost network.

For information about the theory and design of this software, see ???. For a quickly deployable, non-production test network (primarily for use by developers), see Configuring Katzenpost.

Understanding the Katzenpost components

The core of Katzenpost consists of two program executables, dirauth and server. Running the dirauth commmand runs a directory authority node, or dirauth, that functions as part of the mixnet's public-key infrastructure (PKI). Running the server runs either a mix node, a gateway node, or a service node, depending on the configuration. Configuration settings are provided in an associated katzenpost-authority.toml or katzenpost.toml file respectively.

In addition to the server components, Katzenpost also supports connections to client applications hosted externally to the mix network and communicating with it through gateway nodes.

A model mix network is shown in Figure 1.

Figure 1. The pictured element types correspond to discrete client and server programs that Katzenpost requires to function.

The pictured element types correspond to discrete client and server programs that Katzenpost requires to function.

The mix network contains an n-layer topology of mix-nodes, with three nodes per layer in this example. Sphinx packets traverse the network in one direction only. The gateway nodes allow clients to interact with the mix network. The service nodes provide mix network services that mix network clients can interact with. All messages sent by clients are handed to a connector daemon hosted on the client system, passed across the Internet to a gateway, and then relayed to a service node by way of the nine mix nodes. The service node sends its reply back across the mix-node layers to a gateway, which transmits it across the Internet to be received by the targeted client. The mix, gateway, and service nodes send mix descriptors to the dirauths and retrieve a consensus document from them, described below.

In addition to the server components, Katzenpost supports connections to client applications hosted externally to the mix network and communicating with it through gateway nodes and, in some cases, a client connector.

Directory authorities (dirauths)

Dirauths compose the decentralized public key infrastructure (PKI) that serves as the root of security for the entire mix network. Clients, mix nodes, gateways nodes, and service nodes rely on the PKI/dirauth system to maintain and sign an up-to-date consensus document, providing a view of the network including connection information and public cryptographic key materials and signatures.

Every 20 minutes (the current value for an epoch), each mix, gateway, and service node signs a mix descriptor and uploads it to the dirauths. The dirauths then vote on a new consensus document. If consensus is reached, each dirauth signs the document. Clients and nodes download the document as needed and verify the signatures. Consensus fails when 1/2 + 1 nodes fail, which yields greater fault tolerance than, for example, Byzantine Fault Tolerance, which fails when 1/3 + 1 of the nodes fail.

The PKI signature scheme is fully configurable by the dirauths. Our recommendation is to use a hybrid signature scheme consisting of classical Ed25519 and the post-quantum, stateless, hash-based signature scheme known as Sphincs+ (with the parameters: "sphincs-shake-256f"), which is designated in Katzenpost configurations as "Ed25519 Sphincs+". Examples are provided below.

Mix nodes

The mix node is the fundamental building block of the mix network.

Katzenpost mix nodes are arranged in a layered topology to achieve the best levels of anonymity and ease of analysis while being flexible enough to scale with traffic demands.

Gateway nodes

Gateway nodes provide external client access to the mix network. Because gateways are uniquely positioned to identify clients, they are designed to have as little information about client behavior as possible. Gateways are randomly selected and have no persistent relationship with clients and no knowledge of whether a client's packets are decoys or not. When client traffic through a gateway is slow, the node additionally generates decoy traffic.

Service nodes

Service nodes provide functionality requested by clients. They are logically positioned at the deepest point of the mix network, with incoming queries and outgoing replies both needing to traverse all n layers of mix nodes. A service node's functionality may involve storing messages, publishing information outside of the mixnet, interfacing with a blockchain node, and so on. Service nodes also process decoy packets.

Clients

Client applications should be designed so that the following conditions are met:

  • Separate service requests from a client are unlinkable. Repeating the same request may be lead to linkability.

  • Service nodes and clients have no persistent relationship.

  • Cleints generate a stream of packets addressed to random or pseudorandom services regardless of whether a real service request is being made. Most of these packets will be decoy traffic.

  • Traffic from a client to a service node must be correctly coupled with decoy traffic. This can mean that the service node is chosen independently from traffic history, or that the transmitted packet replaces a decoy packet that was meant to go to the desired service.

Katzenpost currently includes several client applications. All applications make extensive use of Sphinx single-use reply blocks (SURBs), which enable service nodes to send replies without knowing the location of the client. Newer clients require a connection through the client connector, which provides multiplexing and privilege separation with a consequent reduction in processing overhead. These clients also implement the Pigeonhole storage and BACAP protocols detailed in Place-holder for research paper link.

The following client applications are available.

Table 1. Katzenpost clients

Name

Needs connector

Description

Code

Ping

no

The mix network equivalent of an ICMP ping utility, used for network testing.

GitHub: ping

Katzen

no

A text chat client with file-transfer support.

GitHub: katzen

Status

yes

An HTML page containing status information about the mix network.

GitHub: status

Worldmap

yes

An HTML page with a world map showing geographic locations of mix network nodes.

GitHub: worldmap


Configuring Katzenpost

This section documents the configuration parameters for each type of Katzenpost server node. Each node has its own configuration file in TOML format.

Configuring directory authorities

The following configuration is drawn from the reference implementation in katzenpost/docker/dirauth_mixnet/auth1/authority.toml. In a real-world mixnet, the component hosts would not be sharing a single IP address. For more information about the test mixnet, see ???.

Table 2. Directory authority (dirauth) configuration sections

Dirauth: Server section

Dirauth: Authorities section

Dirauth: Logging section

Dirauth: Parameters section

Dirauth: Debug section

Dirauth: Mixes sections

Dirauth: GatewayNodes section

Dirauth: ServiceNodes sections

Dirauth: Topology section

Dirauth: SphinxGeometry section


Dirauth: Server section

The Server section configures mandatory basic parameters for each directory authority.

[Server]
    Identifier = "auth1"
    WireKEMScheme = "xwing"
    PKISignatureScheme = "Ed25519 Sphincs+"
    Addresses = ["tcp://127.0.0.1:30001"]
    DataDir = "/dirauth_mixnet/auth1"

  • Identifier

    Specifies the human-readable identifier for a node, and must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • WireKEMScheme

    Specifies the key encapsulation mechanism (KEM) scheme for the PQ Noise-based wire protocol (link layer) that nodes use to communicate with each other. PQ Noise is a post-quantum variation of the Noise protocol framework, which algebraically transforms ECDH handshake patterns into KEM encapsulate/decapsulate operations.

    This configuration option supports the optional use of hybrid post-quantum cryptography to strengthen security. The following KEM schemes are supported:

    • Classical: "x25519", "x448"

      [Note]Note

      X25519 and X448 are actually non-interactive key-exchanges (NIKEs), not KEMs. Katzenpost uses a hashed ElGamal cryptographic construction to convert them from NIKEs to KEMs.

    • Post-quantum: "mlkem768","sntrup4591761", "frodo640shake", "mceliece348864", "mceliece348864f", "mceliece460896", "mceliece460896f", "mceliece6688128", "mceliece6688128f", "mceliece6960119", "mceliece6960119f", "mceliece8192128", "mceliece8192128f", "CTIDH511", "CTIDH512", "CTIDH1024", "CTIDH2048",

    • Hybrid post-quantum: "xwing", "Kyber768-X25519", "MLKEM768-X25519", "MLKEM768-X448", "FrodoKEM-640-SHAKE-X448", "sntrup4591761-X448", "mceliece348864-X25519", "mceliece348864f-X25519", "mceliece460896-X25519", "mceliece460896f-X25519", "mceliece6688128-X25519", "mceliece6688128f-X25519", "mceliece6960119-X25519", "mceliece6960119f-X25519", "mceliece8192128-X25519", "mceliece8192128f-X25519", "CTIDH512-X25519", "CTIDH512-X25519"

    Type: string

    Required: Yes

  • PKISignatureScheme

    Specifies the cryptographic signature scheme which will be used by all components of the mix network when interacting with the PKI system. Mix nodes sign their descriptors using this signature scheme, and dirauth nodes similarly sign PKI documents using the same scheme.

    The following signature schemes are supported: "ed25519", "ed448", "Ed25519 Sphincs+", "Ed448-Sphincs+", "Ed25519-Dilithium2", "Ed448-Dilithium3"

    Type: string

    Required: Yes

  • Addresses

    Specifies a list of one or more address URLs in a format that contains the transport protocol, IP address, and port number that the node will bind to for incoming connections. Katzenpost supports URLs with that start with either "tcp://" or "quic://" such as: ["tcp://192.168.1.1:30001"] and ["quic://192.168.1.1:40001"].

    Type: []string

    Required: Yes

  • DataDir

    Specifies the absolute path to a node's state directory. This is where persistence.db is written to disk and where a node stores its cryptographic key materials when started with the "-g" command-line option.

    Type: string

    Required: Yes

Dirauth: Authorities section

An Authorities section is configured for each peer authority. We recommend using TOML's style for multi-line quotations for key materials.

[[Authorities]]
    Identifier = "auth1"
    IdentityPublicKey = """
-----BEGIN ED25519 PUBLIC KEY-----
dYpXpbozjFfqhR45ZC2q97SOOsXMANdHaEdXrP42CJk=
-----END ED25519 PUBLIC KEY-----
"""
    PKISignatureScheme = "Ed25519"
    LinkPublicKey = """
-----BEGIN XWING PUBLIC KEY-----
ooQBPYNdmfwnxXmvnljPA2mG5gWgurfHhbY87DMRY2tbMeZpinJ5BlSiIecprnmm
QqxcS9o36IS62SVMlOUkw+XEZGVvc9wJqHpgEgVJRAs1PCR8cUAdM6QIYLWt/lkf
SPKDCtZ3GiSIOzMuaglo2tarIPEv1AY7r9B0xXOgSKMkGyBkCfw1VBZf46MM26NL
...
gHtNyQJnXski52O03JpZRIhR40pFOhAAcMMAZDpMTVoxlcdR6WA4SlBiSceeJBgY
Yp9PlGhCimx9am99TrdLoLCdTHB6oowt8tss3POpIOxaSlguyeym/sBhkUrnXOgN
ldMtDsvvc9KUfE4I0+c+XQ==
-----END XWING PUBLIC KEY-----
    """
    WireKEMScheme = "xwing"
    Addresses = ["tcp://127.0.0.1:30001"]

  • Identifier

    Specifies the human-readable identifier for the node which must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • IdentityPublicKey

    String containing the node's public identity key in PEM format. IdentityPublicKey is the node's permanent identifier and is used to verify cryptographic signatures produced by its private identity key.

    Type: string

    Required: Yes

  • PKISignatureScheme

    Specifies the cryptographic signature scheme used by all directory authority nodes. PKISignatureScheme must match the scheme specified in the Server section of the configuration.

    Type: string

    Required: Yes

  • LinkPublicKey

    String containing the peer's public link-layer key in PEM format. LinkPublicKey must match the specified WireKEMScheme.

    Type: string

    Required: Yes

  • WireKEMScheme

    Specifies the key encapsulation mechanism (KEM) scheme for the PQ Noise-based wire protocol (link layer) that nodes use to communicate with each other. PQ Noise is a post-quantum variation of the Noise protocol framework, which algebraically transforms ECDH handshake patterns into KEM encapsulate/decapsulate operations.

    This configuration option supports the optional use of hybrid post-quantum cryptography to strengthen security. The following KEM schemes are supported:

    • Classical: "x25519", "x448"

      [Note]Note

      X25519 and X448 are actually non-interactive key-exchanges (NIKEs), not KEMs. Katzenpost uses a hashed ElGamal cryptographic construction to convert them from NIKEs to KEMs.

    • Post-quantum: "mlkem768","sntrup4591761", "frodo640shake", "mceliece348864", "mceliece348864f", "mceliece460896", "mceliece460896f", "mceliece6688128", "mceliece6688128f", "mceliece6960119", "mceliece6960119f", "mceliece8192128", "mceliece8192128f", "CTIDH511", "CTIDH512", "CTIDH1024", "CTIDH2048",

    • Hybrid post-quantum: "xwing", "Kyber768-X25519", "MLKEM768-X25519", "MLKEM768-X448", "FrodoKEM-640-SHAKE-X448", "sntrup4591761-X448", "mceliece348864-X25519", "mceliece348864f-X25519", "mceliece460896-X25519", "mceliece460896f-X25519", "mceliece6688128-X25519", "mceliece6688128f-X25519", "mceliece6960119-X25519", "mceliece6960119f-X25519", "mceliece8192128-X25519", "mceliece8192128f-X25519", "CTIDH512-X25519", "CTIDH512-X25519"

    Type: string

    Required: Yes

  • Addresses

    Specifies a list of one or more address URLs in a format that contains the transport protocol, IP address, and port number that the node will bind to for incoming connections. Katzenpost supports URLs with that start with either "tcp://" or "quic://" such as: ["tcp://192.168.1.1:30001"] and ["quic://192.168.1.1:40001"].

    Type: []string

    Required: Yes

Dirauth: Logging section

The Logging configuration section controls logging behavior across Katzenpost.

[Logging]
                Disable = false
                File = "katzenpost.log"
                Level = "INFO"

  • Disable

    If true, logging is disabled.

    Type: bool

    Required: No

  • File

    Specifies the log file. If omitted, stdout is used.

    An absolute or relative file path can be specified. A relative path is relative to the DataDir specified in the Server section of the configuration.

    Type: string

    Required: No

  • Level

    Supported logging level values are ERROR | WARNING | NOTICE |INFO | DEBUG.

    Type: string

    Required: No

    [Warning]Warning

    The DEBUG log level is unsafe for production use.

Dirauth: Parameters section

The Parameters section contains the network parameters.

[Parameters]
    SendRatePerMinute = 0
    Mu = 0.005
    MuMaxDelay = 1000
    LambdaP = 0.001
    LambdaPMaxDelay = 1000
    LambdaL = 0.0005
    LambdaLMaxDelay = 1000
    LambdaD = 0.0005
    LambdaDMaxDelay = 3000
    LambdaM = 0.0005
    LambdaG = 0.0
    LambdaMMaxDelay = 100
    LambdaGMaxDelay = 100

  • SendRatePerMinute

    Specifies the maximum allowed rate of packets per client per gateway node. Rate limiting is done on the gateway nodes.

    Type: uint64

    Required: Yes

  • Mu

    Specifies the inverse of the mean of the exponential distribution from which the Sphinx packet per-hop mixing delay will be sampled.

    Type: float64

    Required: Yes

  • MuMaxDelay

    Specifies the maximum Sphinx packet per-hop mixing delay in milliseconds.

    Type: uint64

    Required: Yes

  • LambdaP

    Specifies the inverse of the mean of the exponential distribution that clients sample to determine the time interval between sending messages, whether actual messages from the FIFO egress queue or decoy messages if the queue is empty.

    Type: float64

    Required: Yes

  • LambdaPMaxDelay

    Specifies the maximum send delay interval for LambdaP in milliseconds.

    Type: uint64

    Required: Yes

  • LambdaL

    Specifies the inverse of the mean of the exponential distribution that clients sample to determine the delay interval between loop decoys.

    Type: float64

    Required: Yes

  • LambdaLMaxDelay

    Specifies the maximum send delay interval for LambdaL in milliseconds.

    Type: uint64

    Required: Yes

  • LambdaD

    LambdaD is the inverse of the mean of the exponential distribution that clients sample to determine the delay interval between decoy drop messages.

    Type: float64

    Required: Yes

  • LambdaDMaxDelay

    Specifies the maximum send interval in for LambdaD in milliseconds.

    Type: uint64

    Required: Yes

  • LambdaM

    LambdaM is the inverse of the mean of the exponential distribution that mix nodes sample to determine the delay between mix loop decoys.

    Type: float64

    Required: Yes

  • LambdaG

    LambdaG is the inverse of the mean of the exponential distribution that gateway nodes to select the delay between gateway node decoys.

    [Warning]Warning

    Do not set this value manually in the TOML configuration file. The field is used internally by the dirauth server state machine.

    Type: float64

    Required: Yes

  • LambdaMMaxDelay

    Specifies the maximum delay for LambdaM in milliseconds.

    Type: uint64

    Required: Yes

  • LambdaGMaxDelay

    Specifies the maximum delay for LambdaG in milliseconds.

    Type: uint64

    Required: Yes

Dirauth: Debug section

[Debug]
    Layers = 3
    MinNodesPerLayer = 1
    GenerateOnly = false

  • Layers

    Specifies the number of non-service-provider layers in the network topology.

    Type: int

    Required: Yes

  • MinNodesrPerLayer

    Specifies the minimum number of nodes per layer required to form a valid consensus document.

    Type: int

    Required: Yes

  • GenerateOnly

    If true, the server halts and cleans up the data directory immediately after long-term key generation.

    Type: bool

    Required: No

Dirauth: Mixes sections

The Mixes configuration sections list mix nodes that are known to the authority.

[[Mixes]]
    Identifier = "mix1"
    IdentityPublicKeyPem = "../mix1/identity.public.pem"

[[Mixes]]
    Identifier = "mix2"
    IdentityPublicKeyPem = "../mix2/identity.public.pem"

[[Mixes]]
    Identifier = "mix3"
    IdentityPublicKeyPem = "../mix3/identity.public.pem"

  • Identifier

    Specifies the human-readable identifier for a mix node, and must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • IdentityPublicKeyPem

    Path and file name of a mix node's public identity signing key, also known as the identity key, in PEM format.

    Type: string

    Required: Yes

Dirauth: GatewayNodes section

The GatewayNodes sections list gateway nodes that are known to the authority.

[[GatewayNodes]]
    Identifier = "gateway1"
    IdentityPublicKeyPem = "../gateway1/identity.public.pem"

  • Identifier

    Specifies the human-readable identifier for a gateway node, and must be unique per mixnet. Identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • IdentityPublicKeyPem

    Path and file name of a gateway node's public identity signing key, also known as the identity key, in PEM format.

    Type: string

    Required: Yes

Dirauth: ServiceNodes sections

The ServiceNodes sections list service nodes that are known to the authority.

[[ServiceNodes]]
    Identifier = "servicenode1"
    IdentityPublicKeyPem = "../servicenode1/identity.public.pem"

  • Identifier

    Specifies the human-readable identifier for a service node, and must be unique per mixnet. Identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • IdentityPublicKeyPem

    Path and file name of a service node's public identity signing key, also known as the identity key, in PEM format.

    Type: string

    Required: Yes

Dirauth: Topology section

The Topology section defines the layers of the mix network and the mix nodes in each layer.

[Topology]
                    
    [[Topology.Layers]]
    
        [[Topology.Layers.Nodes]]
            Identifier = "mix1"
            IdentityPublicKeyPem = "../mix1/identity.public.pem"
    
    [[Topology.Layers]]
    
        [[Topology.Layers.Nodes]]
            Identifier = "mix2"
            IdentityPublicKeyPem = "../mix2/identity.public.pem"
    
    [[Topology.Layers]]
    
        [[Topology.Layers.Nodes]]
            Identifier = "mix3"
            IdentityPublicKeyPem = "../mix3/identity.public.pem"

  • Identifier

    Specifies the human-readable identifier for a node, and must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

  • IdentityPublicKeyPem

    Path and file name of a mix node's public identity signing key, also known as the identity key, in PEM format.

    Type: string

    Required: Yes

Dirauth: SphinxGeometry section

Sphinx is an encrypted nested-packet format designed primarily for mixnets. The original Sphinx paper described a non-interactive key exchange (NIKE) employing classical encryption. The Katzenpost implementation strongly emphasizes configurability, supporting key encapsulation mechanisms (KEMs) as well as NIKEs, and enabling the use of either classical or hybrid post-quantum cryptography. Hybrid constructions offset the newness of post-quantum algorithms by offering heavily tested classical algorithms as a fallback.

[Note]Note

Sphinx, the nested-packet format, should not be confused with Sphincs or Sphincs+, which are post-quantum signature schemes.

Katzenpost Sphinx also relies on the following classical cryptographic primitives:

  • CTR-AES256, a stream cipher

  • HMAC-SHA256, a message authentication code (MAC) function

  • HKDF-SHA256, a key derivation function (KDF)

  • AEZv5, a strong pseudorandom permutation (SPRP)

All dirauths must be configured to use the same SphinxGeometry parameters. Any geometry not advertised by the PKI document will fail. Each dirauth publishes the hash of its SphinxGeometry parameters in the PKI document for validation by its peer dirauths.

The SphinxGeometry section defines parameters for the Sphinx encrypted nested-packet format used internally by Katzenpost.

[Warning]Warning

The values in the SphinxGeometry configuration section must be programmatically generated by gensphinx. Many of the parameters are interdependent and cannot be individually modified. Do not modify the these values by hand.

The settings in this section are generated by the gensphinx utility, which computes the Sphinx geometry based on the following user-supplied directives:

  • The number of mix node layers (not counting gateway and service nodes)

  • The length of the application-usable packet payload

  • The selected NIKE or KEM scheme

The output in TOML should then be pasted unchanged into the node's configuration file, as shown below. For more information, see ???.

[SphinxGeometry]
                PacketLength = 3082
                NrHops = 5
                HeaderLength = 476
                RoutingInfoLength = 410
                PerHopRoutingInfoLength = 82
                SURBLength = 572
                SphinxPlaintextHeaderLength = 2
                PayloadTagLength = 32
                ForwardPayloadLength = 2574
                UserForwardPayloadLength = 2000
                NextNodeHopLength = 65
                SPRPKeyMaterialLength = 64
                NIKEName = "x25519"
                KEMName = ""

  • PacketLength

    The length of a Sphinx packet in bytes.

    Type: int

    Required: Yes

  • NrHops

    The number of hops a Sphinx packet takes through the mixnet. Because packet headers hold destination information for each hop, the size of the header increases linearly with the number of hops.

    Type: int

    Required: Yes

  • HeaderLength

    The total length of the Sphinx packet header in bytes.

    Type: int

    Required: Yes

  • RoutingInfoLength

    The total length of the routing information portion of the Sphinx packet header.

    Type: int

    Required: Yes

  • PerHopRoutingInfoLength

    The length of the per-hop routing information in the Sphinx packet header.

    Type: int

    Required: Yes

  • SURBLength

    The length of a single-use reply block (SURB).

    Type: int

    Required: Yes

  • SphinxPlaintextHeaderLength

    The length of the plaintext Sphinx packet header.

    Type: int

    Required: Yes

  • PayloadTagLength

    The length of the payload tag.

    Type: int

    Required: Yes

  • ForwardPayloadLength

    The total size of the payload.

    Type: int

    Required: Yes

  • UserForwardPayloadLength

    The size of the usable payload.

    Type: int

    Required: Yes

  • NextNodeHopLength

    The NextNodeHopLength is derived from the largest routing-information block that we expect to encounter. Other packets have NextNodeHop + NodeDelay sections, or a Recipient section, both of which are shorter.

    Type: int

    Required: Yes

  • SPRPKeyMaterialLength

    The length of the strong pseudo-random permutation (SPRP) key.

    Type: int

    Required: Yes

  • NIKEName

    The name of the non-interactive key exchange (NIKE) scheme used by Sphinx packets.

    NIKEName and KEMName are mutually exclusive.

    Type: string

    Required: Yes

  • KEMName

    The name of the key encapsulation mechanism (KEM) used by Sphinx packets.

    NIKEName and KEMName are mutually exclusive.

    Type: string

    Required: Yes

Configuring mix nodes

The following configuration is drawn from the reference implementation in katzenpost/docker/dirauth_mixnet/mix1/katzenpost.toml. In a real-world mixnet, the component hosts would not be sharing a single IP address. For more information about the test mixnet, see ???.

Table 3. Mix node configuration sections

Mix node: Server section

Mix node: Logging section

Mix node: PKI section

Mix node: Management section

Mix node: SphinxGeometry section

Mix node: Debug section


Mix node: Server section

The Server section configures mandatory basic parameters for each server node.

[Server]
  Identifier = "mix1"
  WireKEM = "xwing"
  PKISignatureScheme = "Ed25519"
  Addresses = ["127.0.0.1:30008"]
  OnlyAdvertiseAltAddresses = false
  MetricsAddress = "127.0.0.1:30009"
  DataDir = "/dirauth_mixnet/mix1"
  IsGatewayNode = false
  IsServiceNode = false
  [Server.AltAddresses]

  • Identifier

    Specifies the human-readable identifier for a node, and must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • WireKEM

    WireKEM specifies the key encapsulation mechanism (KEM) scheme for the PQ Noise-based wire protocol (link layer) that nodes use to communicate with each other. PQ Noise is a post-quantum variation of the Noise protocol framework, which algebraically transforms ECDH handshake patterns into KEM encapsulate/decapsulate operations.

    This configuration option supports the optional use of hybrid post-quantum cryptography to strengthen security. The following KEM schemes are supported:

    • Classical: "x25519", "x448"

      [Note]Note

      X25519 and X448 are actually non-interactive key-exchanges (NIKEs), not KEMs. Katzenpost uses a hashed ElGamal cryptographic construction to convert them from NIKEs to KEMs.

    • Post-quantum: "mlkem768","sntrup4591761", "frodo640shake", "mceliece348864", "mceliece348864f", "mceliece460896", "mceliece460896f", "mceliece6688128", "mceliece6688128f", "mceliece6960119", "mceliece6960119f", "mceliece8192128", "mceliece8192128f", "CTIDH511", "CTIDH512", "CTIDH1024", "CTIDH2048",

    • Hybrid post-quantum: "xwing", "Kyber768-X25519", "MLKEM768-X25519", "MLKEM768-X448", "FrodoKEM-640-SHAKE-X448", "sntrup4591761-X448", "mceliece348864-X25519", "mceliece348864f-X25519", "mceliece460896-X25519", "mceliece460896f-X25519", "mceliece6688128-X25519", "mceliece6688128f-X25519", "mceliece6960119-X25519", "mceliece6960119f-X25519", "mceliece8192128-X25519", "mceliece8192128f-X25519", "CTIDH512-X25519", "CTIDH512-X25519"

    Type: string

    Required: Yes

  • PKISignatureScheme

    Specifies the cryptographic signature scheme that will be used by all components of the mix network when interacting with the PKI system. Mix nodes sign their descriptors using this signature scheme, and dirauth nodes similarly sign PKI documents using the same scheme.

    The following signature schemes are supported:

    • Classical: "ed25519", "ed448"

    • Hybrid post-quantum: "Ed25519 Sphincs+", "Ed448-Sphincs+", "Ed25519-Dilithium2", "Ed448-Dilithium3"

    Type: string

    Required: Yes

  • Addresses

    Specifies a list of one or more address URLs in a format that contains the transport protocol, IP address, and port number that the server will bind to for incoming connections. Katzenpost supports URLs with that start with either "tcp://" or "quic://" such as: ["tcp://192.168.1.1:30001"] and ["quic://192.168.1.1:40001"].

    Type: []string

    Required: Yes

  • BindAddresses

    If true, allows setting of listener addresses that the server will bind to and accept connections on. These addresses are not advertised in the PKI.

    Type: bool

    Required: No

  • MetricsAddress

    Specifies the address/port to bind the Prometheus metrics endpoint to.

    Type: string

    Required: No

  • DataDir

    Specifies the absolute path to a node's state directory. This is where persistence.db is written to disk and where a node stores its cryptographic key materials when started with the "-g" commmand-line option.

    Type: string

    Required: Yes

  • IsGatewayNode

    If true, the server is a gateway node.

    Type: bool

    Required: No

  • IsServiceNode

    If true, the server is a service node.

    Type: bool

    Required: No

Mix node: Logging section

The Logging configuration section controls logging behavior across Katzenpost.

[Logging]
                Disable = false
                File = "katzenpost.log"
                Level = "INFO"

  • Disable

    If true, logging is disabled.

    Type: bool

    Required: No

  • File

    Specifies the log file. If omitted, stdout is used.

    An absolute or relative file path can be specified. A relative path is relative to the DataDir specified in the Server section of the configuration.

    Type: string

    Required: No

  • Level

    Supported logging level values are ERROR | WARNING | NOTICE |INFO | DEBUG.

    Type: string

    Required: No

    [Warning]Warning

    The DEBUG log level is unsafe for production use.

Mix node: PKI section

The PKI section contains the directory authority configuration for a mix, gateway, or service node.

[PKI]
[PKI.dirauth]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth1"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
tqN6tpOVotHWXKCszVn2kS7vAZjQpvJjQF3Qz/Qwhyg=
-----END ED25519 PUBLIC KEY-----
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """-----BEGIN XWING PUBLIC KEY-----
JnJ8ztQEIjAkKJcpuZvJAdkWjBim/5G5d8yoosEQHeGJeeBqNPdm2AitUbpiQPcd
tNCo9DxuC9Ieqmsfw0YpV6AtOOsaInA6QnHDYcuBfZcQL5MU4+t2TzpBZQYlrSED
hPCKrAG+8GEUl6akseG371WQzEtPpEWWCJCJOiS/VDFZT7eKrldlumN6gfiB84sR
...
arFh/WKwYJUj+aGBsFYSqGdzC6MdY4x/YyFe2ze0MJEjThQE91y1d/LCQ3Sb7Ri+
u6PBi3JU2qzlPEejDKwK0t5tMNEAkq8iNrpRTdD/hS0gR+ZIN8Z9QKh7Xf94FWG2
H+r8OaqImQhgHabrWRDyLg==
-----END XWING PUBLIC KEY-----
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30001"]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth2"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
O51Ty2WLu4C1ETMa29s03bMXV72gnjJfTfwLV++LVBI=
-----END ED25519 PUBLIC KEY-----	
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """-----BEGIN XWING PUBLIC KEY-----
TtQkg2XKUnY602FFBaPJ+zpN0Twy20cwyyFxh7FNUjaXA9MAJXs0vUwFbJc6BjYv
f+olKnlIKFSmDvcF74U6w1F0ObugwTNKNxeYKPKhX4FiencUbRwkHoYHdtZdSctz
TKy08qKQyCAccqCRpdo6ZtYXPAU+2rthjYTOL7Zn+7SHUKCuJClcPnvEYjVcJxtZ
...
ubJIe5U4nMJbBkOqr7Kq6niaEkiLODa0tkpB8tKMYTMBdcYyHSXCzpo7U9sb6LAR
HktiTBDtRXviu2vbw7VRXhkMW2kjYZDtReQ5sAse04DvmD49zgTp1YxYW+wWFaL3
37X7/SNuLdHX4PHZXIWHBQ==
-----END XWING PUBLIC KEY-----	
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30002"]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth3"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
zQvydRYJq3npeLcg1NqIf+SswEKE5wFmiwNsI9Z1whQ=
-----END ED25519 PUBLIC KEY-----
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """
-----BEGIN XWING PUBLIC KEY-----
OYK9FiC53xwZ1VST3jDOO4tR+cUMSVRSekmigZMChSjDCPZbKut8TblxtlUfc/yi
Ugorz4NIvYPMWUt3QPwS2UWq8/HMWXNGPUiAevg12+oV+jOJXaJeCfY24UekJnSw
TNcdGaFZFSR0FocFcPBBnrK1M2B8w8eEUKQIsXRDM3x/8aRIuDif+ve8rSwpgKeh
...
OdVD3yw7OOS8uPZLORGQFyJbHtVmFPVvwja4G/o2gntAoHUZ2LiJJakpVhhlSyrI
yuzvwwFtZVfWtNb5gAKZCyg0aduR3qgd7MPerRF+YopZk3OCRpC02YxfUZrHv398
FZWJFK0R8iU52CEUxVpXTA==
-----END XWING PUBLIC KEY-----	
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30003"]

  • Identifier

    Specifies the human-readable identifier for a node, which must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • IdentityPublicKey

    String containing the node's public identity key in PEM format. IdentityPublicKey is the node's permanent identifier and is used to verify cryptographic signatures produced by its private identity key.

    Type: string

    Required: Yes

  • PKISignatureScheme

    Specifies the cryptographic signature scheme that will be used by all components of the mix network when interacting with the PKI system. Mix nodes sign their descriptors using this signature scheme, and dirauth nodes similarly sign PKI documents using the same scheme.

    Type: string

    Required: Yes

  • LinkPublicKey

    String containing the peer's public link-layer key in PEM format. LinkPublicKey must match the specified WireKEMScheme.

    Type: string

    Required: Yes

  • WireKEMScheme

    The name of the wire protocol key-encapsulation mechanism (KEM) to use.

    Type: string

    Required: Yes

  • Addresses

    Specifies a list of one or more address URLs in a format that contains the transport protocol, IP address, and port number that the server will bind to for incoming connections. Katzenpost supports URLs that start with either "tcp://" or "quic://" such as: ["tcp://192.168.1.1:30001"] and ["quic://192.168.1.1:40001"].

    Type: []string

    Required: Yes

Mix node: Management section

The Management section specifies connectivity information for the Katzenpost control protocol which can be used to make run-time configuration changes. A configuration resembles the following:

[Management]
   Enable = false
   Path = "/dirauth_mixnet/mix1/management_sock"

  • Enable

    If true, the management interface is enabled.

    Type: bool

    Required: No

  • Path

    Specifies the path to the management interface socket. If left empty, then management_sock is located in the configuration's defined DataDir>.

    Type: string

    Required: No

Mix node: SphinxGeometry section

The SphinxGeometry section defines parameters for the Sphinx encrypted nested-packet format used internally by Katzenpost.

[Warning]Warning

The values in the SphinxGeometry configuration section must be programmatically generated by gensphinx. Many of the parameters are interdependent and cannot be individually modified. Do not modify the these values by hand.

The settings in this section are generated by the gensphinx utility, which computes the Sphinx geometry based on the following user-supplied directives:

  • The number of mix node layers (not counting gateway and service nodes)

  • The length of the application-usable packet payload

  • The selected NIKE or KEM scheme

The output in TOML should then be pasted unchanged into the node's configuration file, as shown below. For more information, see ???.

[SphinxGeometry]
                PacketLength = 3082
                NrHops = 5
                HeaderLength = 476
                RoutingInfoLength = 410
                PerHopRoutingInfoLength = 82
                SURBLength = 572
                SphinxPlaintextHeaderLength = 2
                PayloadTagLength = 32
                ForwardPayloadLength = 2574
                UserForwardPayloadLength = 2000
                NextNodeHopLength = 65
                SPRPKeyMaterialLength = 64
                NIKEName = "x25519"
                KEMName = ""

  • PacketLength

    The length of a Sphinx packet in bytes.

    Type: int

    Required: Yes

  • NrHops

    The number of hops a Sphinx packet takes through the mixnet. Because packet headers hold destination information for each hop, the size of the header increases linearly with the number of hops.

    Type: int

    Required: Yes

  • HeaderLength

    The total length of the Sphinx packet header in bytes.

    Type: int

    Required: Yes

  • RoutingInfoLength

    The total length of the routing information portion of the Sphinx packet header.

    Type: int

    Required: Yes

  • PerHopRoutingInfoLength

    The length of the per-hop routing information in the Sphinx packet header.

    Type: int

    Required: Yes

  • SURBLength

    The length of a single-use reply block (SURB).

    Type: int

    Required: Yes

  • SphinxPlaintextHeaderLength

    The length of the plaintext Sphinx packet header.

    Type: int

    Required: Yes

  • PayloadTagLength

    The length of the payload tag.

    Type: int

    Required: Yes

  • ForwardPayloadLength

    The total size of the payload.

    Type: int

    Required: Yes

  • UserForwardPayloadLength

    The size of the usable payload.

    Type: int

    Required: Yes

  • NextNodeHopLength

    The NextNodeHopLength is derived from the largest routing-information block that we expect to encounter. Other packets have NextNodeHop + NodeDelay sections, or a Recipient section, both of which are shorter.

    Type: int

    Required: Yes

  • SPRPKeyMaterialLength

    The length of the strong pseudo-random permutation (SPRP) key.

    Type: int

    Required: Yes

  • NIKEName

    The name of the non-interactive key exchange (NIKE) scheme used by Sphinx packets.

    NIKEName and KEMName are mutually exclusive.

    Type: string

    Required: Yes

  • KEMName

    The name of the key encapsulation mechanism (KEM) used by Sphinx packets.

    NIKEName and KEMName are mutually exclusive.

    Type: string

    Required: Yes

Mix node: Debug section

The Debug section is the Katzenpost server debug configuration for advanced tuning.

[Debug]
                NumSphinxWorkers = 16
                NumServiceWorkers = 3
                NumGatewayWorkers = 3
                NumKaetzchenWorkers = 3
                SchedulerExternalMemoryQueue = false
                SchedulerQueueSize = 0
                SchedulerMaxBurst = 16
                UnwrapDelay = 250
                GatewayDelay = 500
                ServiceDelay = 500
                KaetzchenDelay = 750
                SchedulerSlack = 150
                SendSlack = 50
                DecoySlack = 15000
                ConnectTimeout = 60000
                HandshakeTimeout = 30000
                ReauthInterval = 30000
                SendDecoyTraffic = false
                DisableRateLimit = false
                GenerateOnly = false

  • NumSphinxWorkers

    Specifies the number of worker instances to use for inbound Sphinx packet processing.

    Type: int

    Required: No

  • NumProviderWorkers

    Specifies the number of worker instances to use for provider specific packet processing.

    Type: int

    Required: No

  • NumKaetzchenWorkers

    Specifies the number of worker instances to use for Kaetzchen-specific packet processing.

    Type: int

    Required: No

  • SchedulerExternalMemoryQueue

    If true, the experimental disk-backed external memory queue is enabled.

    Type: bool

    Required: No

  • SchedulerQueueSize

    Specifies the maximum scheduler queue size before random entries will start getting dropped. A value less than or equal to zero is treated as unlimited.

    Type: int

    Required: No

  • SchedulerMaxBurst

    Specifies the maximum number of packets that will be dispatched per scheduler wakeup event.

    Type:

    Required: No

  • UnwrapDelay

    Specifies the maximum unwrap delay due to queueing in milliseconds.

    Type: int

    Required: No

  • GatewayDelay

    Specifies the maximum gateway node worker delay due to queueing in milliseconds.

    Type: int

    Required: No

  • ServiceDelay

    Specifies the maximum provider delay due to queueing in milliseconds.

    Type: int

    Required: No

  • KaetzchenDelay

    Specifies the maximum kaetzchen delay due to queueing in milliseconds.

    Type: int

    Required: No

  • SchedulerSlack

    Specifies the maximum scheduler slack due to queueing and/or processing in milliseconds.

    Type: int

    Required: No

  • SendSlack

    Specifies the maximum send-queue slack due to queueing and/or congestion in milliseconds.

    Type: int

    Required: No

  • DecoySlack

    Specifies the maximum decoy sweep slack due to external delays such as latency before a loop decoy packet will be considered lost.

    Type: int

    Required: No

  • ConnectTimeout

    Specifies the maximum time a connection can take to establish a TCP/IP connection in milliseconds.

    Type: int

    Required: No

  • HandshakeTimeout

    Specifies the maximum time a connection can take for a link-protocol handshake in milliseconds.

    Type: int

    Required: No

  • ReauthInterval

    Specifies the interval at which a connection will be reauthenticated in milliseconds.

    Type: int

    Required: No

  • SendDecoyTraffic

    If true, decoy traffic is enabled. This parameter is experimental and untuned, and is disabled by default.

    [Note]Note

    This option will be removed once decoy traffic is fully implemented.

    Type: bool

    Required: No

  • DisableRateLimit

    If true, the per-client rate limiter is disabled.

    [Note]Note

    This option should only be used for testing.

    Type: bool

    Required: No

  • GenerateOnly

    If true, the server immediately halts and cleans up after long-term key generation.

    Type: bool

    Required: No

Configuring gateway nodes

The following configuration is drawn from the reference implementation in katzenpost/docker/dirauth_mixnet/gateway1/katzenpost.toml. In a real-world mixnet, the component hosts would not be sharing a single IP address. For more information about the test mixnet, see ???.

Table 4. Gateway node configuration sections

Gateway node: Server section

Gateway node: Logging section

Gateway node: Gateway section

Gateway node: PKI section

Gateway node: Management section

Gateway node: SphinxGeometry section

Gateway node: Debug section


Gateway node: Server section

The Server section configures mandatory basic parameters for each server node.

[Server]
    Identifier = "gateway1"
    WireKEM = "xwing"
    PKISignatureScheme = "Ed25519"
    Addresses = ["127.0.0.1:30004"]
    OnlyAdvertiseAltAddresses = false
    MetricsAddress = "127.0.0.1:30005"
    DataDir = "/dirauth_mixnet/gateway1"
    IsGatewayNode = true
    IsServiceNode = false
    [Server.AltAddresses]
        TCP = ["localhost:30004"]

  • Identifier

    Specifies the human-readable identifier for a node, and must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • WireKEM

    WireKEM specifies the key encapsulation mechanism (KEM) scheme for the PQ Noise-based wire protocol (link layer) that nodes use to communicate with each other. PQ Noise is a post-quantum variation of the Noise protocol framework, which algebraically transforms ECDH handshake patterns into KEM encapsulate/decapsulate operations.

    This configuration option supports the optional use of hybrid post-quantum cryptography to strengthen security. The following KEM schemes are supported:

    • Classical: "x25519", "x448"

      [Note]Note

      X25519 and X448 are actually non-interactive key-exchanges (NIKEs), not KEMs. Katzenpost uses a hashed ElGamal cryptographic construction to convert them from NIKEs to KEMs.

    • Post-quantum: "mlkem768","sntrup4591761", "frodo640shake", "mceliece348864", "mceliece348864f", "mceliece460896", "mceliece460896f", "mceliece6688128", "mceliece6688128f", "mceliece6960119", "mceliece6960119f", "mceliece8192128", "mceliece8192128f", "CTIDH511", "CTIDH512", "CTIDH1024", "CTIDH2048",

    • Hybrid post-quantum: "xwing", "Kyber768-X25519", "MLKEM768-X25519", "MLKEM768-X448", "FrodoKEM-640-SHAKE-X448", "sntrup4591761-X448", "mceliece348864-X25519", "mceliece348864f-X25519", "mceliece460896-X25519", "mceliece460896f-X25519", "mceliece6688128-X25519", "mceliece6688128f-X25519", "mceliece6960119-X25519", "mceliece6960119f-X25519", "mceliece8192128-X25519", "mceliece8192128f-X25519", "CTIDH512-X25519", "CTIDH512-X25519"

    Type: string

    Required: Yes

  • PKISignatureScheme

    Specifies the cryptographic signature scheme that will be used by all components of the mix network when interacting with the PKI system. Mix nodes sign their descriptors using this signature scheme, and dirauth nodes similarly sign PKI documents using the same scheme.

    The following signature schemes are supported:

    • Classical: "ed25519", "ed448"

    • Hybrid post-quantum: "Ed25519 Sphincs+", "Ed448-Sphincs+", "Ed25519-Dilithium2", "Ed448-Dilithium3"

    Type: string

    Required: Yes

  • Addresses

    Specifies a list of one or more address URLs in a format that contains the transport protocol, IP address, and port number that the server will bind to for incoming connections. Katzenpost supports URLs with that start with either "tcp://" or "quic://" such as: ["tcp://192.168.1.1:30001"] and ["quic://192.168.1.1:40001"].

    Type: []string

    Required: Yes

  • BindAddresses

    If true, allows setting of listener addresses that the server will bind to and accept connections on. These addresses are not advertised in the PKI.

    Type: bool

    Required: No

  • MetricsAddress

    Specifies the address/port to bind the Prometheus metrics endpoint to.

    Type: string

    Required: No

  • DataDir

    Specifies the absolute path to a node's state directory. This is where persistence.db is written to disk and where a node stores its cryptographic key materials when started with the "-g" commmand-line option.

    Type: string

    Required: Yes

  • IsGatewayNode

    If true, the server is a gateway node.

    Type: bool

    Required: No

  • IsServiceNode

    If true, the server is a service node.

    Type: bool

    Required: No

Gateway node: Logging section

The Logging configuration section controls logging behavior across Katzenpost.

[Logging]
                Disable = false
                File = "katzenpost.log"
                Level = "INFO"

  • Disable

    If true, logging is disabled.

    Type: bool

    Required: No

  • File

    Specifies the log file. If omitted, stdout is used.

    An absolute or relative file path can be specified. A relative path is relative to the DataDir specified in the Server section of the configuration.

    Type: string

    Required: No

  • Level

    Supported logging level values are ERROR | WARNING | NOTICE |INFO | DEBUG.

    Type: string

    Required: No

    [Warning]Warning

    The DEBUG log level is unsafe for production use.

Gateway node: Gateway section

The Gateway section of the configuration is required for configuring a Gateway node. The section must contain UserDB and SpoolDB definitions. Bolt is an embedded database library for the Go programming language that Katzenpost has used in the past for its user and spool databases. Because Katzenpost currently persists data on Service nodes instead of Gateways, these databases will probably be deprecated in favour of in-memory concurrency structures. In the meantime, it remains necessary to configure a Gateway node as shown below, only changing the file paths as needed: 

[Gateway]
    [Gateway.UserDB]
        Backend = "bolt"
            [Gateway.UserDB.Bolt]
                UserDB = "/dirauth_mixnet/gateway1/users.db"
    [Gateway.SpoolDB]
        Backend = "bolt"
            [Gateway.SpoolDB.Bolt]
                SpoolDB = "/dirauth_mixnet/gateway1/spool.db"

Gateway node: PKI section

The PKI section contains the directory authority configuration for a mix, gateway, or service node.

[PKI]
[PKI.dirauth]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth1"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
tqN6tpOVotHWXKCszVn2kS7vAZjQpvJjQF3Qz/Qwhyg=
-----END ED25519 PUBLIC KEY-----
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """-----BEGIN XWING PUBLIC KEY-----
JnJ8ztQEIjAkKJcpuZvJAdkWjBim/5G5d8yoosEQHeGJeeBqNPdm2AitUbpiQPcd
tNCo9DxuC9Ieqmsfw0YpV6AtOOsaInA6QnHDYcuBfZcQL5MU4+t2TzpBZQYlrSED
hPCKrAG+8GEUl6akseG371WQzEtPpEWWCJCJOiS/VDFZT7eKrldlumN6gfiB84sR
...
arFh/WKwYJUj+aGBsFYSqGdzC6MdY4x/YyFe2ze0MJEjThQE91y1d/LCQ3Sb7Ri+
u6PBi3JU2qzlPEejDKwK0t5tMNEAkq8iNrpRTdD/hS0gR+ZIN8Z9QKh7Xf94FWG2
H+r8OaqImQhgHabrWRDyLg==
-----END XWING PUBLIC KEY-----
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30001"]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth2"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
O51Ty2WLu4C1ETMa29s03bMXV72gnjJfTfwLV++LVBI=
-----END ED25519 PUBLIC KEY-----	
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """-----BEGIN XWING PUBLIC KEY-----
TtQkg2XKUnY602FFBaPJ+zpN0Twy20cwyyFxh7FNUjaXA9MAJXs0vUwFbJc6BjYv
f+olKnlIKFSmDvcF74U6w1F0ObugwTNKNxeYKPKhX4FiencUbRwkHoYHdtZdSctz
TKy08qKQyCAccqCRpdo6ZtYXPAU+2rthjYTOL7Zn+7SHUKCuJClcPnvEYjVcJxtZ
...
ubJIe5U4nMJbBkOqr7Kq6niaEkiLODa0tkpB8tKMYTMBdcYyHSXCzpo7U9sb6LAR
HktiTBDtRXviu2vbw7VRXhkMW2kjYZDtReQ5sAse04DvmD49zgTp1YxYW+wWFaL3
37X7/SNuLdHX4PHZXIWHBQ==
-----END XWING PUBLIC KEY-----	
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30002"]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth3"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
zQvydRYJq3npeLcg1NqIf+SswEKE5wFmiwNsI9Z1whQ=
-----END ED25519 PUBLIC KEY-----
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """
-----BEGIN XWING PUBLIC KEY-----
OYK9FiC53xwZ1VST3jDOO4tR+cUMSVRSekmigZMChSjDCPZbKut8TblxtlUfc/yi
Ugorz4NIvYPMWUt3QPwS2UWq8/HMWXNGPUiAevg12+oV+jOJXaJeCfY24UekJnSw
TNcdGaFZFSR0FocFcPBBnrK1M2B8w8eEUKQIsXRDM3x/8aRIuDif+ve8rSwpgKeh
...
OdVD3yw7OOS8uPZLORGQFyJbHtVmFPVvwja4G/o2gntAoHUZ2LiJJakpVhhlSyrI
yuzvwwFtZVfWtNb5gAKZCyg0aduR3qgd7MPerRF+YopZk3OCRpC02YxfUZrHv398
FZWJFK0R8iU52CEUxVpXTA==
-----END XWING PUBLIC KEY-----	
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30003"]

  • Identifier

    Specifies the human-readable identifier for a node, which must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • IdentityPublicKey

    String containing the node's public identity key in PEM format. IdentityPublicKey is the node's permanent identifier and is used to verify cryptographic signatures produced by its private identity key.

    Type: string

    Required: Yes

  • PKISignatureScheme

    Specifies the cryptographic signature scheme that will be used by all components of the mix network when interacting with the PKI system. Mix nodes sign their descriptors using this signature scheme, and dirauth nodes similarly sign PKI documents using the same scheme.

    Type: string

    Required: Yes

  • LinkPublicKey

    String containing the peer's public link-layer key in PEM format. LinkPublicKey must match the specified WireKEMScheme.

    Type: string

    Required: Yes

  • WireKEMScheme

    The name of the wire protocol key-encapsulation mechanism (KEM) to use.

    Type: string

    Required: Yes

  • Addresses

    Specifies a list of one or more address URLs in a format that contains the transport protocol, IP address, and port number that the server will bind to for incoming connections. Katzenpost supports URLs that start with either "tcp://" or "quic://" such as: ["tcp://192.168.1.1:30001"] and ["quic://192.168.1.1:40001"].

    Type: []string

    Required: Yes

Gateway node: Management section

The Management section specifies connectivity information for the Katzenpost control protocol which can be used to make run-time configuration changes. A configuration resembles the following:

[Management]
   Enable = false
   Path = "/dirauth_mixnet/mix1/management_sock"

  • Enable

    If true, the management interface is enabled.

    Type: bool

    Required: No

  • Path

    Specifies the path to the management interface socket. If left empty, then management_sock is located in the configuration's defined DataDir>.

    Type: string

    Required: No

Gateway node: SphinxGeometry section

The SphinxGeometry section defines parameters for the Sphinx encrypted nested-packet format used internally by Katzenpost.

[Warning]Warning

The values in the SphinxGeometry configuration section must be programmatically generated by gensphinx. Many of the parameters are interdependent and cannot be individually modified. Do not modify the these values by hand.

The settings in this section are generated by the gensphinx utility, which computes the Sphinx geometry based on the following user-supplied directives:

  • The number of mix node layers (not counting gateway and service nodes)

  • The length of the application-usable packet payload

  • The selected NIKE or KEM scheme

The output in TOML should then be pasted unchanged into the node's configuration file, as shown below. For more information, see ???.

[SphinxGeometry]
                PacketLength = 3082
                NrHops = 5
                HeaderLength = 476
                RoutingInfoLength = 410
                PerHopRoutingInfoLength = 82
                SURBLength = 572
                SphinxPlaintextHeaderLength = 2
                PayloadTagLength = 32
                ForwardPayloadLength = 2574
                UserForwardPayloadLength = 2000
                NextNodeHopLength = 65
                SPRPKeyMaterialLength = 64
                NIKEName = "x25519"
                KEMName = ""

  • PacketLength

    The length of a Sphinx packet in bytes.

    Type: int

    Required: Yes

  • NrHops

    The number of hops a Sphinx packet takes through the mixnet. Because packet headers hold destination information for each hop, the size of the header increases linearly with the number of hops.

    Type: int

    Required: Yes

  • HeaderLength

    The total length of the Sphinx packet header in bytes.

    Type: int

    Required: Yes

  • RoutingInfoLength

    The total length of the routing information portion of the Sphinx packet header.

    Type: int

    Required: Yes

  • PerHopRoutingInfoLength

    The length of the per-hop routing information in the Sphinx packet header.

    Type: int

    Required: Yes

  • SURBLength

    The length of a single-use reply block (SURB).

    Type: int

    Required: Yes

  • SphinxPlaintextHeaderLength

    The length of the plaintext Sphinx packet header.

    Type: int

    Required: Yes

  • PayloadTagLength

    The length of the payload tag.

    Type: int

    Required: Yes

  • ForwardPayloadLength

    The total size of the payload.

    Type: int

    Required: Yes

  • UserForwardPayloadLength

    The size of the usable payload.

    Type: int

    Required: Yes

  • NextNodeHopLength

    The NextNodeHopLength is derived from the largest routing-information block that we expect to encounter. Other packets have NextNodeHop + NodeDelay sections, or a Recipient section, both of which are shorter.

    Type: int

    Required: Yes

  • SPRPKeyMaterialLength

    The length of the strong pseudo-random permutation (SPRP) key.

    Type: int

    Required: Yes

  • NIKEName

    The name of the non-interactive key exchange (NIKE) scheme used by Sphinx packets.

    NIKEName and KEMName are mutually exclusive.

    Type: string

    Required: Yes

  • KEMName

    The name of the key encapsulation mechanism (KEM) used by Sphinx packets.

    NIKEName and KEMName are mutually exclusive.

    Type: string

    Required: Yes

Gateway node: Debug section

The Debug section is the Katzenpost server debug configuration for advanced tuning.

[Debug]
                NumSphinxWorkers = 16
                NumServiceWorkers = 3
                NumGatewayWorkers = 3
                NumKaetzchenWorkers = 3
                SchedulerExternalMemoryQueue = false
                SchedulerQueueSize = 0
                SchedulerMaxBurst = 16
                UnwrapDelay = 250
                GatewayDelay = 500
                ServiceDelay = 500
                KaetzchenDelay = 750
                SchedulerSlack = 150
                SendSlack = 50
                DecoySlack = 15000
                ConnectTimeout = 60000
                HandshakeTimeout = 30000
                ReauthInterval = 30000
                SendDecoyTraffic = false
                DisableRateLimit = false
                GenerateOnly = false

  • NumSphinxWorkers

    Specifies the number of worker instances to use for inbound Sphinx packet processing.

    Type: int

    Required: No

  • NumProviderWorkers

    Specifies the number of worker instances to use for provider specific packet processing.

    Type: int

    Required: No

  • NumKaetzchenWorkers

    Specifies the number of worker instances to use for Kaetzchen-specific packet processing.

    Type: int

    Required: No

  • SchedulerExternalMemoryQueue

    If true, the experimental disk-backed external memory queue is enabled.

    Type: bool

    Required: No

  • SchedulerQueueSize

    Specifies the maximum scheduler queue size before random entries will start getting dropped. A value less than or equal to zero is treated as unlimited.

    Type: int

    Required: No

  • SchedulerMaxBurst

    Specifies the maximum number of packets that will be dispatched per scheduler wakeup event.

    Type:

    Required: No

  • UnwrapDelay

    Specifies the maximum unwrap delay due to queueing in milliseconds.

    Type: int

    Required: No

  • GatewayDelay

    Specifies the maximum gateway node worker delay due to queueing in milliseconds.

    Type: int

    Required: No

  • ServiceDelay

    Specifies the maximum provider delay due to queueing in milliseconds.

    Type: int

    Required: No

  • KaetzchenDelay

    Specifies the maximum kaetzchen delay due to queueing in milliseconds.

    Type: int

    Required: No

  • SchedulerSlack

    Specifies the maximum scheduler slack due to queueing and/or processing in milliseconds.

    Type: int

    Required: No

  • SendSlack

    Specifies the maximum send-queue slack due to queueing and/or congestion in milliseconds.

    Type: int

    Required: No

  • DecoySlack

    Specifies the maximum decoy sweep slack due to external delays such as latency before a loop decoy packet will be considered lost.

    Type: int

    Required: No

  • ConnectTimeout

    Specifies the maximum time a connection can take to establish a TCP/IP connection in milliseconds.

    Type: int

    Required: No

  • HandshakeTimeout

    Specifies the maximum time a connection can take for a link-protocol handshake in milliseconds.

    Type: int

    Required: No

  • ReauthInterval

    Specifies the interval at which a connection will be reauthenticated in milliseconds.

    Type: int

    Required: No

  • SendDecoyTraffic

    If true, decoy traffic is enabled. This parameter is experimental and untuned, and is disabled by default.

    [Note]Note

    This option will be removed once decoy traffic is fully implemented.

    Type: bool

    Required: No

  • DisableRateLimit

    If true, the per-client rate limiter is disabled.

    [Note]Note

    This option should only be used for testing.

    Type: bool

    Required: No

  • GenerateOnly

    If true, the server immediately halts and cleans up after long-term key generation.

    Type: bool

    Required: No

Configuring service nodes

The following configuration is drawn from the reference implementation in katzenpost/docker/dirauth_mixnet/servicenode1/authority.toml. In a real-world mixnet, the component hosts would not be sharing a single IP address. For more information about the test mixnet, see ???.

Table 5. Mix node configuration sections

Service node: Server section

Service node: Logging section

Service node: ServiceNode section

Service node: PKI section

Service node: Management section

Service node: SphinxGeometry section

Service node: Debug section


Service node: Server section

The Server section configures mandatory basic parameters for each server node.

[Server]
    Identifier = "servicenode1"
    WireKEM = "xwing"
    PKISignatureScheme = "Ed25519"
    Addresses = ["127.0.0.1:30006"]
    OnlyAdvertiseAltAddresses = false
    MetricsAddress = "127.0.0.1:30007"
    DataDir = "/dirauth_mixnet/servicenode1"
    IsGatewayNode = false
    IsServiceNode = true
    [Server.AltAddresses]

  • Identifier

    Specifies the human-readable identifier for a node, and must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • WireKEM

    WireKEM specifies the key encapsulation mechanism (KEM) scheme for the PQ Noise-based wire protocol (link layer) that nodes use to communicate with each other. PQ Noise is a post-quantum variation of the Noise protocol framework, which algebraically transforms ECDH handshake patterns into KEM encapsulate/decapsulate operations.

    This configuration option supports the optional use of hybrid post-quantum cryptography to strengthen security. The following KEM schemes are supported:

    • Classical: "x25519", "x448"

      [Note]Note

      X25519 and X448 are actually non-interactive key-exchanges (NIKEs), not KEMs. Katzenpost uses a hashed ElGamal cryptographic construction to convert them from NIKEs to KEMs.

    • Post-quantum: "mlkem768","sntrup4591761", "frodo640shake", "mceliece348864", "mceliece348864f", "mceliece460896", "mceliece460896f", "mceliece6688128", "mceliece6688128f", "mceliece6960119", "mceliece6960119f", "mceliece8192128", "mceliece8192128f", "CTIDH511", "CTIDH512", "CTIDH1024", "CTIDH2048",

    • Hybrid post-quantum: "xwing", "Kyber768-X25519", "MLKEM768-X25519", "MLKEM768-X448", "FrodoKEM-640-SHAKE-X448", "sntrup4591761-X448", "mceliece348864-X25519", "mceliece348864f-X25519", "mceliece460896-X25519", "mceliece460896f-X25519", "mceliece6688128-X25519", "mceliece6688128f-X25519", "mceliece6960119-X25519", "mceliece6960119f-X25519", "mceliece8192128-X25519", "mceliece8192128f-X25519", "CTIDH512-X25519", "CTIDH512-X25519"

    Type: string

    Required: Yes

  • PKISignatureScheme

    Specifies the cryptographic signature scheme that will be used by all components of the mix network when interacting with the PKI system. Mix nodes sign their descriptors using this signature scheme, and dirauth nodes similarly sign PKI documents using the same scheme.

    The following signature schemes are supported:

    • Classical: "ed25519", "ed448"

    • Hybrid post-quantum: "Ed25519 Sphincs+", "Ed448-Sphincs+", "Ed25519-Dilithium2", "Ed448-Dilithium3"

    Type: string

    Required: Yes

  • Addresses

    Specifies a list of one or more address URLs in a format that contains the transport protocol, IP address, and port number that the server will bind to for incoming connections. Katzenpost supports URLs with that start with either "tcp://" or "quic://" such as: ["tcp://192.168.1.1:30001"] and ["quic://192.168.1.1:40001"].

    Type: []string

    Required: Yes

  • BindAddresses

    If true, allows setting of listener addresses that the server will bind to and accept connections on. These addresses are not advertised in the PKI.

    Type: bool

    Required: No

  • MetricsAddress

    Specifies the address/port to bind the Prometheus metrics endpoint to.

    Type: string

    Required: No

  • DataDir

    Specifies the absolute path to a node's state directory. This is where persistence.db is written to disk and where a node stores its cryptographic key materials when started with the "-g" commmand-line option.

    Type: string

    Required: Yes

  • IsGatewayNode

    If true, the server is a gateway node.

    Type: bool

    Required: No

  • IsServiceNode

    If true, the server is a service node.

    Type: bool

    Required: No

Service node: Logging section

The Logging configuration section controls logging behavior across Katzenpost.

[Logging]
                Disable = false
                File = "katzenpost.log"
                Level = "INFO"

  • Disable

    If true, logging is disabled.

    Type: bool

    Required: No

  • File

    Specifies the log file. If omitted, stdout is used.

    An absolute or relative file path can be specified. A relative path is relative to the DataDir specified in the Server section of the configuration.

    Type: string

    Required: No

  • Level

    Supported logging level values are ERROR | WARNING | NOTICE |INFO | DEBUG.

    Type: string

    Required: No

    [Warning]Warning

    The DEBUG log level is unsafe for production use.

Service node: ServiceNode section

The ServiceNode section contains configurations for each network service that Katzenpost supports.

Services, termed Kaetzchen, can be divided into built-in and external services. External services are provided through the CBORPlugin, a Go programming language implementation of the Concise Binary Object Representation (CBOR), a binary data serialization format. While native services need simply to be activated, external services are invoked by a separate command and connected to the mixnet over a Unix socket. The plugin allows mixnet services to be added in any programming language.

[ServiceNode]
                    
    [[ServiceNode.Kaetzchen]]
        Capability = "echo"
        Endpoint = "+echo"
        Disable = false
    
    [[ServiceNode.CBORPluginKaetzchen]]
        Capability = "spool"
        Endpoint = "+spool"
        Command = "/dirauth_mixnet/memspool.alpine"
        MaxConcurrency = 1
        Disable = false
        [ServiceNode.CBORPluginKaetzchen.Config]
            data_store = "/dirauth_mixnet/servicenode1/memspool.storage"
            log_dir = "/dirauth_mixnet/servicenode1"
    
    [[ServiceNode.CBORPluginKaetzchen]]
        Capability = "pigeonhole"
        Endpoint = "+pigeonhole"
        Command = "/dirauth_mixnet/pigeonhole.alpine"
        MaxConcurrency = 1
        Disable = false
        [ServiceNode.CBORPluginKaetzchen.Config]
            db = "/dirauth_mixnet/servicenode1/map.storage"
            log_dir = "/dirauth_mixnet/servicenode1"
    
    [[ServiceNode.CBORPluginKaetzchen]]
        Capability = "panda"
        Endpoint = "+panda"
        Command = "/dirauth_mixnet/panda_server.alpine"
        MaxConcurrency = 1
        Disable = false
        [ServiceNode.CBORPluginKaetzchen.Config]
            fileStore = "/dirauth_mixnet/servicenode1/panda.storage"
            log_dir = "/dirauth_mixnet/servicenode1"
            log_level = "INFO"
    
    [[ServiceNode.CBORPluginKaetzchen]]
        Capability = "http"
        Endpoint = "+http"
        Command = "/dirauth_mixnet/proxy_server.alpine"
        MaxConcurrency = 1
        Disable = false
        [ServiceNode.CBORPluginKaetzchen.Config]
            host = "localhost:4242"
            log_dir = "/dirauth_mixnet/servicenode1"
            log_level = "DEBUG"

Common parameters:

  • Capability

    Specifies the protocol capability exposed by the agent.

    Type: string

    Required: Yes

  • Endpoint

    Specifies the provider-side Endpoint where the agent will accept requests. While not required by the specification, this server only supports Endpoints that are lower-case local parts of an email address.

    Type: string

    Required: Yes

  • Command

    Specifies the full path to the external plugin program that implements this Kaetzchen service.

    Type: string

    Required: Yes

  • MaxConcurrency

    Specifies the number of worker goroutines to start for this service.

    Type: int

    Required: Yes

  • Config

    Specifies extra per-agent arguments to be passed to the agent's initialization routine.

    Type: map[string]interface{}

    Required: Yes

  • Disable

    If true, disables a configured agent.

    Type: bool

    Required: No

Per-service parameters:

  • echo

    The internal echo service must be enabled on every service node of a production mixnet for decoy traffic to work properly.

  • spool

    The spool service supports the catshadow storage protocol, which is required by the Katzen chat client. The example configuration above shows spool enabled with the setting:

    Disable = false
    [Note]Note

    Spool, properly memspool, should not be confused with the spool database on gateway nodes.

    • data_store

      Specifies the full path to the service database file.

      Type: string

      Required: Yes

    • log_dir

      Specifies the path to the node's log directory.

      Type: string

      Required: Yes

  • pigeonhole

    The pigeonhole courier service supports the Blinding-and-Capability scheme (BACAP)-based unlinkable messaging protocols detailed in Place-holder for research paper link. Most of our future protocols will use the pigeonhole courier service.

    • db

      Specifies the full path to the service database file.

      Type: string

      Required: Yes

    • log_dir

      Specifies the path to the node's log directory.

      Type: string

      Required: Yes

  • panda

    The panda storage and authentication service currently does not work properly.

    • fileStore

      Specifies the full path to the service database file.

      Type: string

      Required: Yes

    • log_dir

      Specifies the path to the node's log directory.

      Type: string

      Required: Yes

    • log_level

      Supported values are ERROR | WARNING | NOTICE |INFO | DEBUG.

      [Warning]Warning

      The DEBUG log level is unsafe for production use.

      Type: string

      Required: Yes

      Required: Yes

  • http

    The http service is completely optional, but allows the mixnet to be used as an HTTP proxy. This may be useful for integrating with existing software systems.

    • host

      The host name and TCP port of the service.

      Type: string

      Required: Yes

    • log_dir

      Specifies the path to the node's log directory.

      Type: string

      Required: Yes

    • log_level

      Supported values are ERROR | WARNING | NOTICE |INFO | DEBUG.

      Type: string

      Required: Yes

      Required: Yes

      [Warning]Warning

      The DEBUG log level is unsafe for production use.

      Type: string

      Required: Yes

Service node: PKI section

The PKI section contains the directory authority configuration for a mix, gateway, or service node.

[PKI]
[PKI.dirauth]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth1"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
tqN6tpOVotHWXKCszVn2kS7vAZjQpvJjQF3Qz/Qwhyg=
-----END ED25519 PUBLIC KEY-----
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """-----BEGIN XWING PUBLIC KEY-----
JnJ8ztQEIjAkKJcpuZvJAdkWjBim/5G5d8yoosEQHeGJeeBqNPdm2AitUbpiQPcd
tNCo9DxuC9Ieqmsfw0YpV6AtOOsaInA6QnHDYcuBfZcQL5MU4+t2TzpBZQYlrSED
hPCKrAG+8GEUl6akseG371WQzEtPpEWWCJCJOiS/VDFZT7eKrldlumN6gfiB84sR
...
arFh/WKwYJUj+aGBsFYSqGdzC6MdY4x/YyFe2ze0MJEjThQE91y1d/LCQ3Sb7Ri+
u6PBi3JU2qzlPEejDKwK0t5tMNEAkq8iNrpRTdD/hS0gR+ZIN8Z9QKh7Xf94FWG2
H+r8OaqImQhgHabrWRDyLg==
-----END XWING PUBLIC KEY-----
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30001"]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth2"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
O51Ty2WLu4C1ETMa29s03bMXV72gnjJfTfwLV++LVBI=
-----END ED25519 PUBLIC KEY-----	
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """-----BEGIN XWING PUBLIC KEY-----
TtQkg2XKUnY602FFBaPJ+zpN0Twy20cwyyFxh7FNUjaXA9MAJXs0vUwFbJc6BjYv
f+olKnlIKFSmDvcF74U6w1F0ObugwTNKNxeYKPKhX4FiencUbRwkHoYHdtZdSctz
TKy08qKQyCAccqCRpdo6ZtYXPAU+2rthjYTOL7Zn+7SHUKCuJClcPnvEYjVcJxtZ
...
ubJIe5U4nMJbBkOqr7Kq6niaEkiLODa0tkpB8tKMYTMBdcYyHSXCzpo7U9sb6LAR
HktiTBDtRXviu2vbw7VRXhkMW2kjYZDtReQ5sAse04DvmD49zgTp1YxYW+wWFaL3
37X7/SNuLdHX4PHZXIWHBQ==
-----END XWING PUBLIC KEY-----	
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30002"]

    [[PKI.dirauth.Authorities]]
        Identifier = "auth3"
        IdentityPublicKey = """-----BEGIN ED25519 PUBLIC KEY-----
zQvydRYJq3npeLcg1NqIf+SswEKE5wFmiwNsI9Z1whQ=
-----END ED25519 PUBLIC KEY-----
"""
        PKISignatureScheme = "Ed25519"
        LinkPublicKey = """
-----BEGIN XWING PUBLIC KEY-----
OYK9FiC53xwZ1VST3jDOO4tR+cUMSVRSekmigZMChSjDCPZbKut8TblxtlUfc/yi
Ugorz4NIvYPMWUt3QPwS2UWq8/HMWXNGPUiAevg12+oV+jOJXaJeCfY24UekJnSw
TNcdGaFZFSR0FocFcPBBnrK1M2B8w8eEUKQIsXRDM3x/8aRIuDif+ve8rSwpgKeh
...
OdVD3yw7OOS8uPZLORGQFyJbHtVmFPVvwja4G/o2gntAoHUZ2LiJJakpVhhlSyrI
yuzvwwFtZVfWtNb5gAKZCyg0aduR3qgd7MPerRF+YopZk3OCRpC02YxfUZrHv398
FZWJFK0R8iU52CEUxVpXTA==
-----END XWING PUBLIC KEY-----	
"""
        WireKEMScheme = "xwing"
        Addresses = ["127.0.0.1:30003"]

  • Identifier

    Specifies the human-readable identifier for a node, which must be unique per mixnet. The identifier can be an FQDN but does not have to be.

    Type: string

    Required: Yes

  • IdentityPublicKey

    String containing the node's public identity key in PEM format. IdentityPublicKey is the node's permanent identifier and is used to verify cryptographic signatures produced by its private identity key.

    Type: string

    Required: Yes

  • PKISignatureScheme

    Specifies the cryptographic signature scheme that will be used by all components of the mix network when interacting with the PKI system. Mix nodes sign their descriptors using this signature scheme, and dirauth nodes similarly sign PKI documents using the same scheme.

    Type: string

    Required: Yes

  • LinkPublicKey

    String containing the peer's public link-layer key in PEM format. LinkPublicKey must match the specified WireKEMScheme.

    Type: string

    Required: Yes

  • WireKEMScheme

    The name of the wire protocol key-encapsulation mechanism (KEM) to use.

    Type: string

    Required: Yes

  • Addresses

    Specifies a list of one or more address URLs in a format that contains the transport protocol, IP address, and port number that the server will bind to for incoming connections. Katzenpost supports URLs that start with either "tcp://" or "quic://" such as: ["tcp://192.168.1.1:30001"] and ["quic://192.168.1.1:40001"].

    Type: []string

    Required: Yes

Service node: Management section

The Management section specifies connectivity information for the Katzenpost control protocol which can be used to make run-time configuration changes. A configuration resembles the following:

[Management]
   Enable = false
   Path = "/dirauth_mixnet/mix1/management_sock"

  • Enable

    If true, the management interface is enabled.

    Type: bool

    Required: No

  • Path

    Specifies the path to the management interface socket. If left empty, then management_sock is located in the configuration's defined DataDir>.

    Type: string

    Required: No

Service node: SphinxGeometry section

The SphinxGeometry section defines parameters for the Sphinx encrypted nested-packet format used internally by Katzenpost.

[Warning]Warning

The values in the SphinxGeometry configuration section must be programmatically generated by gensphinx. Many of the parameters are interdependent and cannot be individually modified. Do not modify the these values by hand.

The settings in this section are generated by the gensphinx utility, which computes the Sphinx geometry based on the following user-supplied directives:

  • The number of mix node layers (not counting gateway and service nodes)

  • The length of the application-usable packet payload

  • The selected NIKE or KEM scheme

The output in TOML should then be pasted unchanged into the node's configuration file, as shown below. For more information, see ???.

[SphinxGeometry]
                PacketLength = 3082
                NrHops = 5
                HeaderLength = 476
                RoutingInfoLength = 410
                PerHopRoutingInfoLength = 82
                SURBLength = 572
                SphinxPlaintextHeaderLength = 2
                PayloadTagLength = 32
                ForwardPayloadLength = 2574
                UserForwardPayloadLength = 2000
                NextNodeHopLength = 65
                SPRPKeyMaterialLength = 64
                NIKEName = "x25519"
                KEMName = ""

  • PacketLength

    The length of a Sphinx packet in bytes.

    Type: int

    Required: Yes

  • NrHops

    The number of hops a Sphinx packet takes through the mixnet. Because packet headers hold destination information for each hop, the size of the header increases linearly with the number of hops.

    Type: int

    Required: Yes

  • HeaderLength

    The total length of the Sphinx packet header in bytes.

    Type: int

    Required: Yes

  • RoutingInfoLength

    The total length of the routing information portion of the Sphinx packet header.

    Type: int

    Required: Yes

  • PerHopRoutingInfoLength

    The length of the per-hop routing information in the Sphinx packet header.

    Type: int

    Required: Yes

  • SURBLength

    The length of a single-use reply block (SURB).

    Type: int

    Required: Yes

  • SphinxPlaintextHeaderLength

    The length of the plaintext Sphinx packet header.

    Type: int

    Required: Yes

  • PayloadTagLength

    The length of the payload tag.

    Type: int

    Required: Yes

  • ForwardPayloadLength

    The total size of the payload.

    Type: int

    Required: Yes

  • UserForwardPayloadLength

    The size of the usable payload.

    Type: int

    Required: Yes

  • NextNodeHopLength

    The NextNodeHopLength is derived from the largest routing-information block that we expect to encounter. Other packets have NextNodeHop + NodeDelay sections, or a Recipient section, both of which are shorter.

    Type: int

    Required: Yes

  • SPRPKeyMaterialLength

    The length of the strong pseudo-random permutation (SPRP) key.

    Type: int

    Required: Yes

  • NIKEName

    The name of the non-interactive key exchange (NIKE) scheme used by Sphinx packets.

    NIKEName and KEMName are mutually exclusive.

    Type: string

    Required: Yes

  • KEMName

    The name of the key encapsulation mechanism (KEM) used by Sphinx packets.

    NIKEName and KEMName are mutually exclusive.

    Type: string

    Required: Yes

Service node: Debug section

The Debug section is the Katzenpost server debug configuration for advanced tuning.

[Debug]
                NumSphinxWorkers = 16
                NumServiceWorkers = 3
                NumGatewayWorkers = 3
                NumKaetzchenWorkers = 3
                SchedulerExternalMemoryQueue = false
                SchedulerQueueSize = 0
                SchedulerMaxBurst = 16
                UnwrapDelay = 250
                GatewayDelay = 500
                ServiceDelay = 500
                KaetzchenDelay = 750
                SchedulerSlack = 150
                SendSlack = 50
                DecoySlack = 15000
                ConnectTimeout = 60000
                HandshakeTimeout = 30000
                ReauthInterval = 30000
                SendDecoyTraffic = false
                DisableRateLimit = false
                GenerateOnly = false

  • NumSphinxWorkers

    Specifies the number of worker instances to use for inbound Sphinx packet processing.

    Type: int

    Required: No

  • NumProviderWorkers

    Specifies the number of worker instances to use for provider specific packet processing.

    Type: int

    Required: No

  • NumKaetzchenWorkers

    Specifies the number of worker instances to use for Kaetzchen-specific packet processing.

    Type: int

    Required: No

  • SchedulerExternalMemoryQueue

    If true, the experimental disk-backed external memory queue is enabled.

    Type: bool

    Required: No

  • SchedulerQueueSize

    Specifies the maximum scheduler queue size before random entries will start getting dropped. A value less than or equal to zero is treated as unlimited.

    Type: int

    Required: No

  • SchedulerMaxBurst

    Specifies the maximum number of packets that will be dispatched per scheduler wakeup event.

    Type:

    Required: No

  • UnwrapDelay

    Specifies the maximum unwrap delay due to queueing in milliseconds.

    Type: int

    Required: No

  • GatewayDelay

    Specifies the maximum gateway node worker delay due to queueing in milliseconds.

    Type: int

    Required: No

  • ServiceDelay

    Specifies the maximum provider delay due to queueing in milliseconds.

    Type: int

    Required: No

  • KaetzchenDelay

    Specifies the maximum kaetzchen delay due to queueing in milliseconds.

    Type: int

    Required: No

  • SchedulerSlack

    Specifies the maximum scheduler slack due to queueing and/or processing in milliseconds.

    Type: int

    Required: No

  • SendSlack

    Specifies the maximum send-queue slack due to queueing and/or congestion in milliseconds.

    Type: int

    Required: No

  • DecoySlack

    Specifies the maximum decoy sweep slack due to external delays such as latency before a loop decoy packet will be considered lost.

    Type: int

    Required: No

  • ConnectTimeout

    Specifies the maximum time a connection can take to establish a TCP/IP connection in milliseconds.

    Type: int

    Required: No

  • HandshakeTimeout

    Specifies the maximum time a connection can take for a link-protocol handshake in milliseconds.

    Type: int

    Required: No

  • ReauthInterval

    Specifies the interval at which a connection will be reauthenticated in milliseconds.

    Type: int

    Required: No

  • SendDecoyTraffic

    If true, decoy traffic is enabled. This parameter is experimental and untuned, and is disabled by default.

    [Note]Note

    This option will be removed once decoy traffic is fully implemented.

    Type: bool

    Required: No

  • DisableRateLimit

    If true, the per-client rate limiter is disabled.

    [Note]Note

    This option should only be used for testing.

    Type: bool

    Required: No

  • GenerateOnly

    If true, the server immediately halts and cleans up after long-term key generation.

    Type: bool

    Required: No

Last modified December 12, 2024: Repairing images links again (e4d53aa1)