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 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 UnmarshalRequest(msg []byte) (*protocol.Request, error)
• func UnmarshalResponse(t int, msg []byte) *protocol.Response
• type AppConfig
  • func LoadConfig(file string) (AppConfig, error)
• type 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 *ServerBaseConfig, listenVerb string, ...) *ServerBase
  • func (sb *ServerBase) ConfigFilePath() string
  • func (sb *ServerBase) EpochUpdate(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 ServerBaseConfig

Functions

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 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 string) error
}

AppConfig is the generic type used to specify the configuration of any kind of CONIKS application-level executable (e.g. key server, client etc.).

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 EpochTimer

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

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

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 *ServerBaseConfig, listenVerb string,
	perms map[*ServerAddress]map[int]bool) *ServerBase

NewServerBase creates a new generic CONIKS-ready server base.

func (*ServerBase) ConfigFilePath

func (sb *ServerBase) ConfigFilePath() string

ConfigFilePath returns the server base's config file path.

func (*ServerBase) EpochUpdate

func (sb *ServerBase) EpochUpdate(f func())

EpochUpdate runs function `f` supposed to be a CONIK's epoch update procedure every epoch.

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 ServerBaseConfig

type ServerBaseConfig struct {
	Logger         *LoggerConfig      `toml:"logger"`
	ConfigFilePath string             `toml:"config_file_path"`
	EpochDeadline  protocol.Timestamp `toml:"epoch_deadline"`
}

A ServerBaseConfig contains configuration values which are read at initialization time from a TOML format configuration file.