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 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/katzenpost/blob/master/docs/specs/kaetzchen.rst

Index

• type Client
  • func NewClient(logBackend *log.Backend, capability, endpoint string, ...) *Client
  • func (c *Client) Capability() string
  • func (c *Client) GetParameters() *map[string]interface{}
  • func (c *Client) ReadChan() chan Command
  • func (c *Client) Start(command string, args []string) error
  • func (c *Client) WriteChan() chan Command
• type ClientPlugin
• type Command
• type CommandBuilder
• type CommandIO
  • func NewCommandIO(log *logging.Logger) *CommandIO
  • func (c *CommandIO) Accept()
  • func (c *CommandIO) ReadChan() chan Command
  • func (c *CommandIO) Start(initiator bool, socketFile string, commandBuilder CommandBuilder)
  • func (c *CommandIO) WriteChan() chan Command
• type Parameters
• type Request
  • func (r *Request) Marshal() ([]byte, error)
  • func (r *Request) Unmarshal(b []byte) error
• type RequestFactory
  • func (r *RequestFactory) Build() Command
• type Response
  • func (r *Response) Marshal() ([]byte, error)
  • func (r *Response) Unmarshal(b []byte) error
• type ResponseFactory
  • func (r *ResponseFactory) Build() Command
• type Server
  • func NewServer(log *logging.Logger, socketFile string, commandBuilder CommandBuilder, ...) *Server
  • func (s *Server) Accept()
  • func (s *Server) Write(cmd Command)
• type ServerPlugin
• type ServicePlugin

Types

type Client

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

func NewClient

func NewClient(logBackend *log.Backend, capability, endpoint string, commandBuilder CommandBuilder) *Client

func (*Client) Capability

func (c *Client) Capability() string

func (*Client) GetParameters

func (c *Client) GetParameters() *map[string]interface{}

func (*Client) ReadChan

func (c *Client) ReadChan() chan Command

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.

func (*Client) WriteChan

func (c *Client) WriteChan() chan Command

type ClientPlugin

type ClientPlugin interface {
	OnCommand(interface{}) (Command, error)
	RegisterConsumer(*Client)
}

type Command

type Command interface {
	Marshal() ([]byte, error)
	Unmarshal(b []byte) error
}

type CommandBuilder

type CommandBuilder interface {
	Build() Command
}

type CommandIO

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

func NewCommandIO

func NewCommandIO(log *logging.Logger) *CommandIO

func (*CommandIO) Accept

func (c *CommandIO) Accept()

func (*CommandIO) ReadChan

func (c *CommandIO) ReadChan() chan Command

func (*CommandIO) Start

func (c *CommandIO) Start(initiator bool, socketFile string, commandBuilder CommandBuilder)

func (*CommandIO) WriteChan

func (c *CommandIO) WriteChan() chan Command

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/katzenpost/blob/master/core/pki/pki.go

type Request

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

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

func (*Request) Marshal

func (r *Request) Marshal() ([]byte, error)

Marshal serializes Request

func (*Request) Unmarshal

func (r *Request) Unmarshal(b []byte) error

Unmarshal deserializes Request

type RequestFactory

type RequestFactory struct {
}

RequestFactory is a CommandBuilder for Requests

func (*RequestFactory) Build

func (r *RequestFactory) Build() Command

Build returns a Request

type Response

type Response struct {
	Payload []byte
}

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

func (*Response) Marshal

func (r *Response) Marshal() ([]byte, error)

Marshal serializes Response

func (*Response) Unmarshal

func (r *Response) Unmarshal(b []byte) error

Unmarshal deserializes Response

type ResponseFactory

type ResponseFactory struct {
}

ResponseFactory is a CommandBuilder for Responses

func (*ResponseFactory) Build

func (r *ResponseFactory) Build() Command

Build returns a Response

type Server

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

Server is used to construct plugins, which are programs which listen on a unix domain socket for connections from the Provider/mix server.

func NewServer

func NewServer(log *logging.Logger, socketFile string, commandBuilder CommandBuilder, plugin ServerPlugin) *Server

func (*Server) Accept

func (s *Server) Accept()

func (*Server) Write

func (s *Server) Write(cmd Command)

type ServerPlugin

type ServerPlugin interface {
	OnCommand(Command) (Command, error)
	RegisterConsumer(*Server)
}

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/katzenpost/server/internal/provider/kaetzchen/kaetzchen.go