client

package
v0.0.32 Latest Latest
Warning

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

Go to latest
Published: Apr 17, 2024 License: AGPL-3.0, AGPL-3.0 Imports: 32 Imported by: 1

README

.. image:: https://travis-ci.org/katzenpost/client.svg?branch=master
  :target: https://travis-ci.org/katzenpost/client

.. image:: https://godoc.org/github.com/katzenpost/katzenpost/client?status.svg
  :target: https://godoc.org/github.com/katzenpost/katzenpost/client


Katzenpost Mix Network Client Library
=====================================

This client library is general purpose in the sense that it can be used to
build arbitrarily complex messaging systems using Katzenpost. However note that
right now it only supports strict SURB based query response protocols to
interactive mix network services. These services can be written in any langauge
and plugged into the Providers. Furthermore this client does not yet perform
any retransmissions if a packet gets dropped by the mix network.

travis tests
------------

Travis tests may sometimes fail if they take too long.


gitlab CI tests
---------------

Our gitlab tests are located here:

https://gitlab.techcultivation.org/katzenpost/client/-/jobs


optional docker tests
---------------------

To run the optional docker tests firstly, see our docker repo
and start your local dockerized mix network:

https://github.com/katzenpost/katzenpost/docker

A couple of minutes after startup run the tests like this:
::

   GORACE=history_size=7 go test -tags=docker_test -race -v -run Docker


license
=======

AGPL: see LICENSE file for details.


supported by
============

.. image:: https://katzenpost.mixnetworks.org/_static/images/eu-flag-tiny.jpg

This project has received funding from the European Union’s Horizon 2020
research and innovation programme under the Grant Agreement No 653497, Privacy
and Accountability in Networks via Optimized Randomized Mix-nets (Panoramix).

Documentation

Overview

Package client provides a Katzenpost client library.

Index

Constants

This section is empty.

Variables

View Source
var ErrMessageNotSent = errors.New("failure sending message")
View Source
var ErrQueueEmpty = errors.New("queue is empty")

ErrQueueEmpty is the error issued when the queue is empty.

View Source
var ErrQueueFull = errors.New("queue is full")

ErrQueueFull is the error issued when the queue is full.

View Source
var ErrReplyTimeout = errors.New("failure waiting for reply, timeout reached")

Functions

func PKIBootstrap

func PKIBootstrap(ctx context.Context, c *Client, linkKey kem.PrivateKey) (pki.Client, *pki.Document, error)

PKIBootstrap returns a pkiClient and fetches a consensus.

func SelectProvider

func SelectProvider(doc *pki.Document) (*pki.MixDescriptor, error)

SelectProvider returns a provider descriptor or error.

Types

type Client

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

Client handles sending and receiving messages over the mix network

func New

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

New creates a new Client with the provided configuration.

func (*Client) GetBackendLog

func (c *Client) GetBackendLog() *log.Backend

func (*Client) GetConfig

func (c *Client) GetConfig() *config.Config

GetConfig returns the client configuration

func (*Client) GetLogger

func (c *Client) GetLogger(name string) *logging.Logger

GetLogger returns a new logger with the given name.

func (*Client) NewTOFUSession

func (c *Client) NewTOFUSession(ctx context.Context) (*Session, error)

NewTOFUSession creates and returns a new ephemeral session or an error.

func (*Client) Shutdown

func (c *Client) Shutdown()

Shutdown cleanly shuts down a given Client instance.

func (*Client) Wait

func (c *Client) Wait()

Wait waits till the Client is terminated for any reason.

type ConnectionStatusEvent

type ConnectionStatusEvent struct {
	// IsConnected is true iff the account is connected to the provider.
	IsConnected bool

	// Err is the error encountered when connecting or by the connection if any.
	Err error
}

ConnectionStatusEvent is the event sent when an account's connection status changes.

func (*ConnectionStatusEvent) String

func (e *ConnectionStatusEvent) String() string

String returns a string representation of the ConnectionStatusEvent.

type EgressQueue

type EgressQueue interface {

	// Peek returns the next queue item without modifying the queue.
	Peek() (Item, error)

	// Pop pops the next item off the queue.
	Pop() (Item, error)

	// Push pushes the item onto the queue.
	Push(Item) error
}

EgressQueue is the egress queue interface.

type Event

type Event interface {
	// String returns a string representation of the Event.
	String() string
}

Event is the generic event sent over the event listener channel.

type Item

type Item interface {
	Priority() uint64
}

type Message

