backend

Documentation

Overview

Copyright 2015 Gravitational, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

backend package allows for pluggable back-ends for secrets storage. To implement a new storage back-end you have to supply an object which:

• implements backend.Backend interface
• implements backend.NewFunc function

Index

• Constants
• func AnyTTL(clock clockwork.Clock, times ...time.Time) time.Duration
• func TTL(clock clockwork.Clock, t time.Time) time.Duration
• func ValidateLockTTL(ttl time.Duration) error
• type Backend
• type Config
• type Item
• type Items
  • func (it Items) Len() int
  • func (it Items) Less(i, j int) bool
  • func (it Items) Swap(i, j int)
• type JSONCodec
  • func (c *JSONCodec) CreateJSONVal(path []string, key string, val interface{}, ttl time.Duration) error
  • func (c *JSONCodec) GetJSONVal(path []string, key string, val interface{}) error
  • func (c *JSONCodec) UpsertJSONVal(path []string, key string, val interface{}, ttl time.Duration) error
• type NameFunc
• type NewFunc
• type OpConfig
  • func CollectOptions(opts []OpOption) (*OpConfig, error)
• type OpOption
  • func WithDeduplicateByKey() OpOption
  • func WithRecursive() OpOption
• type Params
  • func (p Params) GetString(key string) string
• type Sanitizer
  • func NewSanitizer(backend Backend) *Sanitizer
  • func (s *Sanitizer) AcquireLock(token string, ttl time.Duration) error
  • func (s *Sanitizer) Backend() Backend
  • func (s *Sanitizer) Clock() clockwork.Clock
  • func (s *Sanitizer) Close() error
  • func (s *Sanitizer) CompareAndSwapVal(bucket []string, key string, val []byte, prevVal []byte, ttl time.Duration) error
  • func (s *Sanitizer) CreateVal(bucket []string, key string, val []byte, ttl time.Duration) error
  • func (s *Sanitizer) DeleteBucket(path []string, bucket string) error
  • func (s *Sanitizer) DeleteKey(bucket []string, key string) error
  • func (s *Sanitizer) GetItems(bucket []string, opts ...OpOption) ([]Item, error)
  • func (s *Sanitizer) GetKeys(bucket []string, opts ...OpOption) ([]string, error)
  • func (s *Sanitizer) GetVal(bucket []string, key string) ([]byte, error)
  • func (s *Sanitizer) ReleaseLock(token string) error
  • func (s *Sanitizer) UpsertItems(bucket []string, items []Item) error
  • func (s *Sanitizer) UpsertVal(bucket []string, key string, val []byte, ttl time.Duration) error

Constants

const (
	Forever         time.Duration = 0
	MaxLockDuration time.Duration = time.Minute
)

Forever means that object TTL will not expire unless deleted

Functions

func AnyTTL

func AnyTTL(clock clockwork.Clock, times ...time.Time) time.Duration

AnyTTL returns TTL if any of the suplied times pass expiry time otherwise returns forever

func TTL

func TTL(clock clockwork.Clock, t time.Time) time.Duration

TTL converts time to TTL from current time supplied by provider, if t is zero, returns forever

func ValidateLockTTL

func ValidateLockTTL(ttl time.Duration) error

ValidateLockTTL helper allows all backends to validate lock TTL parameter

Types

type Backend

type Backend interface {
	// GetKeys returns a list of keys for a given path
	GetKeys(bucket []string, opts ...OpOption) ([]string, error)
	// GetItems returns a list of items (key value pairs) for a bucket.
	GetItems(bucket []string, opts ...OpOption) ([]Item, error)
	// CreateVal creates value with a given TTL and key in the bucket
	// if the value already exists, it must return trace.AlreadyExistsError
	CreateVal(bucket []string, key string, val []byte, ttl time.Duration) error
	// UpsertVal updates or inserts value with a given TTL into a bucket
	// ForeverTTL for no TTL
	UpsertVal(bucket []string, key string, val []byte, ttl time.Duration) error
	// UpsertItems updates or inserts all passed in backend.Items (with a TTL)
	// into the given bucket.
	UpsertItems(bucket []string, items []Item) error
	// GetVal return a value for a given key in the bucket
	GetVal(path []string, key string) ([]byte, error)
	// CompareAndSwapVal compares and swaps values in atomic operation,
	// succeeds if prevVal matches the value stored in the database,
	// requires prevVal as a non-empty value. Returns trace.CompareFailed
	// in case if value did not match.
	CompareAndSwapVal(bucket []string, key string, val []byte, prevVal []byte, ttl time.Duration) error
	// DeleteKey deletes a key in a bucket
	DeleteKey(bucket []string, key string) error
	// DeleteBucket deletes the bucket by a given path
	DeleteBucket(path []string, bkt string) error
	// AcquireLock grabs a lock that will be released automatically in TTL
	AcquireLock(token string, ttl time.Duration) error
	// ReleaseLock forces lock release before TTL
	ReleaseLock(token string) error
	// Close releases the resources taken up by this backend
	Close() error
	// Clock returns clock used by this backend
	Clock() clockwork.Clock
}

Backend implements abstraction over local or remote storage backend

Storage is modeled after BoltDB:

• bucket is a slice []string{"a", "b"}
• buckets contain key value pairs

type Config

type Config struct {
	// Type can be "bolt" or "etcd" or "dynamodb"
	Type string `yaml:"type,omitempty"`

	// Params is a generic key/value property bag which allows arbitrary
	// falues to be passed to backend
	Params Params `yaml:",inline"`
}

