monitoring

Documentation

Overview

Package monitoring defines the structs and interfaces for monitoring primitives with Tink. This package isn't yet production ready and might go through various changes.

Index

• type Client
• type Context
  • func NewContext(primitive string, apiFunction string, keysetInfo *KeysetInfo) *Context
• type Entry
• type KeyStatus
  • func (status KeyStatus) String() string
• type KeysetInfo
  • func NewKeysetInfo(annotations map[string]string, primaryKeyID uint32, entries []*Entry) *KeysetInfo
• type Logger

Types

type Client

type Client interface {
	NewLogger(context *Context) (Logger, error)
}

Client represents an interface to hold monitoring client context to create a `Logger`. A Client is registered with Tink's registry and used by primitives to obtain a `Logger`.

type Context

type Context struct {
	Primitive   string
	APIFunction string
	KeysetInfo  *KeysetInfo
}

Context defines a context for monitoring events, wich includes the primitive and API used, and information on the keyset.

func NewContext

func NewContext(primitive string, apiFunction string, keysetInfo *KeysetInfo) *Context

NewContext creates a new monitoring context.

type Entry

type Entry struct {
	Status    KeyStatus
	KeyID     uint32
	KeyType   string
	KeyPrefix string
}

Entry represents each entry inside a Keyset.

type KeyStatus

type KeyStatus int

KeyStatus represents KeyStatusType in tink/proto/tink.proto.

const (
	// Enabled keys can be used for cryptographic operations.
	Enabled KeyStatus = iota
	// Disabled keys can't be used, but can be re-enabled.
	Disabled
	// Destroyed keys don't exist in the keyset anymore.
	Destroyed

	// DoNotUse is intended to guard from failures that may be caused by future expansions.
	DoNotUse KeyStatus = 20
)

func (KeyStatus) String

func (status KeyStatus) String() string

type KeysetInfo

type KeysetInfo struct {
	Annotations  map[string]string
	PrimaryKeyID uint32
	Entries      []*Entry
}

KeysetInfo represents a keyset in a certain point in time for the purpose of monitoring operations involving cryptographic keys.

func NewKeysetInfo

func NewKeysetInfo(annotations map[string]string, primaryKeyID uint32, entries []*Entry) *KeysetInfo

NewKeysetInfo creates a new KeysetInfo.

type Logger

type Logger interface {
	// Logs a successful use of `keyID` on an input of `numBytes`. Tink primitive
	// wrappers call this method when they  successfully use a key to carry out a
	// primitive method, e.g. aead.Encrypt(). As a consequence, implementations of
	// MonitoringClient should be mindful on the amount of work performed by this
	// method, as this will be called on each cryptographic operation. Implementations
	// of MonitoringClient are responsible to add context to identify, e.g., the
	// primitive and the API function.
	Log(keyID uint32, numBytes int)

	// Logs a failure. Tink calls this method when a cryptographic operation
	// failed, e.g. no key could be found to decrypt a ciphertext. In this
	// case the failure is not associated with a specific key, therefore this
	// method has no arguments. The MonitoringClient implementation is responsible
	// to add context to identify where the failure comes from.
	LogFailure()
}

Logger is an interface for logging which can be created through a `Client`. monitoring clients are invoked by Tink during cryptographic operations to emit certain events.