pairing

Documentation

Overview

Package pairing provides client-server pairing functionality

Index

• Variables
• func AesDecrypt(psk []byte, ciphertext []byte) ([]byte, error)
• func AesEncrypt(psk []byte, plaintext []byte) ([]byte, error)
• type Client
  • func NewDefaultPairingClient(clientName string, wgConfig *wg.Config, keyPair KeyPair, ...) Client
  • func NewKeyCachingPairingClient(storage KeyCachingPairingClientStorage, wgConfig *wg.Config, ...) Client
• type ClientError
  • func NewClientError(err error) ClientError
  • func (e ClientError) Error() string
• type ClientTransport
  • func NewHTTPClientPairingTransport(serverURL string) ClientTransport
  • func NewPSKClientPairingTransport(psk string, child ClientTransport) ClientTransport
• type Encoder
  • func NewJSONPairingEncoder() Encoder
• type IPPool
  • func NewIPPool(starting string, reserved ReservedAddressLister) IPPool
• type IncomingPairingRequest
• type KeyCachingPairingClientStorage
  • func NewBoltKeyCachingPairingClientStorage(path string) (KeyCachingPairingClientStorage, error)
  • func NewInMemoryKeyCachingPairingClientStorage() KeyCachingPairingClientStorage
• type KeyPair
• type MetadataEnricher
• type PeerInfo
• type PeerStorage
  • func NewBoltPeerStorage(path string) PeerStorage
  • func NewInMemoryPeerStorage() PeerStorage
• type Request
• type RequestWireguardConfig
• type ReservedAddressLister
  • func NewReservedAddressLister(storage PeerStorage) ReservedAddressLister
• type Response
• type ResponseWireguardConfig
• type Server
  • func NewServer(serverName string, publicWgHostPort string, wgConfig *wg.Config, ...) *Server
  • func (s *Server) Start()
• type ServerError
  • func NewServerError(err error) ServerError
  • func (e ServerError) Error() string
• type ServerTransport
  • func NewHTTPServerPairingTransport(server *http.Server) ServerTransport
  • func NewPSKPairingServerTransport(psk string, child ServerTransport) ServerTransport

Variables

var ErrPeerDoesNotExist = errors.New("peer does not exist")

ErrPeerDoesNotExist is returned when a peer does not exist yet

Functions

func AesDecrypt

func AesDecrypt(psk []byte, ciphertext []byte) ([]byte, error)

AesDecrypt decrypts ciphertext using the provided pre-shared key (psk).

func AesEncrypt

func AesEncrypt(psk []byte, plaintext []byte) ([]byte, error)

AesEncrypt encrypts plaintext using the provided pre-shared key (psk).

Types

type Client

type Client interface {
	Pair() (Response, error)
}

Client allows pairing with a server

func NewDefaultPairingClient

func NewDefaultPairingClient(
	clientName string,
	wgConfig *wg.Config,
	keyPair KeyPair,
	wgReloader wg.WireguardConfigReloader,
	encoder Encoder,
	transport ClientTransport,
) Client

NewDefaultPairingClient executes HTTP pairing requests to the server

func NewKeyCachingPairingClient

func NewKeyCachingPairingClient(
	storage KeyCachingPairingClientStorage,
	wgConfig *wg.Config,

	wgReloader wg.WireguardConfigReloader,
	client Client,
) Client

NewKeyCachingPairingClient is a decorator that tries to cache the keys obtained by child client

type ClientError

type ClientError struct {
	Err error
}

ClientError is an error that indicate, that it's something wrong with the client

func NewClientError

func NewClientError(err error) ClientError

NewClientError creates a new PairingRequestClientError instance

func (ClientError) Error

func (e ClientError) Error() string

type ClientTransport

type ClientTransport interface {
	Send([]byte) ([]byte, error)
}

ClientTransport is an interface for sending pairing requests

func NewHTTPClientPairingTransport

func NewHTTPClientPairingTransport(serverURL string) ClientTransport

NewHTTPClientPairingTransport creates a new PairingClientTransport instance

func NewPSKClientPairingTransport

func NewPSKClientPairingTransport(psk string, child ClientTransport) ClientTransport

NewPSKClientPairingTransport creates a new PairingClientTransport, that encrypts and decrypts requests using the provided pre-shared key (psk).

type Encoder

type Encoder interface {
	EncodeRequest(Request) ([]byte, error)
	DecodeRequest([]byte) (Request, error)

	EncodeResponse(Response) ([]byte, error)
	DecodeResponse([]byte) (Response, error)
}

Encoder is an interface for encoding and decoding pairing requests and responses

func NewJSONPairingEncoder

func NewJSONPairingEncoder() Encoder

NewJSONPairingEncoder creates a new PairingEncoder instance

type IPPool

type IPPool interface {
	Next() (string, error)
}

IPPool is an interface for managing IP addresses

func NewIPPool

func NewIPPool(starting string, reserved ReservedAddressLister) IPPool

NewIPPool creates a new IP pool

type IncomingPairingRequest

