vaku

Documentation

Overview

Package vaku provides an API for interacting with the Vault Key/Value secrets engine. Vaku works indentically on V1 and V2 K/V mount versions except in cases where the command is only supported on the V2 engine. Vaku supports many useful commands like copy, move, and search on Vault paths and folders alike.

Index

• Variables
• func AddPrefix(p, pfx string) string
• func AddPrefixList(l []string, pfx string)
• func EnsureFolder(p string) string
• func EnsurePrefix(p, pfx string) string
• func EnsurePrefixList(l []string, pfx string)
• func EnsurePrefixMap(m map[string]map[string]any, pfx string)
• func InsertIntoPath(path, after, insert string) string
• func IsFolder(p string) bool
• func PathJoin(p ...string) string
• func TrimPrefixList(l []string, pfx string)
• func TrimPrefixMap(m map[string]map[string]any, pfx string)
• func Version() string
• type Client
  • func NewClient(opts ...Option) (*Client, error)
  • func (c *Client) FolderCopy(ctx context.Context, src, dst string) error
  • func (c *Client) FolderDelete(ctx context.Context, p string) error
  • func (c *Client) FolderDeleteMeta(ctx context.Context, p string) error
  • func (c *Client) FolderDestroy(ctx context.Context, p string, versions []int) error
  • func (c *Client) FolderList(ctx context.Context, p string) ([]string, error)
  • func (c *Client) FolderListChan(ctx context.Context, p string) (<-chan string, <-chan error)
  • func (c *Client) FolderMove(ctx context.Context, src, dst string) error
  • func (c *Client) FolderRead(ctx context.Context, p string) (map[string]map[string]any, error)
  • func (c *Client) FolderReadChan(ctx context.Context, p string) (<-chan map[string]map[string]any, <-chan error)
  • func (c *Client) FolderSearch(ctx context.Context, path, search string) ([]string, error)
  • func (c *Client) FolderWrite(ctx context.Context, d map[string]map[string]any) error
  • func (c *Client) PathCopy(src, dst string) error
  • func (c *Client) PathDelete(p string) error
  • func (c *Client) PathDeleteMeta(p string) error
  • func (c *Client) PathDestroy(p string, versions []int) error
  • func (c *Client) PathList(p string) ([]string, error)
  • func (c *Client) PathMove(src, dst string) error
  • func (c *Client) PathRead(p string) (map[string]any, error)
  • func (c *Client) PathSearch(p, s string) (bool, error)
  • func (c *Client) PathUpdate(p string, d map[string]any) error
  • func (c *Client) PathWrite(p string, d map[string]any) error
• type ClientInterface
• type Mount
• type Option
  • func WithAbsolutePath(b bool) Option
  • func WithIgnoreAccessErrors(b bool) Option
  • func WithMountProvider(p mountProvider) Option
  • func WithVaultClient(c *vault.Client) Option
  • func WithVaultDstClient(c *vault.Client) Option
  • func WithVaultSrcClient(c *vault.Client) Option
  • func WithWorkers(n int) Option

Variables

var (
	// ErrNumWorkers when workers is not a supported number.
	ErrNumWorkers = errors.New("invalid workers")
	// ErrApplyOptions when options fails to apply.
	ErrApplyOptions = errors.New("applying options")
)

var (
	// ErrContext when ctx.Err() is not nil.
	ErrContext = errors.New("context")
	// ErrDecodeSecret when secret data cannot be extracted from a vault secret.
	ErrDecodeSecret = errors.New("decode secret")
	// ErrJSONMarshal when secret data cannot be marshaled into json.
	ErrJSONMarshal = errors.New("json marshal")
	// ErrNilData when passed data is nil.
	ErrNilData = errors.New("nil data")
	// ErrUnknownError when returning an error with no data.
	ErrUnknownError = errors.New("unknown error")
)

Errors that are not specific to one file/function.

