client2

package
v0.0.49 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 30, 2025 License: AGPL-3.0 Imports: 38 Imported by: 0

Documentation

Overview

SPDX-FileCopyrightText: © 2023 David Stainton SPDX-License-Identifier: AGPL-3.0-only

Client2 is the new low level client for Katzenpost mix networks.

Introduction

**Please see the ThinClient section of this documentation** to learn about Katzenpost client integration. The vast majority of applications will use the ThinClient type and not any other part of this library.

Client2 uses a privilege separated design where many applications use a thin client library to connect to the client2 daemon which multiplexes their connections to the mixnet entry node.

A Katzenpost mixnet client has several responsibilities at minimum:

* compose Sphinx packets * decrypt SURB replies * send and receive Noise protocol messages * keep up to date with the latest PKI document

Overview

Client2 is essentially a long running daemon process that listens on an abstract unix domain socket for incoming thin client library connections. Many client applications can use the same client2 daemon. Those connections are multiplexed into the daemon's single connection to the mix network.

Therefore applications will be integrated with Katzenpost using the thin client library which gives them the capability to talk with the client2 daemon and in that way interact with the mix network. The reason we call it a thin client library is because it does not do any mixnet related cryptography since that is already handled by the client2 daemon. In particular, the PKI document is stripped by the daemon before it's passed on to the thin clients. Likewise, thin clients don't decrypt SURB replies or compose Sphinx packets, instead all the that Noise, Sphinx and PKI related cryptography is handled by the daemon.

Thin client and daemon protocol

Note that the thin client daemon protocol listens on an abstract unix domain of type `SOCK_SEQPACKET` which is defined as: 

**SOCK_SEQPACKET** (since Linux 2.6.4), is a connection-oriented socket that preserves message
boundaries and delivers messages in the order that they were sent.

In golang this is referred to by the "unixpacket" network string.

## Client socket naming convention

Thin clients MUST randomize their abstract unix domain socket name otherwise the static name will prevent multiplexing because the kernel requires that the connection be between uniquely nameed socket pairs. The Katzenpost reference implementation of the thin client library selects a socket name with four random hex digits appended to the end of the name like so: 

@katzenpost_golang_thin_client_DEADBEEF

## Daemon socket naming convention

The client2 daemon listens on an abstract unix domain socket with the following name: 

@katzenpost

## Protocol description

Upon connecting to the daemon socket the client must wait for two messages. The first message received must contain a connection status and the second message must contain a new PKI document event. This marks the end of the initial connection sequence. Note that this PKI document is stripped of all cryptographic signatures.

In the next protocol phase, the client may send `Request` messages to the daemon in order to cause the daemon to encapsulate the given payload in a Sphinx packet and send it to the entry node. Likewise the daemon my send the client `Response` messages at any time during this protocol phase. These `Response` messages may indicated a connection status change, a new PKI document or a message sent or reply event.

SPDX-FileCopyrightText: © 2023 David Stainton SPDX-License-Identifier: AGPL-3.0-only

SPDX-FileCopyrightText: © 2023 David Stainton SPDX-License-Identifier: AGPL-3.0-only

Index

Constants

View Source 
const (
	// MessageIDLength is the length of a message ID in bytes.
	MessageIDLength = 16

	// RoundTripTimeSlop is the slop added to the expected packet
	// round trip timeout threshold.
	RoundTripTimeSlop = (3 * time.Minute) + (45 * time.Second)

	MaxRetransmissions = 3
)
View Source 
const (
	// AppIDLength is the length of the application ID in bytes.
	AppIDLength = 16
)
View Source 
const EchoService = "echo"

EchoCapability is the standardized capability for the echo service. XXX FIXME, move me to a common module where it'll be referenced by both the client and the server.

Variables

View Source 
var (
	// ErrNotConnected is the error returned when an operation fails due to the
	// client not currently being connected to the Gateway.
	ErrNotConnected = errors.New("client/conn: not connected to the Gateway")

	// ErrShutdown is the error returned when the connection is closed due to
	// a call to Shutdown().
	ErrShutdown = errors.New("shutdown requested")
)
View Source 
var (
	PublishDeadline = vServer.PublishConsensusDeadline

	// WarpedEpoch is a build time flag that accelerates the recheckInterval
	WarpedEpoch = "false"
)

Functions

func IntoThinResponse 

func IntoThinResponse(r *Response) *thin.Response

func NewListener 

func NewListener(client *Client, rates *Rates, egressCh chan *Request, logBackend *log.Backend) (*listener, error)

New creates a new listener.

Types

type ARQMessage 