type IncomingPairingRequest struct {
	Request  []byte
	Response chan []byte
	Err      chan error
}

IncomingPairingRequest is a request that was received by the server

type KeyCachingPairingClientStorage

type KeyCachingPairingClientStorage interface {
	Set(Response) error
	Get() (Response, error)
}

KeyCachingPairingClientStorage is a storage for pairing responses cache

func NewBoltKeyCachingPairingClientStorage

func NewBoltKeyCachingPairingClientStorage(path string) (KeyCachingPairingClientStorage, error)

NewBoltKeyCachingPairingClientStorage creates a new KeyCachingPairingClientStorage backed by a bolt database

func NewInMemoryKeyCachingPairingClientStorage

func NewInMemoryKeyCachingPairingClientStorage() KeyCachingPairingClientStorage

NewInMemoryKeyCachingPairingClientStorage creates a new KeyCachingPairingClientStorage backed by memory

type KeyPair

type KeyPair struct {
	PublicKey  string `json:"public_key"`
	PrivateKey string `json:"private_key"`
}

KeyPair is a pair of public and private keys

type MetadataEnricher

type MetadataEnricher interface {
	Metadata() map[string]string
}

MetadataEnricher is an interface that allows transports exchanging information between their client/server implementations

type PeerInfo

type PeerInfo struct {
	Name      string `json:"name"`
	IP        string `json:"ip"`
	PublicKey string `json:"public_key"`
}

PeerInfo is a struct that contains information about a peer

type PeerStorage

type PeerStorage interface {
	Store(PeerInfo) error
	GetByName(string) (PeerInfo, error)
	List() ([]PeerInfo, error)
	DeleteByName(string) error
}

PeerStorage is an interface for storing and retrieving peers

func NewBoltPeerStorage

func NewBoltPeerStorage(path string) PeerStorage

NewBoltPeerStorage creates a new BoltDB (persistent, on-disk storage) PeerStorage instance

func NewInMemoryPeerStorage

func NewInMemoryPeerStorage() PeerStorage

NewInMemoryPeerStorage creates a new in-memory PeerStorage instance

type Request

type Request struct {
	Name string `json:"name"` // Name of the peer, that requests pairing,
	//  for example `dev1`, `us-east-1`, etc
	Wireguard RequestWireguardConfig `json:"wireguard"`
	Metadata  map[string]string      `json:"metadata"` // Any protocol-specific metadata
}

Request is a request to pair with a server

type RequestWireguardConfig

type RequestWireguardConfig struct {
	PublicKey string `json:"public_key"`
}

RequestWireguardConfig is a wireguard configuration for the pairing request

type ReservedAddressLister

type ReservedAddressLister interface {
	ReservedAddresses() ([]string, error)
}

ReservedAddressLister is an interface for listing reserved addresses

func NewReservedAddressLister

func NewReservedAddressLister(storage PeerStorage) ReservedAddressLister

NewReservedAddressLister creates a new reserved address lister

type Response

type Response struct {
	Name       string `json:"name"`        // Name of the server peer
	AssignedIP string `json:"assigned_ip"` // IP that the server assigned to the peer,
	// that requested pairing
	InternalServerIP string                  `json:"internal_server_ip"` // IP of the server in the internal network
	Wireguard        ResponseWireguardConfig `json:"wireguard"`
	Metadata         map[string]string       `json:"metadata"` // Any protocol-specific metadata
}

Response is a response to a pairing request

type ResponseWireguardConfig

type ResponseWireguardConfig struct {
	PublicKey string `json:"public_key"`
	Endpoint  string `json:"endpoint"`
}

ResponseWireguardConfig is a wireguard configuration for the pairing response

type Server

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

Server is a server that can pair with multiple clients

func NewServer

func NewServer(
	serverName string,
	publicWgHostPort string,
	wgConfig *wg.Config,
	keyPair KeyPair,
	wgReloader wg.WireguardConfigReloader,
	encoder Encoder,
	transport ServerTransport,
	ips IPPool,
	storage PeerStorage,
	enrichers []MetadataEnricher,
) *Server

NewServer creates a new PairingServer instance

func (*Server) Start

func (s *Server) Start()

Start starts the pairing server

type ServerError

type ServerError struct {
	Err error
}

ServerError is an error that indicate, that client request was OK, but server failed

func NewServerError

func NewServerError(err error) ServerError

NewServerError creates a new PairingRequestServerError instance

func (ServerError) Error

func (e ServerError) Error() string

type ServerTransport

type ServerTransport interface {
	Requests() <-chan IncomingPairingRequest
}

ServerTransport is an interface for receiving pairing requests

func NewHTTPServerPairingTransport

func NewHTTPServerPairingTransport(server *http.Server) ServerTransport

NewHTTPServerPairingTransport creates a new PairingServerTransport instance

func NewPSKPairingServerTransport

func NewPSKPairingServerTransport(psk string, child ServerTransport) ServerTransport

NewPSKPairingServerTransport creates a new PairingServerTransport, that encrypts and decrypts requests using the provided pre-shared key (psk).