Config is used for 'storage' config section. It's a combination of values for various backends: 'boltdb', 'etcd', 'filesystem' and 'dynamodb'

type Item

type Item struct {
	// FullPath is set to full path
	FullPath string
	// Key is an item key.
	Key string
	// Value is an item value.
	Value []byte
	// TTL is the expire time for the item.
	TTL time.Duration
}

Item is a pair of key and value.

type Items

type Items []Item

func (Items) Len

func (it Items) Len() int

Len is part of sort.Interface.

func (Items) Less

func (it Items) Less(i, j int) bool

Less is part of sort.Interface.

func (Items) Swap

func (it Items) Swap(i, j int)

Swap is part of sort.Interface.

type JSONCodec

type JSONCodec struct {
	Backend
}

func (*JSONCodec) CreateJSONVal

func (c *JSONCodec) CreateJSONVal(path []string, key string, val interface{}, ttl time.Duration) error

func (*JSONCodec) GetJSONVal

func (c *JSONCodec) GetJSONVal(path []string, key string, val interface{}) error

func (*JSONCodec) UpsertJSONVal

func (c *JSONCodec) UpsertJSONVal(path []string, key string, val interface{}, ttl time.Duration) error

type NameFunc

type NameFunc func() string

NameFunc type defines a function type which every backend must implement to return its name

type NewFunc

type NewFunc func(Params) (Backend, error)

NewFunc type defines a function type which every backend must implement to instantiate itself

type OpConfig

type OpConfig struct {
	// Recursive triggers recursive get.
	Recursive bool

	// KeysOnly fetches only keys.
	KeysOnly bool

	// DeduplicateByKey removes duplicates based off key instead of the full path.
	// Used for certain resources like users.
	DeduplicateByKey bool
}

OpConfig contains operation config

func CollectOptions

func CollectOptions(opts []OpOption) (*OpConfig, error)

CollectOptions collects all options from functional arg and returns config

type OpOption

type OpOption func(*OpConfig) error

OpOption is operation functional argument

func WithDeduplicateByKey

func WithDeduplicateByKey() OpOption

DeduplicateByKey removes duplicates based off key instead of the full path.

func WithRecursive

func WithRecursive() OpOption

WithRecursive sets get operation to be recursive

type Params

type Params map[string]interface{}

backend.Params type defines a flexible unified back-end configuration API. It is just a map of key/value pairs which gets populated by `storage` section in Teleport YAML config.

func (Params) GetString

func (p Params) GetString(key string) string

GetString returns a string value stored in Params map, or an empty string if nothing is found

type Sanitizer

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

Sanitizer wraps a Backend implementation to make sure all values requested of the backend are whitelisted.

func NewSanitizer

func NewSanitizer(backend Backend) *Sanitizer

NewSanitizer returns a new Sanitizer.

func (*Sanitizer) AcquireLock

func (s *Sanitizer) AcquireLock(token string, ttl time.Duration) error

AcquireLock grabs a lock that will be released automatically after a TTL.

func (*Sanitizer) Backend

func (s *Sanitizer) Backend() Backend

Backend returns the underlying backend. Useful when knowing the type of backend is important (for example, can the backend support forking).

func (*Sanitizer) Clock

func (s *Sanitizer) Clock() clockwork.Clock

Clock returns clock used by this backend

func (*Sanitizer) Close

func (s *Sanitizer) Close() error

Close releases the resources taken up by this backend

func (*Sanitizer) CompareAndSwapVal

func (s *Sanitizer) CompareAndSwapVal(bucket []string, key string, val []byte, prevVal []byte, ttl time.Duration) error

CompareAndSwapVal compares and swaps values in atomic operation, succeeds if prevVal matches the value stored in the database, requires prevVal as a non-empty value. Returns trace.CompareFailed in case if value did not match.

func (*Sanitizer) CreateVal

func (s *Sanitizer) CreateVal(bucket []string, key string, val []byte, ttl time.Duration) error

CreateVal creates value with a given TTL and key in the bucket. If the value already exists, returns trace.AlreadyExistsError.

func (*Sanitizer) DeleteBucket

func (s *Sanitizer) DeleteBucket(path []string, bucket string) error

DeleteBucket deletes the bucket by a given path.

func (*Sanitizer) DeleteKey

func (s *Sanitizer) DeleteKey(bucket []string, key string) error

DeleteKey deletes a key in a bucket.

func (*Sanitizer) GetItems

func (s *Sanitizer) GetItems(bucket []string, opts ...OpOption) ([]Item, error)

GetItems returns a list of items (key value pairs) for a bucket.

func (*Sanitizer) GetKeys

func (s *Sanitizer) GetKeys(bucket []string, opts ...OpOption) ([]string, error)

GetKeys returns a list of keys for a given path.

func (*Sanitizer) GetVal

func (s *Sanitizer) GetVal(bucket []string, key string) ([]byte, error)

GetVal returns a value for a given key in the bucket.

func (*Sanitizer) ReleaseLock

func (s *Sanitizer) ReleaseLock(token string) error

ReleaseLock forces lock release before the TTL has expired.

func (*Sanitizer) UpsertItems

func (s *Sanitizer) UpsertItems(bucket []string, items []Item) error

UpsertItems updates or inserts all passed in backend.Items (with a TTL) into the given bucket.

func (*Sanitizer) UpsertVal

func (s *Sanitizer) UpsertVal(bucket []string, key string, val []byte, ttl time.Duration) error

UpsertVal updates or inserts value with a given TTL into a bucket. Use backend.ForeverTTL for no TTL.