cborplugin

Documentation

Overview

Package cborplugin is a plugin system allowing mix network services to be added in any language. It communicates queries and responses to and from the mix server using CBOR over HTTP over UNIX domain socket. Beyond that, a client supplied SURB is used to route the response back to the client as described in our Kaetzchen specification document:

https://github.com/katzenpost/docs/blob/master/specs/kaetzchen.rst

Index

• type Client
  • func New(command, capability, endpoint string, logBackend *log.Backend) *Client
  • func (c *Client) Capability() string
  • func (c *Client) GetParameters() *Parameters
  • func (c *Client) OnRequest(request *Request) ([]byte, error)
  • func (c *Client) Start(command string, args []string) error
• type Parameters
• type Request
• type Response
• type ServicePlugin

Types

type Client

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

Client acts as a client interacting with one or more plugins. The Client type is composite with Worker and therefore has a Halt method. Client implements this interface and proxies data between this mix server and the external plugin program.

func New

func New(command, capability, endpoint string, logBackend *log.Backend) *Client

New creates a new plugin client instance which represents the single execution of the external plugin program.

func (*Client) Capability

func (c *Client) Capability() string

Capability are used in Mix Descriptor publication to give service clients more information about the service. Not plugins will need to use this feature.

func (*Client) GetParameters

func (c *Client) GetParameters() *Parameters

GetParameters are used in Mix Descriptor publication to give service clients more information about the service. Not plugins will need to use this feature.

func (*Client) OnRequest

func (c *Client) OnRequest(request *Request) ([]byte, error)

OnRequest send a query request to plugin using CBOR + HTTP over Unix domain socket.

func (*Client) Start

func (c *Client) Start(command string, args []string) error

Start execs the plugin and starts a worker thread to listen on the halt chan sends a TERM signal to the plugin if the shutdown even is dispatched.

type Parameters

type Parameters map[string]string

Parameters is an optional mapping that plugins can publish, these get advertised to clients in the MixDescriptor. The output of GetParameters() ends up being published in a map associating with the service names to service parameters map. This information is part of the Mix Descriptor which is defined here: https://github.com/katzenpost/core/blob/master/pki/pki.go

type Request

type Request struct {
	ID      uint64
	Payload []byte
	HasSURB bool
}

Request is the struct type used in service query requests to plugins.

type Response

type Response struct {
	Payload []byte
}

Response is the response received after sending a Request to the plugin.

type ServicePlugin

type ServicePlugin interface {
	// OnRequest is the method that is called when the Provider receives
	// a request designed for a particular agent. The caller will handle
	// extracting the payload component of the message
	OnRequest(request *Request) ([]byte, error)

	// Capability returns the agent's functionality for publication in
	// the Provider's descriptor.
	Capability() string

	// Parameters returns the agent's paramenters for publication in
	// the Provider's descriptor.
	GetParameters() *Parameters

	// Halt stops the plugin.
	Halt()
}

ServicePlugin is the interface that we expose for external plugins to implement. This is similar to the internal Kaetzchen interface defined in: github.com/katzenpost/server/internal/provider/kaetzchen/kaetzchen.go