Documentation ¶
Index ¶
- Constants
- Variables
- func CalculateTTL(sysView logical.SystemView, ...) (ttl time.Duration, warnings []string, errors error)
- func DeleteWAL(ctx context.Context, s logical.Storage, id string) error
- func GenericNameRegex(name string) string
- func GenericNameWithAtRegex(name string) string
- func ListWAL(ctx context.Context, s logical.Storage) ([]string, error)
- func MatchAllRegex(name string) string
- func OptionalParamRegex(name string) string
- func PutWAL(ctx context.Context, s logical.Storage, kind string, data interface{}) (string, error)
- func TestBackendRoutes(t *testing.T, b *Backend, rs []string)
- type Backend
- func (b *Backend) Cleanup(ctx context.Context)
- func (b *Backend) HandleExistenceCheck(ctx context.Context, req *logical.Request) (checkFound bool, exists bool, err error)
- func (b *Backend) HandleRequest(ctx context.Context, req *logical.Request) (*logical.Response, error)
- func (b *Backend) InvalidateKey(ctx context.Context, key string)
- func (b *Backend) Logger() log.Logger
- func (b *Backend) Route(path string) *Path
- func (b *Backend) Secret(k string) *Secret
- func (b *Backend) Setup(ctx context.Context, config *logical.BackendConfig) error
- func (b *Backend) SpecialPaths() *logical.Paths
- func (b *Backend) System() logical.SystemView
- func (b *Backend) Type() logical.BackendType
- type CleanupFunc
- type ExistenceFunc
- type FieldData
- func (d *FieldData) Get(k string) interface{}
- func (d *FieldData) GetDefaultOrZero(k string) interface{}
- func (d *FieldData) GetFirst(k ...string) (interface{}, bool)
- func (d *FieldData) GetOk(k string) (interface{}, bool)
- func (d *FieldData) GetOkErr(k string) (interface{}, bool, error)
- func (d *FieldData) Validate() error
- type FieldSchema
- type FieldType
- type InvalidateFunc
- type OASContent
- type OASDocument
- type OASInfo
- type OASLicense
- type OASMediaTypeObject
- type OASOperation
- type OASParameter
- type OASPathItem
- type OASRequestBody
- type OASResponse
- type OASSchema
- type OperationFunc
- type OperationHandler
- type OperationProperties
- type Path
- type PathMap
- func (p *PathMap) Delete(ctx context.Context, s logical.Storage, k string) error
- func (p *PathMap) Get(ctx context.Context, s logical.Storage, k string) (map[string]interface{}, error)
- func (p *PathMap) List(ctx context.Context, s logical.Storage, prefix string) ([]string, error)
- func (p *PathMap) Paths() []*Path
- func (p *PathMap) Put(ctx context.Context, s logical.Storage, k string, v map[string]interface{}) error
- type PathOperation
- type PathStruct
- func (p *PathStruct) Delete(ctx context.Context, s logical.Storage) error
- func (p *PathStruct) Get(ctx context.Context, s logical.Storage) (map[string]interface{}, error)
- func (p *PathStruct) Paths() []*Path
- func (p *PathStruct) Put(ctx context.Context, s logical.Storage, v map[string]interface{}) error
- type PolicyMap
- type RequestExample
- type Response
- type Secret
- func (s *Secret) HandleRenew(ctx context.Context, req *logical.Request) (*logical.Response, error)
- func (s *Secret) HandleRevoke(ctx context.Context, req *logical.Request) (*logical.Response, error)
- func (s *Secret) Renewable() bool
- func (s *Secret) Response(data, internal map[string]interface{}) *logical.Response
- type WALEntry
- type WALRollbackFunc
Constants ¶
const OASVersion = "3.0.2"
OpenAPI specification (OAS): https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
const WALPrefix = "wal/"
WALPrefix is the prefix within Storage where WAL entries will be written.
Variables ¶
var OASStdRespNoContent = &OASResponse{
Description: "empty body",
}
var OASStdRespOK = &OASResponse{
Description: "OK",
}
Functions ¶
func CalculateTTL ¶ added in v0.10.0
func CalculateTTL(sysView logical.SystemView, increment, backendTTL, period, backendMaxTTL, explicitMaxTTL time.Duration, startTime time.Time) (ttl time.Duration, warnings []string, errors error)
CalculateTTL takes all the user-specified, backend, and system inputs and calculates a TTL for a lease
func DeleteWAL ¶
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
Helper which returns a generic regex string for creating endpoint patterns that are identified by the given name in the backends
func GenericNameWithAtRegex ¶ added in v1.0.0
GenericNameWithAtRegex returns a generic regex that allows alphanumeric characters along with -, . and @.
func MatchAllRegex ¶ added in v1.0.0
Helper which returns a regex string for capturing an entire endpoint path as the given name.
func OptionalParamRegex ¶ added in v0.5.2
Helper which returns a regex string for optionally accepting the a field from the API URL
func PutWAL ¶
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.
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 // 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 // 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
Cleanup is used to release resources and prepare to stop the backend
func (*Backend) HandleExistenceCheck ¶ added in v0.5.0
func (b *Backend) HandleExistenceCheck(ctx context.Context, req *logical.Request) (checkFound bool, exists bool, err error)
HandleExistenceCheck is the logical.Backend implementation.
func (*Backend) HandleRequest ¶
func (b *Backend) HandleRequest(ctx context.Context, req *logical.Request) (*logical.Response, error)
HandleRequest is the logical.Backend implementation.
func (*Backend) InvalidateKey ¶ added in v0.6.5
InvalidateKey is used to clear caches and reset internal state on key changes
func (*Backend) Logger ¶
Logger can be used to get the logger. If no logger has been set, the logs will be discarded.
func (*Backend) Setup ¶ added in v0.2.0
Setup is used to initialize the backend with the initial backend configuration
func (*Backend) SpecialPaths ¶
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
CleanupFunc is the callback for backend unload.
type ExistenceFunc ¶ added in v0.9.2
ExistenceFunc is the callback called for an existence check on a path.
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 ¶
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
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) GetFirst ¶ added in v0.10.3
GetFirst gets the value for the given field names, in order from first to last. This can be useful for fields with a current name, and one or more deprecated names. The second return value will be false if the keys are invalid or the keys are not set at all.
func (*FieldData) GetOk ¶
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. If the field k is set and the decoded value is nil, the default or zero value will be returned instead.
func (*FieldData) GetOkErr ¶
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.
type FieldSchema ¶
type FieldSchema struct { Type FieldType Default interface{} Description string Required bool Deprecated bool }
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 // TypeLowerCaseString is a helper for TypeString that returns a lowercase // version of the provided string TypeLowerCaseString // 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 // TypeCommaIntSlice is a helper for TypeSlice that returns a sanitized // slice of Ints TypeCommaIntSlice // TypeHeader is a helper for sending request headers through to Vault. // For instance, the AWS and AliCloud credential plugins both act as a // benevolent MITM for a request, and the headers are sent through and // parsed. TypeHeader )
type InvalidateFunc ¶ added in v0.6.5
InvalidateFunc is the callback for backend key invalidation.
type OASContent ¶ added in v1.0.0
type OASContent map[string]*OASMediaTypeObject
type OASDocument ¶ added in v1.0.0
type OASDocument struct { Version string `json:"openapi" mapstructure:"openapi"` Info OASInfo `json:"info"` Paths map[string]*OASPathItem `json:"paths"` }
func NewOASDocument ¶ added in v1.0.0
func NewOASDocument() *OASDocument
NewOASDocument returns an empty OpenAPI document.
func NewOASDocumentFromMap ¶ added in v1.0.0
func NewOASDocumentFromMap(input map[string]interface{}) (*OASDocument, error)
NewOASDocumentFromMap builds an OASDocument from an existing map version of a document. If a document has been decoded from JSON or received from a plugin, it will be as a map[string]interface{} and needs special handling beyond the default mapstructure decoding.
func (*OASDocument) CreateOperationIDs ¶ added in v1.0.1
func (d *OASDocument) CreateOperationIDs(context string)
CreateOperationIDs generates unique operationIds for all paths/methods. The transform will convert path/method into camelcase. e.g.:
/sys/tools/random/{urlbytes} -> postSysToolsRandomUrlbytes
In the unlikely case of a duplicate ids, a numeric suffix is added:
postSysToolsRandomUrlbytes_2
An optional user-provided suffix ("context") may also be appended.
type OASInfo ¶ added in v1.0.0
type OASInfo struct { Title string `json:"title"` Description string `json:"description"` Version string `json:"version"` License OASLicense `json:"license"` }
type OASLicense ¶ added in v1.0.0
type OASMediaTypeObject ¶ added in v1.0.0
type OASMediaTypeObject struct {
Schema *OASSchema `json:"schema,omitempty"`
}
type OASOperation ¶ added in v1.0.0
type OASOperation struct { Summary string `json:"summary,omitempty"` Description string `json:"description,omitempty"` OperationID string `json:"operationId,omitempty"` Tags []string `json:"tags,omitempty"` Parameters []OASParameter `json:"parameters,omitempty"` RequestBody *OASRequestBody `json:"requestBody,omitempty"` Responses map[int]*OASResponse `json:"responses"` Deprecated bool `json:"deprecated,omitempty"` }
func NewOASOperation ¶ added in v1.0.0
func NewOASOperation() *OASOperation
NewOASOperation creates an empty OpenAPI Operations object.
type OASParameter ¶ added in v1.0.0
type OASPathItem ¶ added in v1.0.0
type OASPathItem struct { Description string `json:"description,omitempty"` Parameters []OASParameter `json:"parameters,omitempty"` Sudo bool `json:"x-vault-sudo,omitempty" mapstructure:"x-vault-sudo"` Unauthenticated bool `json:"x-vault-unauthenticated,omitempty" mapstructure:"x-vault-unauthenticated"` CreateSupported bool `json:"x-vault-create-supported,omitempty" mapstructure:"x-vault-create-supported"` Get *OASOperation `json:"get,omitempty"` Post *OASOperation `json:"post,omitempty"` Delete *OASOperation `json:"delete,omitempty"` }
type OASRequestBody ¶ added in v1.0.0
type OASRequestBody struct { Description string `json:"description,omitempty"` Content OASContent `json:"content,omitempty"` }
type OASResponse ¶ added in v1.0.0
type OASResponse struct { Description string `json:"description"` Content OASContent `json:"content,omitempty"` }
type OASSchema ¶ added in v1.0.0
type OASSchema struct { Type string `json:"type,omitempty"` Description string `json:"description,omitempty"` Properties map[string]*OASSchema `json:"properties,omitempty"` Items *OASSchema `json:"items,omitempty"` Format string `json:"format,omitempty"` Pattern string `json:"pattern,omitempty"` Example interface{} `json:"example,omitempty"` Deprecated bool `json:"deprecated,omitempty"` }
type OperationFunc ¶
OperationFunc is the callback called for an operation on a path.
func LeaseExtend ¶
func LeaseExtend(backendIncrement, backendMax time.Duration, systemView logical.SystemView) OperationFunc
LeaseExtend is left for backwards compatibility for plugins. This function now just passes back the data that was passed into it to be processed in core. DEPRECATED
type OperationHandler ¶ added in v1.0.0
type OperationHandler interface { Handler() OperationFunc Properties() OperationProperties }
OperationHandler defines and describes a specific operation handler.
type OperationProperties ¶ added in v1.0.0
type OperationProperties struct { // Summary is a brief (usually one line) description of the operation. Summary string // Description is extended documentation of the operation and may contain // Markdown-formatted text markup. Description string // Examples provides samples of the expected request data. The most // relevant example should be first in the list, as it will be shown in // documentation that supports only a single example. Examples []RequestExample // Responses provides a list of response description for a given response // code. The most relevant response should be first in the list, as it will // be shown in documentation that only allows a single example. Responses map[int][]Response // Unpublished indicates that this operation should not appear in public // documentation or help text. The operation may still have documentation // attached that can be used internally. Unpublished bool // Deprecated indicates that this operation should be avoided. Deprecated bool }
OperationProperties describes an operation for documentation, help text, and other clients. A Summary should always be provided, whereas other fields can be populated as needed.
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 // Operations is the set of operations supported and the associated OperationsHandler. // // If both Create and Update operations are present, documentation and examples from // the Update definition will be used. Similarly if both Read and List are present, // Read will be used for documentation. Operations map[logical.Operation]OperationHandler // 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. // // Deprecated: Operations should be used instead and will take priority if present. 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 ExistenceFunc // FeatureRequired, if implemented, will validate if the given feature is // enabled for the set of paths FeatureRequired license.Features // Deprecated denotes that this path is considered deprecated. This may // be reflected in help and documentation. Deprecated bool // 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 ¶
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 *saltpkg.Salt SaltFunc func(context.Context) (*saltpkg.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) Get ¶
func (p *PathMap) Get(ctx context.Context, s logical.Storage, k string) (map[string]interface{}, error)
Get reads a value out of the mapping
type PathOperation ¶ added in v1.0.0
type PathOperation struct { Callback OperationFunc Summary string Description string Examples []RequestExample Responses map[int][]Response Unpublished bool Deprecated bool }
PathOperation is a concrete implementation of OperationHandler.
func (*PathOperation) Handler ¶ added in v1.0.0
func (p *PathOperation) Handler() OperationFunc
func (*PathOperation) Properties ¶ added in v1.0.0
func (p *PathOperation) Properties() OperationProperties
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) Paths ¶
func (p *PathStruct) Paths() []*Path
Paths are the paths to append to the Backend paths.
type PolicyMap ¶
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.
type RequestExample ¶ added in v1.0.0
type RequestExample struct { Description string // optional description of the request Data map[string]interface{} // map version of sample JSON request data // Optional example response to the sample request. This approach is considered // provisional for now, and this field may be changed or removed. Response *Response }
RequestExample is example of request data.
type Response ¶ added in v1.0.0
type Response struct { Description string // summary of the the response and should always be provided MediaType string // media type of the response, defaulting to "application/json" if empty Example *logical.Response // example response data }
Response describes and optional demonstrations an operation response.
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 ¶
HandleRenew is the request handler for renewing this secret.
func (*Secret) HandleRevoke ¶
HandleRevoke is the request handler for renewing this secret.