var (
	// ErrFolderList when FolderList fails.
	ErrFolderList = errors.New("folder list")
	// ErrFolderListChan when FolderListChan fails.
	ErrFolderListChan = errors.New("folder list chan")
)

var (
	// ErrFolderRead when FolderRead fails.
	ErrFolderRead = errors.New("folder read")
	// ErrFolderReadChan when FolderReadChan fails.
	ErrFolderReadChan = errors.New("folder read chan")
)

var (
	// ErrMountInfo when failing to get mount information about a path.
	ErrMountInfo = errors.New("mount info")
	// ErrListMounts when failing to list vault mounts.
	ErrListMounts = errors.New("list mounts")
	// ErrNoMount when path cannot be matched to a mount.
	ErrNoMount = errors.New("no matching mount")
	// ErrRewritePath when failing to rewrite the path with mount data.
	ErrRewritePath = errors.New("rewriting path")
	// ErrMountVersion when an operation is not supported on the mount version.
	ErrMountVersion = errors.New("mount version does not support operation")
)

var (
	// ErrPathDelete when PathDelete fails.
	ErrPathDelete = errors.New("path delete")
	// ErrVaultDelete when the underlying Vault API delete fails.
	ErrVaultDelete = errors.New("vault delete")
)

var (
	// ErrPathList when PathList fails.
	ErrPathList = errors.New("path list")
	// ErrVaultList when the underlying Vault API list fails.
	ErrVaultList = errors.New("vault list")
)

var (
	// ErrPathRead when PathRead fails.
	ErrPathRead = errors.New("path read")
	// ErrVaultRead when the underlying Vault API read fails.
	ErrVaultRead = errors.New("vault read")
)

var (
	// ErrPathWrite when PathWrite errors.
	ErrPathWrite = errors.New("path write")
	// ErrVaultWrite when the underlying Vault API write fails.
	ErrVaultWrite = errors.New("vault write")
)

var (
	// ErrFolderCopy when FolderCopy fails.
	ErrFolderCopy = errors.New("folder copy")
)

var (
	// ErrFolderDelete when FolderDelete fails.
	ErrFolderDelete = errors.New("folder delete")
)

var (
	// ErrFolderDeleteMeta when FolderDeleteMeta fails.
	ErrFolderDeleteMeta = errors.New("folder delete meta")
)

var (
	// ErrFolderDestroy when FolderDestroy fails.
	ErrFolderDestroy = errors.New("folder destroy")
)

var (
	// ErrFolderMove when FolderMove fails.
	ErrFolderMove = errors.New("folder move")
)

var (
	// ErrFolderSearch when FolderSearch fails.
	ErrFolderSearch = errors.New("folder search")
)

var (
	// ErrFolderWrite when FolderWrite fails.
	ErrFolderWrite = errors.New("folder write")
)

var (
	// ErrPathCopy when PathCopy fails.
	ErrPathCopy = errors.New("path copy")
)

var (
	// ErrPathDeleteMeta when PathDeleteMeta fails.
	ErrPathDeleteMeta = errors.New("path delete meta")
)

var (
	// ErrPathDestroy when PathDestroy fails.
	ErrPathDestroy = errors.New("path destroy")
)

var (
	// ErrPathMove when PathMove fails.
	ErrPathMove = errors.New("path move")
)

var (
	// ErrPathSearch when PathSearch fails.
	ErrPathSearch = errors.New("path search")
)

var (
	// ErrPathUpdate when PathUpdate fails.
	ErrPathUpdate = errors.New("path update")
)

Functions

func AddPrefix

func AddPrefix(p, pfx string) string

AddPrefix adds a prefix to a path.

func AddPrefixList

func AddPrefixList(l []string, pfx string)

AddPrefixList adds a prefix to every item in a list.

func EnsureFolder

func EnsureFolder(p string) string

EnsureFolder ensures a path is a folder (adds a trailing "/").

func EnsurePrefix

func EnsurePrefix(p, pfx string) string