type ARQMessage struct {

	// AppID identifies the application sending/receiving the message/reply.
	AppID *[AppIDLength]byte

	// MessageID is the unique message identifier
	MessageID *[MessageIDLength]byte

	// DestinationIdHash is 32 byte hash of the destination Provider's
	// identity public key.
	DestinationIdHash *[32]byte

	// RecipientQueueID is the queue identity which will receive the message.
	RecipientQueueID []byte

	// Payload is the message payload
	Payload []byte

	// SURBID is the SURB identifier.
	SURBID *[sConstants.SURBIDLength]byte

	// SURBDecryptionKeys is the SURB decryption keys
	SURBDecryptionKeys []byte

	// Retransmissions counts the number of times the message has been retransmitted.
	Retransmissions uint32

	// SentAt contains the time the message was sent.
	SentAt time.Time

	// ReplyETA is the expected round trip time to receive a response.
	ReplyETA time.Duration
}

ARQMessage is used by ARQ.

type CachedDoc 

type CachedDoc struct {
	Doc  *cpki.Document
	Blob []byte
}

type Client 

type Client struct {
	worker.Worker
	sync.RWMutex

	PKIClient cpki.Client

	// DialContextFn is the optional alternative Dialer.DialContext function
	// to be used when creating outgoing network connections.
	DialContextFn func(ctx context.Context, network, address string) (net.Conn, error)
	// contains filtered or unexported fields
}

Client manages startup, shutdow, creating new connections and reconnecting.

func New 

func New(cfg *config.Config, logBackend *log.Backend) (*Client, error)

New creates a new Client with the provided configuration.

func (*Client) ClockSkew 

func (c *Client) ClockSkew() time.Duration

ClockSkew returns the current best guess difference between the client's system clock and the network's global clock, rounded to the nearest second, as measured against the provider during the handshake process. Calls to this routine should not be made until the first `ClientConfig.OnConnFn(true)` callback.

func (*Client) ComposeSphinxPacket 

func (c *Client) ComposeSphinxPacket(request *Request) (pkt []byte, surbkey []byte, rtt time.Duration, err error)

ComposeSphinxPacket is used to compose Sphinx packets.

func (*Client) CurrentDocument 

func (c *Client) CurrentDocument() ([]byte, *cpki.Document)

CurrentDocument returns the current pki.Document, or nil iff one does not exist. The caller MUST NOT modify the returned object in any way.

func (*Client) ForceFetch 

func (c *Client) ForceFetch()

ForceFetch attempts to force an otherwise idle client to attempt to fetch the contents of the user's spool. This call has no effect if a connection is not established or if the connection is already in the middle of a fetch cycle, and should be considered a best effort operation.

func (*Client) ForceFetchPKI 

func (c *Client) ForceFetchPKI()

ForceFetchPKI attempts to force client's pkiclient to wake and fetch consensus documents immediately.

func (*Client) GetPollInterval 

func (c *Client) GetPollInterval() time.Duration

XXX This will go away once we get rid of polling.

func (*Client) SendCiphertext 

func (c *Client) SendCiphertext(request *Request) ([]byte, time.Duration, error)

SendCiphertext sends the ciphertext b to the recipient/provider, with a SURB identified by surbID, and returns the SURB decryption key and total round trip delay. Blocks until packet is sent on the wire.

func (*Client) SendPacket 

func (c *Client) SendPacket(pkt []byte) error

func (*Client) SetPollInterval 

func (c *Client) SetPollInterval(interval time.Duration)

XXX This will go away once we get rid of polling.

func (*Client) Shutdown 

func (c *Client) Shutdown()

Shutdown cleanly shuts down a given Client instance.

func (*Client) Start 

func (c *Client) Start() error

func (*Client) WaitForCurrentDocument 

func (c *Client) WaitForCurrentDocument()

type ConnectError 

type ConnectError struct {
	// Err is the original error that caused the connect attempt to fail.
	Err error
}

ConnectError is the error used to indicate that a connect attempt has failed.

func (*ConnectError) Error 

func (e *ConnectError) Error() string

Error implements the error interface.

type ConsensusGetter 

type ConsensusGetter interface {
	GetConsensus(ctx context.Context, epoch uint64) (*commands.Consensus2, error)
}

type Daemon 

type Daemon struct {
	worker.Worker
	// contains filtered or unexported fields
}

func NewDaemon 

func NewDaemon(cfg *config.Config) (*Daemon, error)

func (*Daemon) Shutdown 

func (d *Daemon) Shutdown()

Shutdown cleanly shuts down a given Server instance.

func (*Daemon) Start 

func (d *Daemon) Start() error

type ExpDist 

type ExpDist struct {
	worker.Worker
	// contains filtered or unexported fields
}

