minclient

README

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

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

Minimal Client Library
========================



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 minclient provides a minimal Katzenpost client.

Package path provides routines for path selection.

Index

• Variables
• func NewPath(rng *mRand.Rand, doc *kpki.Document, recipient []byte, ...) ([]*sphinx.PathHop, time.Time, error)
• func ToString(doc *kpki.Document, p []*sphinx.PathHop) ([]string, error)
• type Client
  • func New(cfg *ClientConfig) (*Client, error)
  • func (c *Client) ClockSkew() time.Duration
  • func (c *Client) ComposeSphinxPacket(recipient, provider string, surbID *[sConstants.SURBIDLength]byte, b []byte) ([]byte, []byte, time.Duration, error)
  • func (c *Client) CurrentDocument() *cpki.Document
  • func (c *Client) ForceFetch()
  • func (c *Client) GetPollInterval() time.Duration
  • func (c *Client) SendCiphertext(recipient, provider string, surbID *[sConstants.SURBIDLength]byte, b []byte) ([]byte, time.Duration, error)
  • func (c *Client) SendSphinxPacket(pkt []byte) error
  • func (c *Client) SendUnreliableCiphertext(recipient, provider string, b []byte) error
  • func (c *Client) SetPollInterval(interval time.Duration)
  • func (c *Client) Shutdown()
  • func (c *Client) Wait()
• type ClientConfig
• type ConnectError
  • func (e *ConnectError) Error() string
• type PKIError
  • func (e *PKIError) Error() string
• type ProtocolError
  • func (e *ProtocolError) Error() string

Variables

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

	// ErrShutdown is the error returned when the connection is closed due to
	// a call to Shutdown().
	ErrShutdown = errors.New("shutdown requested")
)

var (

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

Functions

func NewPath

func NewPath(rng *mRand.Rand, doc *kpki.Document, recipient []byte, src, dst *kpki.MixDescriptor, surbID *[constants.SURBIDLength]byte, baseTime time.Time, isFromClient, isForward bool, epoch uint64) ([]*sphinx.PathHop, time.Time, error)

NewPath creates a new path suitable for use in creating a Sphinx packet with the specified parameters.

Note: Forward packets originating from a client have slightly different path requirements than internally sourced packets or response packets as it includes the 0th hop.

func ToString

func ToString(doc *kpki.Document, p []*sphinx.PathHop) ([]string, error)

ToString returns a slice of strings representing the "useful" component of each PathHop, suitable for debugging.

Types

type Client

type Client struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Client is a client instance.

func New

func New(cfg *ClientConfig) (*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(recipient, provider string, surbID *[sConstants.SURBIDLength]byte, b []byte) ([]byte, []byte, time.Duration, error)

ComposeSphinxPacket is used to compose Sphinx packets.

func (*Client) CurrentDocument

func (c *Client) CurrentDocument() *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) GetPollInterval

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

func (*Client) SendCiphertext

func (c *Client) SendCiphertext(recipient, provider string, surbID *[sConstants.SURBIDLength]byte, b []byte) ([]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.

func (*Client) SendSphinxPacket

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

SendSphinxPacket sends the given Sphinx packet.

func (*Client) SendUnreliableCiphertext

func (c *Client) SendUnreliableCiphertext(recipient, provider string, b []byte) error

SendUnreliableCiphertext sends the ciphertext b to the recipient/provider, in an unreliable manner. No notification of the packet being received will be generated by the recipient's provider.

func (*Client) SetPollInterval

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

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 ClientConfig

type ClientConfig struct {
	// User is the user identifier used to connect to the Provider.
	User string

	// Provider is the provider identifier to connect to.
	Provider string

	// ProviderKeyPin is the optional pinned provider EdDSA signing key.
	// If specified, the client will refuse to accept provider descriptors
	// in PKI documents unless they are signed by the pinned key.
	ProviderKeyPin *eddsa.PublicKey

	// LinkKey is the user's ECDH link authentication private key.
	LinkKey *ecdh.PrivateKey

	// LogBackend is the logging backend to use for client logging.
	LogBackend *log.Backend

	// PKIClient is the PKI Document data source.
	PKIClient kpki.Client

	// OnConnFn is the callback function that will be called when the
	// connection status changes.  The error parameter will be nil on
	// successful connection establishment, otherwise it will be set
	// with the reason why a connection has been torn down (or a connect
	// attempt has failed).
	OnConnFn func(error)

	// OnMessageEmptyFn is the callback function that will be called
	// when the user's server side spool is empty.  This can happen
	// as the result of periodic background fetches.  Calls to the callback
	// that return an error will be treated as a signal to tear down the
	// connection.
	OnEmptyFn func() error

	// OnMessageFn is the callback function that will be called when
	// a message is retrived from the user's server side spool.  Callers
	// MUST be prepared to receive multiple callbacks with the same
	// message body.  Calls to the callback that return an error will
	// be treated as a signal to tear down the connection.
	OnMessageFn func([]byte) error

	// OnACKFn is the callback function that will be called when a
	// message CK is retreived from the user's server side spool.  Callers
	// MUST be prepared to receive multiple callbacks with the same
	// SURB ID and SURB ciphertext.  Calls to the callback that return
	// an error will be treated as a signal to tear down the connection.
	OnACKFn func(*[constants.SURBIDLength]byte, []byte) error

	// OnDocumentFn is the callback function taht will be called when a
	// new directory document is retreived for the current epoch.
	OnDocumentFn func(*cpki.Document)

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

	// PreferedTransports is a list of the transports will be used to make
	// outgoing network connections, with the most prefered first.
	PreferedTransports []cpki.Transport

	// MessagePollInterval is the interval at which the server will be
	// polled for new messages if the queue is belived to be empty.
	// If left unset, an interval of 1 minute will be used.
	MessagePollInterval time.Duration

	// EnableTimeSync enables the use of skewed remote provider time
	// instead of system time when available.
	EnableTimeSync bool
}

ClientConfig is a client configuration.

type ConnectError

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

TODO: replace panic code with other error code or recover pattern? 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 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.