framework

package
v0.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 21, 2017 License: MPL-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const WALPrefix = "wal/"

WALPrefix is the prefix within Storage where WAL entries will be written.

Variables

This section is empty.

Functions

func DeleteWAL 

func DeleteWAL(s logical.Storage, id string) error

DeleteWAL commits the WAL entry with the given ID. Once committed, it is assumed that the operation was a success and doesn't need to be rolled back.

func GenericNameRegex added in v0.3.0 

func GenericNameRegex(name string) string

Helper which returns a generic regex string for creating endpoint patterns that are identified by the given name in the backends

func ListWAL 

func ListWAL(s logical.Storage) ([]string, error)

ListWAL lists all the entries in the WAL.

func OptionalParamRegex added in v0.5.2 

func OptionalParamRegex(name string) string

Helper which returns a regex string for optionally accepting the a field from the API URL

func PutWAL 

func PutWAL(s logical.Storage, kind string, data interface{}) (string, error)

PutWAL writes some data to the WAL.

The kind parameter is used by the framework to allow users to store multiple kinds of WAL data and to easily disambiguate what data they're expecting.

Data within the WAL that is uncommitted (CommitWAL hasn't be called) will be given to the rollback callback when an rollback operation is received, allowing the backend to clean up some partial states.

The data must be JSON encodable.

This returns a unique ID that can be used to reference this WAL data. WAL data cannot be modified. You can only add to the WAL and commit existing WAL entries.

func TestBackendRoutes added in v0.1.1 

func TestBackendRoutes(t *testing.T, b *Backend, rs []string)

TestBackendRoutes is a helper to test that all the given routes will route properly in the backend.

Types

type Backend 

type Backend struct {
	// Help is the help text that is shown when a help request is made
	// on the root of this resource. The root help is special since we
	// show all the paths that can be requested.
	Help string

	// Paths are the various routes that the backend responds to.
	// This cannot be modified after construction (i.e. dynamically changing
	// paths, including adding or removing, is not allowed once the
	// backend is in use).
	//
	// PathsSpecial is the list of path patterns that denote the
	// paths above that require special privileges. These can't be
	// regular expressions, it is either exact match or prefix match.
	// For prefix match, append '*' as a suffix.
	Paths        []*Path
	PathsSpecial *logical.Paths

	// Secrets is the list of secret types that this backend can
	// return. It is used to automatically generate proper responses,
	// and ease specifying callbacks for revocation, renewal, etc.
	Secrets []*Secret

	// PeriodicFunc is the callback, which if set, will be invoked when the
	// periodic timer of RollbackManager ticks. This can be used by
	// backends to do anything it wishes to do periodically.
	//
	// PeriodicFunc can be invoked to, say to periodically delete stale
	// entries in backend's storage, while the backend is still being used.
	// (Note the different of this action from what `Clean` does, which is
	// invoked just before the backend is unmounted).
	PeriodicFunc periodicFunc

	// WALRollback is called when a WAL entry (see wal.go) has to be rolled
	// back. It is called with the data from the entry.
	//
	// WALRollbackMinAge is the minimum age of a WAL entry before it is attempted
	// to be rolled back. This should be longer than the maximum time it takes
	// to successfully create a secret.
	WALRollback       WALRollbackFunc
	WALRollbackMinAge time.Duration

	// Clean is called on unload to clean up e.g any existing connections
	// to the backend, if required.
	Clean CleanupFunc

	// Initialize is called after a backend is created. Storage should not be
	// written to before this function is called.
	Init InitializeFunc

	// Invalidate is called when a keys is modified if required
	Invalidate InvalidateFunc

	// AuthRenew is the callback to call when a RenewRequest for an
	// authentication comes in. By default, renewal won't be allowed.
	// See the built-in AuthRenew helpers in lease.go for common callbacks.
	AuthRenew OperationFunc

	// LicenseRegistration is called to register the license for a backend.
	LicenseRegistration LicenseRegistrationFunc

	// Type is the logical.BackendType for the backend implementation
	BackendType logical.BackendType
	// contains filtered or unexported fields
}

Backend is an implementation of logical.Backend that allows the implementer to code a backend using a much more programmer-friendly framework that handles a lot of the routing and validation for you.

This is recommended over implementing logical.Backend directly.

func (*Backend) Cleanup added in v0.3.0 

func (b *Backend) Cleanup()

Cleanup is used to release resources and prepare to stop the backend

func (*Backend) HandleExistenceCheck added in v0.5.0 

func (b *Backend) HandleExistenceCheck(req *logical.Request) (checkFound bool, exists bool, err error)

HandleExistenceCheck is the logical.Backend implementation.

func (*Backend) HandleRequest 

func (b *Backend) HandleRequest(req *logical.Request) (*logical.Response, error)

HandleRequest is the logical.Backend implementation.

func (*Backend) Initialize added in v0.6.5 

func (b *Backend) Initialize() error

Initialize calls the backend's Init func if set.

func (*Backend) InvalidateKey added in v0.6.5 

func (b *Backend) InvalidateKey(key string)

InvalidateKey is used to clear caches and reset internal state on key changes

func (*Backend) Logger 

func (b *Backend) Logger() log.Logger

Logger can be used to get the logger. If no logger has been set, the logs will be discarded.

func (*Backend) RegisterLicense added in v0.8.0 

func (b *Backend) RegisterLicense(license interface{}) error

RegisterLicense performs backend license registration.

func (*Backend) Route 

func (b *Backend) Route(path string) *Path

Route looks up the path that would be used for a given path string.

func (*Backend) SanitizeTTL added in v0.3.0 

func (b *Backend) SanitizeTTL(ttl, maxTTL time.Duration) (time.Duration, time.Duration, error)

SanitizeTTL caps the boundaries of ttl and max_ttl values to the backend mount's max_ttl value.

func (*Backend) SanitizeTTLStr added in v0.6.0 

func (b *Backend) SanitizeTTLStr(ttlStr, maxTTLStr string) (ttl, maxTTL time.Duration, err error)

SanitizeTTLStr takes in the TTL and MaxTTL values provided by the user, compares those with the SystemView values. If they are empty a value of 0 is set, which will cause initial secret or LeaseExtend operations to use the mount/system defaults. If they are set, their boundaries are validated.

func (*Backend) Secret 

func (b *Backend) Secret(k string) *Secret

Secret is used to look up the secret with the given type.

func (*Backend) Setup added in v0.2.0 

func (b *Backend) Setup(config *logical.BackendConfig) error

Setup is used to initialize the backend with the initial backend configuration

func (*Backend) SpecialPaths 

func (b *Backend) SpecialPaths() *logical.Paths

SpecialPaths is the logical.Backend implementation.

func (*Backend) System added in v0.3.0 

func (b *Backend) System() logical.SystemView

System returns the backend's system view.

func (*Backend) Type added in v0.8.0 

func (b *Backend) Type() logical.BackendType

Type returns the backend type

type CleanupFunc added in v0.3.0 

type CleanupFunc func()

CleanupFunc is the callback for backend unload.

type FieldData 

type FieldData struct {
	Raw    map[string]interface{}
	Schema map[string]*FieldSchema
}

FieldData is the structure passed to the callback to handle a path containing the populated parameters for fields. This should be used instead of the raw (*vault.Request).Data to access data in a type-safe way.

func (*FieldData) Get 

func (d *FieldData) Get(k string) interface{}

Get gets the value for the given field. If the key is an invalid field, FieldData will panic. If you want a safer version of this method, use GetOk. If the field k is not set, the default value (if set) will be returned, otherwise the zero value will be returned.

func (*FieldData) GetDefaultOrZero added in v0.6.0 

func (d *FieldData) GetDefaultOrZero(k string) interface{}

GetDefaultOrZero gets the default value set on the schema for the given field. If there is no default value set, the zero value of the type will be returned.

func (*FieldData) GetOk 

func (d *FieldData) GetOk(k string) (interface{}, bool)

GetOk gets the value for the given field. The second return value will be false if the key is invalid or the key is not set at all.

func (*FieldData) GetOkErr 

func (d *FieldData) GetOkErr(k string) (interface{}, bool, error)

GetOkErr is the most conservative of all the Get methods. It returns whether key is set or not, but also an error value. The error value is non-nil if the field doesn't exist or there was an error parsing the field value.

func (*FieldData) Validate added in v0.3.0 

func (d *FieldData) Validate() error

Validate cycles through raw data and validate conversions in the schema, so we don't get an error/panic later when trying to get data out. Data not in the schema is not an error at this point, so we don't worry about it.

type FieldSchema 

type FieldSchema struct {
	Type        FieldType
	Default     interface{}
	Description string
}

FieldSchema is a basic schema to describe the format of a path field.

func (*FieldSchema) DefaultOrZero 

func (s *FieldSchema) DefaultOrZero() interface{}

DefaultOrZero returns the default value if it is set, or otherwise the zero value of the type.

type FieldType 

type FieldType uint

FieldType is the enum of types that a field can be. 

const (
	TypeInvalid FieldType = 0
	TypeString  FieldType = iota
	TypeInt
	TypeBool
	TypeMap

	// TypeDurationSecond represent as seconds, this can be either an
	// integer or go duration format string (e.g. 24h)
	TypeDurationSecond

	// TypeSlice represents a slice of any type
	TypeSlice

	// TypeStringSlice is a helper for TypeSlice that returns a sanitized
	// slice of strings
	TypeStringSlice

	// TypeCommaStringSlice is a helper for TypeSlice that returns a sanitized
	// slice of strings and also supports parsing a comma-separated list in
	// a string field
	TypeCommaStringSlice

	// TypeNameString represents a name that is URI safe and follows specific
	// rules.  These rules include start and end with an alphanumeric
	// character and characters in the middle can be alphanumeric or . or -.
	TypeNameString

	// TypeKVPairs allows you to represent the data as a map or a list of
	// equal sign delimited key pairs
	TypeKVPairs
)

func (FieldType) String 

func (t FieldType) String() string

func (FieldType) Zero 

func (t FieldType) Zero() interface{}

Zero returns the correct zero-value for a specific FieldType

type InitializeFunc added in v0.6.5 

type InitializeFunc func() error

InitializeFunc is the callback for backend creation.

type InvalidateFunc added in v0.6.5 

type InvalidateFunc func(string)

InvalidateFunc is the callback for backend key invalidation.

type LicenseRegistrationFunc added in v0.8.0 

type LicenseRegistrationFunc func(interface{}) error

LicenseRegistrationFunc is the callback for backend license registration.

type OperationFunc 

type OperationFunc func(*logical.Request, *FieldData) (*logical.Response, error)

OperationFunc is the callback called for an operation on a path.

func LeaseExtend 

func LeaseExtend(backendIncrement, backendMax time.Duration, systemView logical.SystemView) OperationFunc

LeaseExtend returns an OperationFunc that can be used to simply extend the lease of the auth/secret for the duration that was requested. The parameters provided are used to determine the lease's new TTL value.

backendIncrement is the backend's requested increment -- perhaps from a user request, perhaps from a role/config value. If not set, uses the mount/system value.

backendMax is the backend's requested increment -- this can be more restrictive than the mount/system value but not less.

systemView is the system view from the calling backend, used to determine and/or correct default/max times.

type Path 

type Path struct {
	// Pattern is the pattern of the URL that matches this path.
	//
	// This should be a valid regular expression. Named captures will be
	// exposed as fields that should map to a schema in Fields. If a named
	// capture is not a field in the Fields map, then it will be ignored.
	Pattern string

	// Fields is the mapping of data fields to a schema describing that
	// field. Named captures in the Pattern also map to fields. If a named
	// capture name matches a PUT body name, the named capture takes
	// priority.
	//
	// Note that only named capture fields are available in every operation,
	// whereas all fields are available in the Write operation.
	Fields map[string]*FieldSchema

	// Callbacks are the set of callbacks that are called for a given
	// operation. If a callback for a specific operation is not present,
	// then logical.ErrUnsupportedOperation is automatically generated.
	//
	// The help operation is the only operation that the Path will
	// automatically handle if the Help field is set. If both the Help
	// field is set and there is a callback registered here, then the
	// callback will be called.
	Callbacks map[logical.Operation]OperationFunc

	// ExistenceCheck, if implemented, is used to query whether a given
	// resource exists or not. This is used for ACL purposes: if an Update
	// action is specified, and the existence check returns false, the action
	// is not allowed since the resource must first be created. The reverse is
	// also true. If not specified, the Update action is forced and the user
	// must have UpdateCapability on the path.
	ExistenceCheck func(*logical.Request, *FieldData) (bool, error)

	// Help is text describing how to use this path. This will be used
	// to auto-generate the help operation. The Path will automatically
	// generate a parameter listing and URL structure based on the
	// regular expression, so the help text should just contain a description
	// of what happens.
	//
	// HelpSynopsis is a one-sentence description of the path. This will
	// be automatically line-wrapped at 80 characters.
	//
	// HelpDescription is a long-form description of the path. This will
	// be automatically line-wrapped at 80 characters.
	HelpSynopsis    string
	HelpDescription string
}

Path is a single path that the backend responds to.

func PathAppend 

func PathAppend(paths ...[]*Path) []*Path

PathAppend is a helper for appending lists of paths into a single list.

type PathMap 

type PathMap struct {
	Prefix        string
	Name          string
	Schema        map[string]*FieldSchema
	CaseSensitive bool
	Salt          *salt.Salt
	SaltFunc      func() (*salt.Salt, error)
	// contains filtered or unexported fields
}

PathMap can be used to generate a path that stores mappings in the storage. It is a structure that also exports functions for querying the mappings.

The primary use case for this is for credential providers to do their mapping to policies.

func (*PathMap) Delete added in v0.2.0 

func (p *PathMap) Delete(s logical.Storage, k string) error

Delete removes a value from the mapping

func (*PathMap) Get 

func (p *PathMap) Get(s logical.Storage, k string) (map[string]interface{}, error)

Get reads a value out of the mapping

func (*PathMap) List 

func (p *PathMap) List(s logical.Storage, prefix string) ([]string, error)

List reads the keys under a given path

func (*PathMap) Paths 

func (p *PathMap) Paths() []*Path

Paths are the paths to append to the Backend paths.

func (*PathMap) Put 

func (p *PathMap) Put(s logical.Storage, k string, v map[string]interface{}) error

Put writes a value into the mapping

type PathStruct 

type PathStruct struct {
	Name            string
	Path            string
	Schema          map[string]*FieldSchema
	HelpSynopsis    string
	HelpDescription string

	Read bool
}

PathStruct can be used to generate a path that stores a struct in the storage. This structure is a map[string]interface{} but the types are set according to the schema in this structure.

func (*PathStruct) Delete added in v0.2.0 

func (p *PathStruct) Delete(s logical.Storage) error

Delete removes the structure.

func (*PathStruct) Get 

func (p *PathStruct) Get(s logical.Storage) (map[string]interface{}, error)

Get reads the structure.

func (*PathStruct) Paths 

func (p *PathStruct) Paths() []*Path

Paths are the paths to append to the Backend paths.

func (*PathStruct) Put 

func (p *PathStruct) Put(s logical.Storage, v map[string]interface{}) error

Put writes the structure.

type PolicyMap 

type PolicyMap struct {
	PathMap

	DefaultKey string
	PolicyKey  string
}

PolicyMap is a specialization of PathMap that expects the values to be lists of policies. This assists in querying and loading policies from the PathMap.

func (*PolicyMap) Policies 

func (p *PolicyMap) Policies(s logical.Storage, names ...string) ([]string, error)

type Secret 

type Secret struct {
	// Type is the name of this secret type. This is used to setup the
	// vault ID and to look up the proper secret structure when revocation/
	// renewal happens. Once this is set this should not be changed.
	//
	// The format of this must match (case insensitive): ^a-Z0-9_$
	Type string

	// Fields is the mapping of data fields and schema that comprise
	// the structure of this secret.
	Fields map[string]*FieldSchema

	// DefaultDuration is the default value for the duration of the lease for
	// this secret. This can be manually overwritten with the result of
	// Response().
	//
	// If these aren't set, Vault core will set a default lease period which
	// may come from a mount tuning.
	DefaultDuration time.Duration

	// Renew is the callback called to renew this secret. If Renew is
	// not specified then renewable is set to false in the secret.
	// See lease.go for helpers for this value.
	Renew OperationFunc

	// Revoke is the callback called to revoke this secret. This is required.
	Revoke OperationFunc
}

Secret is a type of secret that can be returned from a backend.

func (*Secret) HandleRenew 

func (s *Secret) HandleRenew(req *logical.Request) (*logical.Response, error)

HandleRenew is the request handler for renewing this secret.

func (*Secret) HandleRevoke 

func (s *Secret) HandleRevoke(req *logical.Request) (*logical.Response, error)

HandleRevoke is the request handler for renewing this secret.

func (*Secret) Renewable 

func (s *Secret) Renewable() bool

func (*Secret) Response 

func (s *Secret) Response(
	data, internal map[string]interface{}) *logical.Response

type WALEntry 

type WALEntry struct {
	ID        string      `json:"-"`
	Kind      string      `json:"type"`
	Data      interface{} `json:"data"`
	CreatedAt int64       `json:"created_at"`
}

func GetWAL 

func GetWAL(s logical.Storage, id string) (*WALEntry, error)

GetWAL reads a specific entry from the WAL. If the entry doesn't exist, then nil value is returned.

The kind, value, and error are returned.

type WALRollbackFunc added in v0.6.0 

type WALRollbackFunc func(*logical.Request, string, interface{}) error

WALRollbackFunc is the callback for rollbacks.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.