ExpDist provides a pseudorandom ticker with an average and maximum delay The channel returned by OutCh() is written at an average rate specified with UpdateRate(average, max uint64), in units of milliseconds.

func NewExpDist 

func NewExpDist() *ExpDist

NewExpDist returns an ExpDist with running worker routine.

func (*ExpDist) OutCh 

func (e *ExpDist) OutCh() <-chan struct{}

OutCh returns channel that receives at the rate specified by UpdateRate

func (*ExpDist) UpdateConnectionStatus 

func (e *ExpDist) UpdateConnectionStatus(isConnected bool)

UpdateConnectionStatus(true) starts sending to OutCh and UpdateConnectionStatus(false) stops sending to OutCh

func (*ExpDist) UpdateRate 

func (e *ExpDist) UpdateRate(averageRate uint64, maxDelay uint64)

UpdateRate is a value in milliseconds and specifies the average and maximum delay between writes to the channel returned by OutCh.

type PKIError 

type PKIError struct {
	// Err is the original PKI error.
	Err error
}

PKIError is the error used to indicate PKI related failures.

func (*PKIError) Error 

func (e *PKIError) Error() string

Error implements the error interface.

type ProtocolError 

type ProtocolError struct {
	// Err is the original error that triggered connection termination.
	Err error
}

ProtocolError is the error used to indicate that the connection was closed due to wire protocol related reasons.

func (*ProtocolError) Error 

func (e *ProtocolError) Error() string

Error implements the error interface.

type Rates 

type Rates struct {
	// contains filtered or unexported fields
}

type Request 

type Request struct {
	// ID is the unique identifier with respect to the Payload.
	// This is only used by the ARQ.
	ID *[MessageIDLength]byte

	// WithSURB indicates if the message should be sent with a SURB
	// in the Sphinx payload.
	WithSURB bool

	// SURBID must be a unique identity for each request.
	// This field should be nil if WithSURB is false.
	SURBID *[sConstants.SURBIDLength]byte

	// AppID must be a unique identity for the client application
	// that is sending this Request.
	AppID *[AppIDLength]byte

	// DestinationIdHash is 32 byte hash of the destination Provider's
	// identity public key.
	DestinationIdHash *[32]byte

	// RecipientQueueID is the queue identity which will receive the message.
	RecipientQueueID []byte

	// Payload is the actual Sphinx packet.
	Payload []byte

	// IsSendOp is set to true if the intent is to send a message through
	// the mix network.
	IsSendOp bool

	// IsARQSendOp is set to true if the intent is to send a message through
	// the mix network using the naive ARQ error correction scheme.
	IsARQSendOp bool

	// IsLoopDecoy is set to true to indicate that this message shall
	// be a loop decoy message.
	IsLoopDecoy bool

	// IsDropDecoy is set to true to indicate that this message shall
	// be a drop decoy message.
	IsDropDecoy bool

	// IsThinClose is set to true to indicate that the thin client
	// is disconnecting from the daemon.
	IsThinClose bool
}

func FromThinRequest 

func FromThinRequest(r *thin.Request, appid *[AppIDLength]byte) *Request

type Response 

type Response struct {
	// AppID must be a unique identity for the client application
	// that is receiving this Response.
	AppID *[AppIDLength]byte

	ShutdownEvent *thin.ShutdownEvent

	ConnectionStatusEvent *thin.ConnectionStatusEvent

	NewPKIDocumentEvent *thin.NewPKIDocumentEvent

	MessageSentEvent *thin.MessageSentEvent

	MessageReplyEvent *thin.MessageReplyEvent

	MessageIDGarbageCollected *thin.MessageIDGarbageCollected
}

type TimerQueue 

type TimerQueue struct {
	worker.Worker
	// contains filtered or unexported fields
}

func NewTimerQueue 

func NewTimerQueue(action func(interface{})) *TimerQueue

func (*TimerQueue) Len 

func (t *TimerQueue) Len() int

func (*TimerQueue) Peek 

func (t *TimerQueue) Peek() *queue.Entry

func (*TimerQueue) Pop 

func (t *TimerQueue) Pop() interface{}

func (*TimerQueue) Push 

func (t *TimerQueue) Push(priority uint64, value interface{})

func (*TimerQueue) Start 

func (t *TimerQueue) Start()

Source Files

View all Source files

Directories

Path Synopsis
cmd
kpclientd command
standalone client daemon
 standalone client daemon
Package config implements the configuration for the Katzenpost client.
 Package config implements the configuration for the Katzenpost client.
Package proxy implements the support for an upstream (outgoing) proxy.
 Package proxy implements the support for an upstream (outgoing) proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.