EnsurePrefix adds a prefix to a path if it doesn't already have it.

func EnsurePrefixList

func EnsurePrefixList(l []string, pfx string)

EnsurePrefixList adds a prefix to every item in a list if it doesn't already have it.

func EnsurePrefixMap

func EnsurePrefixMap(m map[string]map[string]any, pfx string)

EnsurePrefixMap ensures a prefix for every key in a map.

func InsertIntoPath

func InsertIntoPath(path, after, insert string) string

InsertIntoPath adds 'insert' into 'path' after 'after' and returns the new path.

func IsFolder

func IsFolder(p string) bool

IsFolder if path is a folder (ends in "/").

func PathJoin

func PathJoin(p ...string) string

PathJoin combines multiple paths into one.

func TrimPrefixList

func TrimPrefixList(l []string, pfx string)

TrimPrefixList removes a prefix from every item in a list.

func TrimPrefixMap

func TrimPrefixMap(m map[string]map[string]any, pfx string)

TrimPrefixMap removes a prefix from every key in a map.

func Version

func Version() string

Version gives the current Vaku API version.

Types

type Client

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

Client has all Vaku functions and wraps Vault API clients.

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient returns a new Vaku Client based on the Vault API config.

func (*Client) FolderCopy

func (c *Client) FolderCopy(ctx context.Context, src, dst string) error

FolderCopy copies data at a source folder to a destination folder..

func (*Client) FolderDelete

func (c *Client) FolderDelete(ctx context.Context, p string) error

FolderDelete recursively deletes the provided path and all subpaths.

func (*Client) FolderDeleteMeta

func (c *Client) FolderDeleteMeta(ctx context.Context, p string) error

FolderDeleteMeta deletes all secret metadata and versions for all secrets in a folder. Only works on v2 kv engines.

func (*Client) FolderDestroy

func (c *Client) FolderDestroy(ctx context.Context, p string, versions []int) error

FolderDestroy destroys versions of all secrets in a folder. Only works on v2 kv engines.

func (*Client) FolderList

func (c *Client) FolderList(ctx context.Context, p string) ([]string, error)

FolderList recursively lists the provided path and all subpaths.

func (*Client) FolderListChan

func (c *Client) FolderListChan(ctx context.Context, p string) (<-chan string, <-chan error)

FolderListChan recursively lists the provided path and all subpaths. Returns an unbuffered channel that can be read until close and an error channel that sends either the first error or nil when the work is done.

func (*Client) FolderMove

func (c *Client) FolderMove(ctx context.Context, src, dst string) error

FolderMove moves data at a source folder to a destination folder. Source is deleted after copy.

func (*Client) FolderRead

func (c *Client) FolderRead(ctx context.Context, p string) (map[string]map[string]any, error)

FolderRead recursively reads the provided path and all subpaths.

func (*Client) FolderReadChan

func (c *Client) FolderReadChan(ctx context.Context, p string) (<-chan map[string]map[string]any, <-chan error)

FolderReadChan recursively reads the provided path and all subpaths. Returns an unbuffered channel that can be read until close and an error channel that sends either the first error or nil when the work is done.

func (*Client) FolderSearch

func (c *Client) FolderSearch(ctx context.Context, path, search string) ([]string, error)

FolderSearch searches the provided path and all subpaths. Returns a list of paths in which the string was found.

func (*Client) FolderWrite

func (c *Client) FolderWrite(ctx context.Context, d map[string]map[string]any) error

FolderWrite writes data to a path. Multiple paths can be written to at once.

func (*Client) PathCopy

func (c *Client) PathCopy(src, dst string) error

PathCopy copies data at a source path to a destination path.

func (*Client) PathDelete

func (c *Client) PathDelete(p string) error

PathDelete deletes data at a path.

func (*Client) PathDeleteMeta

func (c *Client) PathDeleteMeta(p string) error

PathDeleteMeta deletes all secret metadata and versions. Only works on v2 kv engines.