type Message struct {
	sync.Mutex
	// ID is the message identifier
	ID *[cConstants.MessageIDLength]byte

	// Recipient is the message recipient
	Recipient string

	// Provider is the recipient Provider
	Provider string

	// Payload is the message payload
	Payload []byte

	// 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

	// IsBlocking indicates whether or not the client is blocking on the
	// sending of the query and the receiving of it's reply.
	IsBlocking bool

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

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

	// Reply is the SURB reply
	Reply []byte

	// WithSURB specified if a SURB should be bundled with the forward payload.
	WithSURB bool

	// Specifies if this message is a decoy.
	IsDecoy bool

	// Priority controls the dwell time in the current AQM.
	QueuePriority uint64

	// Reliable indicate whether automatic retransmissions should be used.
	Reliable bool

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

Message is a message reference which is used to match future received SURB replies.

func (*Message) Priority

func (m *Message) Priority() uint64

func (*Message) SetPriority

func (m *Message) SetPriority(priority uint64)

type MessageIDGarbageCollected

type MessageIDGarbageCollected struct {
	// MessageID is the local unique identifier for the message.
	MessageID *[cConstants.MessageIDLength]byte
}

MessageIDGarbageCollected is the event used to signal when a given message ID has been garbage collected.

func (*MessageIDGarbageCollected) String

func (e *MessageIDGarbageCollected) String() string

String returns a string representation of a MessageIDGarbageCollected.

type MessageReplyEvent

type MessageReplyEvent struct {
	// MessageID is the unique identifier for the request associated with the
	// reply.
	MessageID *[cConstants.MessageIDLength]byte

	// Payload is the reply payload if any.
	Payload []byte

	// Err is the error encountered when servicing the request if any.
	Err error
}

MessageReplyEvent is the event sent when a new message is received.

func (*MessageReplyEvent) String

func (e *MessageReplyEvent) String() string

String returns a string representation of the MessageReplyEvent.

type MessageSentEvent

type MessageSentEvent struct {
	// MessageID is the local unique identifier for the message, generated
	// when the message was enqueued.
	MessageID *[cConstants.MessageIDLength]byte

	// 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

	// Err is the error encountered when sending the message if any.
	Err error
}

MessageSentEvent is the event sent when a message has been fully transmitted.

func (*MessageSentEvent) String

func (e *MessageSentEvent) String() string

String returns a string representation of a MessageSentEvent.

type NewDocumentEvent

type NewDocumentEvent struct {
	Document *pki.Document
}

NewDocumentEvent is the new document event, signaling that we have received a new document from the PKI.

func (*NewDocumentEvent) String

func (e *NewDocumentEvent) String() string

String returns a string representation of a NewDocumentEvent.

type Queue

type Queue struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Queue is our in-memory queue implementation used as our egress FIFO queue for messages sent by the client.

func (*Queue) Peek

func (q *Queue) Peek() (Item, error)

Peek returns the next message ref from the queue without modifying the queue.

func (*Queue) Pop

func (q *Queue) Pop() (Item, error)

Pop pops the next message ref off the queue and returns nil upon success, otherwise an error is returned.

func (*Queue) Push

func (q *Queue) Push(e Item) error

Push pushes the given message ref onto the queue and returns nil on success, otherwise an error is returned.

type Session

type Session struct {
	worker.Worker

	EventSink chan Event
	// contains filtered or unexported fields
}

Session is the struct type that keeps state for a given session.

func NewSession

func NewSession(
	ctx context.Context,
	pkiClient pki.Client,
	cachedDoc *pki.Document,
	fatalErrCh chan error,
	logBackend *log.Backend,
	cfg *config.Config,
	linkKey kem.PrivateKey,
	provider *pki.MixDescriptor) (*Session, error)

New establishes a session with provider using key. This method will block until session is connected to the Provider.

func (*Session) BlockingSendReliableMessage

func (s *Session) BlockingSendReliableMessage(recipient, provider string, message []byte) ([]byte, error)

BlockingSendReliableMessage sends a message with automatic message retransmission enabled

func (*Session) BlockingSendUnreliableMessage

func (s *Session) BlockingSendUnreliableMessage(recipient, provider string, message []byte) ([]byte, error)

func (*Session) CurrentDocument

func (s *Session) CurrentDocument() *pki.Document

func (*Session) ForceFetchPKI

func (s *Session) ForceFetchPKI()

func (*Session) GetService

func (s *Session) GetService(serviceName string) (*utils.ServiceDescriptor, error)

GetService returns a randomly selected service matching the specified service name

func (*Session) GetServices

func (s *Session) GetServices(serviceName string) ([]*utils.ServiceDescriptor, error)

GetServices returns the services matching the specified service name

func (*Session) Push

func (s *Session) Push(i Item) error

func (*Session) SendReliableMessage

func (s *Session) SendReliableMessage(recipient, provider string, message []byte) (*[cConstants.MessageIDLength]byte, error)

SendReliableMessage asynchronously sends messages with automatic retransmissiosn.

func (*Session) SendUnreliableMessage

func (s *Session) SendUnreliableMessage(recipient, provider string, message []byte) (*[cConstants.MessageIDLength]byte, error)

SendUnreliableMessage asynchronously sends message without any automatic retransmissions.

func (*Session) Shutdown

func (s *Session) Shutdown()

func (*Session) SphinxGeometry

func (s *Session) SphinxGeometry() *geo.Geometry

func (*Session) WaitForDocument

func (s *Session) WaitForDocument(ctx context.Context) error

WaitForDocument blocks until a pki fetch has completed

type TimerQueue

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

TimerQueue is a queue that delays messages before forwarding to another queue

func NewTimerQueue

func NewTimerQueue(nextQueue nqueue) *TimerQueue

NewTimerQueue intantiates a new TimerQueue and starts the worker routine

func (*TimerQueue) Push

func (a *TimerQueue) Push(i Item)

Push adds a message to the TimerQueue

Directories

Path Synopsis
Package config implements the configuration for the Katzenpost client.
Package config implements the configuration for the Katzenpost client.
internal
proxy
Package proxy implements the support for an upstream (outgoing) proxy.
Package proxy implements the support for an upstream (outgoing) proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL