application

Documentation

Overview

Package application is a library for building compatible CONIKS clients and servers.

application implements the server- and client-side application-layer components of the CONIKS key management and verification system. More specifically, application provides an API for building CONIKS registration proxies (bots), client applications, and key servers.

Encoding

This module implements the message encoding and decoding for client-server communications. Currently this module only supports JSON encoding. Protobufs will be supported in the future.

Logger

This module implements a generic logging system that can be used by any CONIKS application/executable.

ServerBase

This module provides an API for implementing any CONIKS server-side functionality (either key server or auditor-client interface).

Index

• func LoadInitSTR(path, file string) (*protocol.DirSTR, error)
• func LoadSigningPubKey(path, file string) (sign.PublicKey, error)
• func MarshalRequest(reqType int, request interface{}) ([]byte, error)
• func MarshalResponse(response *protocol.Response) ([]byte, error)
• func SaveConfig(file string, conf AppConfig) error
• func SaveSTR(file string, str *protocol.DirSTR) error
• func UnmarshalRequest(msg []byte) (*protocol.Request, error)
• func UnmarshalResponse(t int, msg []byte) *protocol.Response
• type AppConfig
  • func LoadConfig(file string) (AppConfig, error)
• type CommonConfig
  • func NewCommonConfig(file, encoding string, logger *LoggerConfig) *CommonConfig
  • func (conf *CommonConfig) GetLoader() ConfigLoader
• type ConfigLoader
• type EpochTimer
  • func NewEpochTimer(epDeadline protocol.Timestamp) *EpochTimer
• type Logger
  • func NewLogger(conf *LoggerConfig) *Logger
  • func (l *Logger) Debug(msg string, keysAndValues ...interface{})
  • func (l *Logger) Error(msg string, keysAndValues ...interface{})
  • func (l *Logger) Fatal(msg string, keysAndValues ...interface{})
  • func (l *Logger) Info(msg string, keysAndValues ...interface{})
  • func (l *Logger) Panic(msg string, keysAndValues ...interface{})
  • func (l *Logger) Warn(msg string, keysAndValues ...interface{})
• type LoggerConfig
• type ServerAddress
• type ServerBase
  • func NewServerBase(conf *CommonConfig, listenVerb string, perms map[*ServerAddress]map[int]bool) *ServerBase
  • func (sb *ServerBase) ConfigInfo() (string, string)
  • func (sb *ServerBase) EpochUpdate(timer *EpochTimer, f func())
  • func (sb *ServerBase) HotReload(f func())
  • func (sb *ServerBase) ListenAndHandle(addr *ServerAddress, reqHandler func(req *protocol.Request) *protocol.Response)
  • func (sb *ServerBase) Logger() *Logger
  • func (sb *ServerBase) RunInBackground(f func())
  • func (sb *ServerBase) Shutdown() error
• type TomlLoader
  • func (ld *TomlLoader) Decode(conf AppConfig) error
  • func (ld *TomlLoader) Encode(conf AppConfig) error

Functions

func LoadInitSTR

func LoadInitSTR(path, file string) (*protocol.DirSTR, error)

LoadInitSTR loads an initial STR at the given path specified in the given config file. If there is any parsing error or the STR is malformed, LoadInitSTR() returns an error with a nil STR.

func LoadSigningPubKey

func LoadSigningPubKey(path, file string) (sign.PublicKey, error)

LoadSigningPubKey loads a public signing key at the given path specified in the given config file. If there is any parsing error or the key is malformed, LoadSigningPubKey() returns an error with a nil key.

func MarshalRequest

func MarshalRequest(reqType int, request interface{}) ([]byte, error)

MarshalRequest returns a JSON encoding of the client's request.

func MarshalResponse

func MarshalResponse(response *protocol.Response) ([]byte, error)

MarshalResponse returns a JSON encoding of the server's response.

func SaveConfig

func SaveConfig(file string, conf AppConfig) error

SaveConfig stores the given configuration conf in the given file using toml encoding. If there is any encoding or IO error, SaveConfig() returns an error.

func SaveSTR

func SaveSTR(file string, str *protocol.DirSTR) error

SaveSTR serializes the given STR to the given file.

func UnmarshalRequest

func UnmarshalRequest(msg []byte) (*protocol.Request, error)

UnmarshalRequest parses a JSON-encoded request msg and creates the corresponding protocol.Request, which will be handled by the server.

func UnmarshalResponse

func UnmarshalResponse(t int, msg []byte) *protocol.Response

UnmarshalResponse decodes the given message into a protocol.Response according to the given request type t. The request types are integer constants defined in the protocol package.

Types

type AppConfig

type AppConfig interface {
	Load(file, encoding string) error
	Save() error
	GetPath() string
}

AppConfig provides an abstraction of the underlying encoding format for the configs.

func LoadConfig

func LoadConfig(file string) (AppConfig, error)

LoadConfig loads an application configuration from the given toml-encoded file. If there is any decoding error, an LoadConfig() returns an error with a nil config.

type CommonConfig

type CommonConfig struct {
	Path     string
	Logger   *LoggerConfig `toml:"logger"`
	Encoding string
	// contains filtered or unexported fields
}

CommonConfig is the generic type used to specify the configuration of any kind of CONIKS application-level executable (e.g. key server, client etc.). It contains some common configuration values including the file path, logger configuration, and config loader.

func NewCommonConfig

func NewCommonConfig(file, encoding string, logger *LoggerConfig) *CommonConfig

NewCommonConfig initializes an application's config file path, its loader for the given encoding, and the logger configuration. Note: This constructor must be called in each Load() method implementation of an AppConfig.

func (*CommonConfig) GetLoader

func (conf *CommonConfig) GetLoader() ConfigLoader

GetLoader returns the config's loader.

type ConfigLoader

type ConfigLoader interface {
	Encode(conf AppConfig) error
	Decode(conf AppConfig) error
}

ConfigLoader provides an interface for implementing different CONIKS application configuration encodings.

type EpochTimer

type EpochTimer struct {
	*time.Timer
	// contains filtered or unexported fields
}

EpochTimer consists of a `time.Timer` and the epoch deadline value.

func NewEpochTimer

func NewEpochTimer(epDeadline protocol.Timestamp) *EpochTimer

NewEpochTimer initializes an epoch timer for running regular update procedures every epoch.

type Logger

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

Logger is a wrapper for zap.SugaredLogger.

func NewLogger

func NewLogger(conf *LoggerConfig) *Logger

NewLogger builds an instance of Logger with default configurations. This logger writes DebugLevel and above logs in development environment, InfoLevel and above logs in production environment to stderr and the file specified in conf, in a human-friendly format.

func (*Logger) Debug

func (l *Logger) Debug(msg string, keysAndValues ...interface{})

Debug logs a message that is most useful to debug, with some additional context addressed by key-value pairs.

func (*Logger) Error

func (l *Logger) Error(msg string, keysAndValues ...interface{})

Error logs a message that is fatal to the operation, but not the service or application, and forces admin intervention, with some additional context addressed by key-value pairs. This still allow the application to continue running.

func (*Logger) Fatal

func (l *Logger) Fatal(msg string, keysAndValues ...interface{})

Fatal is the same as Panic but it then calls os.Exit instead.

func (*Logger) Info

func (l *Logger) Info(msg string, keysAndValues ...interface{})

Info logs a message that highlights the progress of the application and generally can be ignored under normal circumstances, with some additional context addressed by key-value pairs.

func (*Logger) Panic

func (l *Logger) Panic(msg string, keysAndValues ...interface{})

Panic logs a message that is a severe error event, leads the application to abort, with some additional context addressed by key-value pairs. It then panics.

func (*Logger) Warn

func (l *Logger) Warn(msg string, keysAndValues ...interface{})

Warn logs a message that indicates potentially harmful situations, with some additional context addressed by key-value pairs.

type LoggerConfig

type LoggerConfig struct {
	EnableStacktrace bool   `toml:"enable_stacktrace,omitempty"`
	Environment      string `toml:"env"`
	Path             string `toml:"path,omitempty"`
}

A LoggerConfig contains the running environment which is either "development" or "production", the path of file to write the logging output to, and an option to explicitly enable stracktrace output.

type ServerAddress

type ServerAddress struct {
	// Address is formatted as a url: scheme://address.
	Address string `toml:"address"`
	// TLSCertPath is a path to the server's TLS Certificate,
	// which has to be set if the connection is TCP.
	TLSCertPath string `toml:"cert,omitempty"`
	// TLSKeyPath is a path to the server's TLS private key,
	// which has to be set if the connection is TCP.
	TLSKeyPath string `toml:"key,omitempty"`
}

A ServerAddress describes a server's connection. It supports two types of connections: a TCP connection ("tcp") and a Unix socket connection ("unix").

Additionally, TCP connections must use TLS for added security, and each is required to specify a TLS certificate and corresponding private key.

type ServerBase

type ServerBase struct {
	Verb string

	sync.RWMutex
	// contains filtered or unexported fields
}

A ServerBase represents the base features needed to implement a CONIKS key server or auditor. It wraps a ConiksDirectory or AuditLog with a network layer which handles requests/responses and their encoding/decoding. A ServerBase also supports concurrent handling of requests.

func NewServerBase

func NewServerBase(conf *CommonConfig, listenVerb string,
	perms map[*ServerAddress]map[int]bool) *ServerBase

NewServerBase creates a new generic CONIKS-ready server base.

func (*ServerBase) ConfigInfo

func (sb *ServerBase) ConfigInfo() (string, string)

ConfigInfo returns the server base's config file path and encoding.

func (*ServerBase) EpochUpdate

func (sb *ServerBase) EpochUpdate(timer *EpochTimer, f func())

EpochUpdate runs function `f`, which is supposed to be a CONIK's update procedure every epoch, following the given timer.

func (*ServerBase) HotReload

func (sb *ServerBase) HotReload(f func())

HotReload implements hot-reloading by listening for SIGUSR2 signal.

func (*ServerBase) ListenAndHandle

func (sb *ServerBase) ListenAndHandle(addr *ServerAddress,
	reqHandler func(req *protocol.Request) *protocol.Response)

ListenAndHandle implements the main functionality of a CONIKS-ready server. It listens athe the given server address with corresponding permissions, and takes the specified pre- and post-Listening actions. It also supports hot-reloading the configuration by listening for SIGUSR2 signal.

func (*ServerBase) Logger

func (sb *ServerBase) Logger() *Logger

Logger returns the server base's logger instance.

func (*ServerBase) RunInBackground

func (sb *ServerBase) RunInBackground(f func())

RunInBackground creates a new goroutine that calls function `f`. It automatically increments the counter `sync.WaitGroup` of the `ServerBase` and calls `Done` when the function execution is finished.

func (*ServerBase) Shutdown

func (sb *ServerBase) Shutdown() error

Shutdown closes all of the server's connections and shuts down the server.

type TomlLoader

type TomlLoader struct{}

TomlLoader implements a ConfigLoader for toml-encoded CONIKS application configurations.

func (*TomlLoader) Decode

func (ld *TomlLoader) Decode(conf AppConfig) error

Decode reads an application configuration from the given toml-encoded file. If there is any decoding error, Decode() returns an error.

func (*TomlLoader) Encode

func (ld *TomlLoader) Encode(conf AppConfig) error

Encode saves the given configuration conf in toml encoding. If there is any encoding or IO error, Encode() returns an error.