func (*Client) PathDestroy

func (c *Client) PathDestroy(p string, versions []int) error

PathDestroy destroys versions of a secret at a path. Only works on v2 kv engines.

func (*Client) PathList

func (c *Client) PathList(p string) ([]string, error)

PathList lists paths at a path.

func (*Client) PathMove

func (c *Client) PathMove(src, dst string) error

PathMove moves data at a source path to a destination path (copy + delete).

func (*Client) PathRead

func (c *Client) PathRead(p string) (map[string]any, error)

PathRead reads data at a path.

func (*Client) PathSearch

func (c *Client) PathSearch(p, s string) (bool, error)

PathSearch searches for a string at a path.

func (*Client) PathUpdate

func (c *Client) PathUpdate(p string, d map[string]any) error

PathUpdate updates a path with data. New data (precedence) is merged with existing data.

func (*Client) PathWrite

func (c *Client) PathWrite(p string, d map[string]any) error

PathWrite writes data to a path.

type ClientInterface

type ClientInterface interface {
	PathList(string) ([]string, error)
	PathRead(string) (map[string]any, error)
	PathWrite(string, map[string]any) error
	PathDelete(string) error
	PathDeleteMeta(string) error
	PathDestroy(string, []int) error
	PathUpdate(string, map[string]any) error
	PathSearch(string, string) (bool, error)
	PathCopy(string, string) error
	PathMove(string, string) error

	FolderList(context.Context, string) ([]string, error)
	FolderListChan(context.Context, string) (<-chan string, <-chan error)
	FolderRead(context.Context, string) (map[string]map[string]any, error)
	FolderReadChan(context.Context, string) (<-chan map[string]map[string]any, <-chan error)
	FolderWrite(context.Context, map[string]map[string]any) error
	FolderDelete(context.Context, string) error
	FolderDeleteMeta(context.Context, string) error
	FolderDestroy(context.Context, string, []int) error
	FolderSearch(context.Context, string, string) ([]string, error)
	FolderCopy(context.Context, string, string) error
	FolderMove(context.Context, string, string) error
}

ClientInterface exports the interface for the full Vaku client.

type Mount

type Mount struct {
	Path    string
	Type    string
	Version string
}

Mount is a high level representation of selected fields of a vault mount that are relevant to vaku.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option configures a Client.

func WithAbsolutePath

func WithAbsolutePath(b bool) Option

WithAbsolutePath sets the output format for all returned paths. Default path output is a relative path, trimmed up to the path input. Pass WithAbsolutePath(true) to set path output to the entire path. Example: List(secret/foo) -> "bar" OR "secret/foo/bar".

func WithIgnoreAccessErrors

func WithIgnoreAccessErrors(b bool) Option

WithIgnoreAccessErrors allows errors on path reads to be ignored. This may be useful when listing and searching where you only have access to a subset of the paths. By default read errors will return an error but you can set this to true to silently ignore them.

func WithMountProvider

func WithMountProvider(p mountProvider) Option

WithMountProvider makes it possible to inject a custom method for listing mounts. The default method uses the sys/mounts endpoint. This requires a level of privilege that not all users may have.

func WithVaultClient

func WithVaultClient(c *vault.Client) Option

WithVaultClient sets the Vault client to be used.

func WithVaultDstClient

func WithVaultDstClient(c *vault.Client) Option

WithVaultDstClient sets a separate Vault client to be used only on operations that have a source and destination (copy, move, etc...). If unset the source client will be used.

func WithVaultSrcClient

func WithVaultSrcClient(c *vault.Client) Option

WithVaultSrcClient is an alias for WithVaultClient.

func WithWorkers

func WithWorkers(n int) Option

WithWorkers sets the maximum number of goroutines that access Vault at any given time. Does not cap the number of goroutines overall. Default value is 10. A stable and well-operated Vault server should be able to handle 100 or more without issue. Use with caution and tune specifically to your environment and storage backend.