vaultkv

package module
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Mar 23, 2023 License: Unlicense Imports: 19 Imported by: 7

README

vaultkv

How to Use

This is a GoDoc: https://godoc.org/github.com/cloudfoundry-community/vaultkv

If you want to do anything with this library, then you'll need to make a Client object. The Client object will need, at the very least, its VaultURI member populated. AuthToken should be set to your bearer token for Vault. If you need a bearer token created from some other auth method, you can call one of the AuthX functions (currently, we support Github, LDAP, Okta, and Userpass). An http client can be optionally provided (if not, then http.DefaultClient will be used). If you would like to see information about the requests and responses, then you can optionally provide an io.Writer for trace logs to be streamed to.

func main() {
  vault := &vaultkv.Client{
  AuthToken: "01234567-89ab-cdef-0123-456789abcdef",
    VaultURL: vaultURI,
    Client: &http.Client{
      Transport: &http.Transport{
        TLSClientConfig: &tls.Config{
          InsecureSkipVerify: true,
        },
      },
    },
    Trace: os.Stdout,
  }

  output := struct{
    Bar string `json:"bar"`
  }{}
  err := vault.Get("secret/foo", &output)
  if err != nil {
    os.Exit(1)
  }

  fmt.Printf("output.Bar is `%s'\n", output.Bar)
}

Testing

Run ./test in the base directory to test all supported Vault versions. Run ./test latest to test only the latest supported version of Vault.

Documentation

Overview

Package vaultkv provides a client with functions that make API calls that a user of Vault may commonly want.

Index

Constants

View Source 
const (
	//MountTypeGeneric is what the key value backend was called prior to 0.8.0
	MountTypeGeneric = "generic"
	//MountTypeKV is the type string to get a Key Value backend
	MountTypeKV = "kv"
)

Variables

This section is empty.

Functions

func IsAnyStandbyErr 

func IsAnyStandbyErr(err error) bool

IsAnyStandbyErr returns true if the error is that the node is a standby or a performance standby

func IsBadRequest 

func IsBadRequest(err error) bool

IsBadRequest returns true if the error is an ErrBadRequest

func IsErrDRSecondary 

func IsErrDRSecondary(err error) bool

IsErrDRSecondary returns true if the error is an ErrDRSecondary

func IsErrKVUnsupported 

func IsErrKVUnsupported(err error) bool

IsErrKVUnsupported returns true if the error is an ErrKVUnsupported

func IsErrPerfStandby 

func IsErrPerfStandby(err error) bool

IsErrPerfStandby returns true if the error is an ErrPerfStandby

func IsErrStandby 

func IsErrStandby(err error) bool

IsErrStandby returns true if the error is an ErrStandby

func IsForbidden 

func IsForbidden(err error) bool

IsForbidden returns true if the error is an ErrForbidden

func IsInternalServer 

func IsInternalServer(err error) bool

IsInternalServer returns true if the error is an ErrInternalServer

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound returns true if the error is an ErrNotFound

func IsSealed 

func IsSealed(err error) bool

IsSealed returns true if the error is an ErrSealed

func IsTransport 

func IsTransport(err error) bool

IsTransport returns true if the error is an ErrTransport

func IsUninitialized 

func IsUninitialized(err error) bool

IsUninitialized returns true if the error is an ErrUninitialized

Types

type AuthGithubMetadata 

type AuthGithubMetadata struct {
	Username     string `json:"username"`
	Organization string `json:"org"`
}

AuthGithubMetadata is the metadata member set by AuthGithub.

type AuthLDAPMetadata 

type AuthLDAPMetadata struct {
	Username string `json:"username"`
}

AuthLDAPMetadata is the metadata member set by AuthLDAP

type AuthOktaMetadata added in v0.5.0 

type AuthOktaMetadata struct {
	Username string `json:"username"`
}

AuthOktaMetadata is the metadata member set by AuthOkta

type AuthOutput 

type AuthOutput struct {
	Renewable     bool
	LeaseDuration time.Duration
	ClientToken   string
	Accessor      string
	Policies      []string
	//Metadata's internal structure is dependent on the auth type
	Metadata interface{}
}

AuthOutput is the general structure as returned by AuthX functions. The Metadata member type is determined by the specific Auth function. Note that the Vault must be initialized and unsealed in order to use authentication endpoints.

type AuthUserpassMetadata 

type AuthUserpassMetadata struct {
	Username string `json:"username"`
}

AuthUserpassMetadata is the metadata member set by AuthUserpass

type Client 

type Client struct {
	AuthToken string
	VaultURL  *url.URL
	//If Client is nil, http.DefaultClient will be used
	Client *http.Client
	//If Trace is non-nil, information about HTTP requests will be given into the
	//Writer.
	Trace io.Writer
	//Namespace, if non-empty, will send a X-Vault-Namespace header on requests with
	// the given value.
	Namespace string
	// contains filtered or unexported fields
}

Client provides functions that access and abstract the Vault API. VaultURL must be set to the for the client to work. Only Vault versions 0.6.5 and above are tested to work with this client.

func (*Client) AuthApprole 

func (v *Client) AuthApprole(roleID, secretID string) (ret *AuthOutput, err error)

AuthApprole performs auth against the given approle mount with the given approle ID and secret. If the login is successful, this client's AuthToken is set to the returned token. Given mountpoint is relative to /v1/auth.

func (*Client) AuthApproleMount added in v0.4.0 

func (v *Client) AuthApproleMount(mount, roleID, secretID string) (ret *AuthOutput, err error)

AuthApproleMount performs auth against the given approle mount with the given approle ID and secret. If the login is successful, this client's AuthToken is set to the returned token.

func (*Client) AuthGithub 

func (v *Client) AuthGithub(accessToken string) (ret *AuthOutput, err error)

AuthGithub is a shorthand for AuthGithubMount against the default github auth mountpoint, 'github'

func (*Client) AuthGithubMount added in v0.4.0 

func (v *Client) AuthGithubMount(mount, accessToken string) (ret *AuthOutput, err error)

AuthGithubMount submits the given accessToken to the github auth endpoint at the given mount, checking it against configurations for Github organizations. If the accessToken belongs to an authorized account, then the AuthOutput object is returned, and this client's AuthToken is set to the returned token. Given mountpoint is relative to /v1/auth.

func (*Client) AuthLDAP 

func (v *Client) AuthLDAP(username, password string) (ret *AuthOutput, err error)

AuthLDAP is a shorthand for AuthLDAPMount against the default LDAP mountpoint, 'ldap'.

func (*Client) AuthLDAPMount added in v0.4.0 

func (v *Client) AuthLDAPMount(mount, username, password string) (ret *AuthOutput, err error)

AuthLDAPMount submits the given username and password to the LDAP auth endpoint mounted at the given mountpoint, checking it against existing LDAP auth configurations. If auth is successful, then the AuthOutput object is returned, and this client's AuthToken is set to the returned token. Given mountpoint is relative to /v1/auth.

func (*Client) AuthOkta added in v0.5.0 

func (v *Client) AuthOkta(username, password string) (ret *AuthOutput, err error)

AuthOkta is a shorthand for AuthOktaMount against the default Okta mountpoint, 'okta'.

func (*Client) AuthOktaMount added in v0.5.0 

func (v *Client) AuthOktaMount(mount, username, password string) (ret *AuthOutput, err error)

AuthOktaMount submits the given username and password to the Okta auth endpoint mounted at the given mountpoint, checking it against existing Okta auth configurations. If auth is successful, then the AuthOutput object is returned, and this client's AuthToken is set to the returned token. Given mountpoint is relative to /v1/auth.

func (*Client) AuthUserpass 

func (v *Client) AuthUserpass(username, password string) (ret *AuthOutput, err error)

AuthUserpass is a shorthand for AuthUserpassMount for the default userpass mount point, 'userpass'.

func (*Client) AuthUserpassMount added in v0.4.0 

func (v *Client) AuthUserpassMount(mount, username, password string) (ret *AuthOutput, err error)

AuthUserpass submits the given username and password to the userpass auth endpoint located at the given mount. If a username with that password exists, then the AuthOutput object is returned, and this client's AuthToken is set to the returned token. Given mountpoint is relative to /v1/auth.

func (*Client) Curl 

func (v *Client) Curl(method string, path string, urlQuery url.Values, body io.Reader) (*http.Response, error)

Curl takes the given path, prepends <VaultURL>/v1/ to it, and makes the request with the remainder of the given parameters. Errors returned only reflect transport errors, not HTTP semantic errors

func (*Client) CurrentRekey 

func (v *Client) CurrentRekey() (*Rekey, error)

CurrentRekey returns a *Rekey with the state necessary to continue a rekey operation if one is in progress. If no rekey is in progress, *ErrNotFound is returned and no *Rekey is returned.

func (*Client) Delete 

func (v *Client) Delete(path string) error

Delete attempts to delete the value at the specified path. No error is returned if there is already no value at the given path.

func (*Client) DisableSecretsMount 

func (c *Client) DisableSecretsMount(path string) error

DisableSecretsMount deletes the mount at the given path.

func (*Client) EnableSecretsMount 

func (c *Client) EnableSecretsMount(path string, config Mount) error

EnableSecretsMount mounts a secrets backend at the given path, configured with the given Mount configuration.

func (*Client) GenerateRootCancel 

func (v *Client) GenerateRootCancel() error

GenerateRootCancel cancels the current generate root operation

func (*Client) Get 

func (v *Client) Get(path string, output interface{}) error

Get retrieves the secret at the given path and unmarshals it into the given output object using the semantics of encoding/json.Unmarshal. If the object is nil, an unmarshal will not be attempted (this can be used to check for existence). If the object could not be unmarshalled into, the resultant error is returned. Example path would be /secret/foo, if Key/Value backend were mounted at "/secret". The Vault must be unsealed and initialized for this endpoint to work. No assumptions are made about the mounting point of your Key/Value backend.

func (*Client) Health 

func (v *Client) Health(standbyok bool) error

Health gives information about the current state of the Vault. If standbyok is set to true, no error will be returned in the case that the targeted vault is a standby node or a performance standby node. If the targeted node is a standby and standbyok is false, then ErrStandby will be returned. If the Vault is not yet initialized, ErrUninitialized will be returned. If the Vault is initialized but sealed, then ErrSealed will be returned. If none of these are the case, no error is returned.

func (*Client) InitVault 

func (v *Client) InitVault(in InitConfig) (out *InitVaultOutput, err error)

InitVault puts to the /sys/init endpoint to initialize the Vault, and returns the root token and unseal keys that were generated. The token of the client object is automatically set to the root token if the init is successful. If the vault has already been initialized, this returns *ErrBadRequest

func (*Client) IsInitialized 

func (v *Client) IsInitialized() (is bool, err error)

IsInitialized returns true if the targeted Vault is initialized

func (*Client) IsKVv2Mount 

func (c *Client) IsKVv2Mount(path string) (mountPath string, isV2 bool, err error)

IsKVv2Mount returns true if the mount is a version 2 KV mount and false otherwise. This will also simply return false if no mount exists at the given mount point or if the Vault is too old to have the API endpoint to look for the mount. If a different API error occurs, it will be propagated out.

func (*Client) List 

func (v *Client) List(path string) ([]string, error)

List returns the list of paths nested directly under the given path. If this is not a "directory" for any paths, then ErrNotFound is returned. In the list of paths returned on success, if a path ends with a slash, then it is also a "directory". The Vault must be unsealed and initialized for this endpoint to work. No assumptions are made about the mounting point of your Key/Value backend.

func (*Client) ListMounts 

func (c *Client) ListMounts() (map[string]Mount, error)

ListMounts queries the Vault backend for a list of active mounts that can be seen with the current authentication token. It is returned as a map of mount points to mount information.

func (*Client) NewGenerateRoot 

func (v *Client) NewGenerateRoot() (*GenerateRoot, error)

NewGenerateRoot initializes and returns a new generate root object.

func (*Client) NewKV 

func (v *Client) NewKV() *KV

NewKV returns an initialized KV object.

func (*Client) NewRekey 

func (v *Client) NewRekey(conf RekeyConfig) (*Rekey, error)

NewRekey will start a new rekey operation. If successful, a *Rekey is returned containing the necessary state for submitting keys for this rekey operation.

func (*Client) RekeyCancel 

func (v *Client) RekeyCancel() error

RekeyCancel tells Vault to forget about the current rekey operation

func (*Client) ResetUnseal 

func (v *Client) ResetUnseal() (err error)

ResetUnseal resets the current unseal attempt, such that the progress towards an unseal becomes 0. If the vault is unsealed, nothing happens and no error is returned.

func (*Client) Seal 

func (v *Client) Seal() error

Seal puts to the /sys/seal endpoint to seal the Vault. If the Vault is already sealed, this doesn't return an error. If the Vault is unsealed and an incorrect token is provided, then this returns *ErrForbidden. Newer versions of Vault (0.11.2+) APIs return errors if the Vault is uninitialized or already sealed. This function squelches these errors for consistency with earlier versions of Vault

func (*Client) SealStatus 

func (v *Client) SealStatus() (ret *SealState, err error)

SealStatus calls the /sys/seal-status endpoint and returns the info therein

func (*Client) Set 

func (v *Client) Set(path string, values interface{}) error

Set puts the values in the given object at the given path. The given object must marshal into a JSON hash from string->anything (see: a golang map or struct). The Vault must be unsealed and initialized for this endpoint to work. No assumptions are made about the mounting point of your Key/Value backend.

func (*Client) SetAuthToken 

func (v *Client) SetAuthToken(token string)

SetAuthToken provides a thread-safe way to set the auth token for the client. Setting AuthToken directly is still valid, but may race if a coroutine can possibly make a request with the client while the AuthToken is being written to. This function handles a mutex which avoids that.

func (*Client) TokenInfoSelf 

func (v *Client) TokenInfoSelf() (ret *TokenInfo, err error)

TokenInfoSelf returns the contents of the token self info endpoint of the vault

func (*Client) TokenIsValid 

func (v *Client) TokenIsValid() (err error)

TokenIsValid returns no error if it can look itself up. This can error if the token is valid but somebody has configured policies such that it can not look itself up. It can also error, of course, if the token is invalid.

func (*Client) TokenRenewSelf 

func (v *Client) TokenRenewSelf() (err error)

TokenRenewSelf takes the token in the Client object and attempts to renew its lease.

func (*Client) TuneSecretsMount added in v0.2.0 

func (c *Client) TuneSecretsMount(path string, opts TuneMountOptions) error

TuneSecretsMount updates the configuration of the mount at the given path.

func (*Client) Unseal 

func (v *Client) Unseal(key string) (out *SealState, err error)

Unseal puts to the /sys/unseal endpoint with a single key to progress the unseal attempt. If the unseal was successful, then the Sealed member of the returned struct will be false. If the given unseal key is improperly formatted, an *ErrBadRequest is returned. If the vault is already unsealed, no error is returned

func (*Client) UpgradeKVToV2 added in v0.2.0 

func (c *Client) UpgradeKVToV2(path string) error

UpgradeKVToV2 sets the version of the mount (presumably KV mount) to the version 2. Just a shorthand wrapper for TuneSecretsMount with the appropriate opts structure.

func (*Client) V2Delete 

func (c *Client) V2Delete(mount, subpath string, opts *V2DeleteOpts) error

V2Delete marks a secret version at the given path as deleted. If opts is not provided or the Versions slice therein is left nil, the latest version is deleted. Otherwise, the specified versions are deleted. Note that the deleted data from this call is recoverable from a call to V2Undelete.

func (*Client) V2Destroy 

func (c *Client) V2Destroy(mount, subpath string, versions []uint) error

V2Destroy permanently deletes the specified versions at the specified path.

func (*Client) V2DestroyMetadata 

func (c *Client) V2DestroyMetadata(mount, subpath string) error

V2DestroyMetadata permanently destroys all secret versions and all metadata associated with the secret at the specified path.

func (*Client) V2Get 

func (c *Client) V2Get(mount, subpath string, output interface{}, opts *V2GetOpts) (meta V2Version, err error)

V2Get will get a secret from the given path in a KV version 2 secrets backend. If the secret is at "/bar" in the backend mounted at "foo", then the path should be "foo/bar". The response will be decoded into the item pointed to by output using encoding/json.Unmarshal semantics. The version to retrieve can be selected by setting Version in the V2GetOpts struct at opts.

func (*Client) V2GetMetadata 

func (c *Client) V2GetMetadata(mount, subpath string) (meta V2Metadata, err error)

V2GetMetadata gets the metadata associated with the secret at the specified path.

func (*Client) V2List 

func (c *Client) V2List(mount, subpath string) ([]string, error)

V2List returns the list of paths nested directly under the given path. If this is not a "directory" for any paths, then ErrNotFound is returned. In the list of paths returned on success, if a path ends with a slash, then it is also a "directory". The Vault must be unsealed and initialized for this endpoint to work. No assumptions are made about the mounting point of your Key/Value backend.

func (*Client) V2Set 

func (c *Client) V2Set(mount, subpath string, values interface{}, opts *V2SetOpts) (meta V2Version, err error)

V2Set uses encoding/json.Marshal on the object given in values to encode the secret as JSON, and writes it to the path given. Populate ops to use the check-and-set functionality. Returns the metadata about the written secret if the write is successful.

func (*Client) V2Undelete 

func (c *Client) V2Undelete(mount, subpath string, versions []uint) error

V2Undelete marks the specified versions at the specified paths as not deleted.

type ErrBadRequest 

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

ErrBadRequest represents 400 status codes that are returned from the API. See: your fault.

func (*ErrBadRequest) Error 

func (e *ErrBadRequest) Error() string

type ErrDRSecondary 

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

ErrDRSecondary is only returned from Health() if standbyok is set to false and the node you're querying is a secondary disaster recovery node.

func (*ErrDRSecondary) Error 

func (e *ErrDRSecondary) Error() string

type ErrForbidden 

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

ErrForbidden represents 403 status codes returned from the API. This could be if your auth is wrong or expired, or you simply don't have access to do the particular thing you're trying to do. Check your privilege.

func (*ErrForbidden) Error 

func (e *ErrForbidden) Error() string

type ErrInternalServer 

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

ErrInternalServer represents 500 status codes that are returned from the API. See: their fault.

func (*ErrInternalServer) Error 

func (e *ErrInternalServer) Error() string

type ErrKVUnsupported 

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

ErrKVUnsupported is returned by the KV object when the user requests an operation that cannot be performed by the actual version of the KV backend that the KV object is abstracting

func (*ErrKVUnsupported) Error 

func (e *ErrKVUnsupported) Error() string

type ErrNotFound 

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

ErrNotFound represents 404 status codes returned from the API. This could be either that the thing you're looking for doesn't exist, or in some cases that you don't have access to the thing you're looking for and that Vault is hiding it from you.

func (*ErrNotFound) Error 

func (e *ErrNotFound) Error() string

type ErrPerfStandby 

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

ErrPerfStandby is only returned from Health() if standbyok is set to false and the node you're querying is a performance standby node.

func (*ErrPerfStandby) Error 

func (e *ErrPerfStandby) Error() string

type ErrSealed 

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

ErrSealed represents the 503 status code that is returned by Vault most commonly if the Vault is currently sealed, but could also represent the Vault being in a maintenance state.

func (*ErrSealed) Error 

func (e *ErrSealed) Error() string

type ErrStandby 

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

ErrStandby is only returned from Health() if standbyok is set to false and the node you're querying is a standby.

func (*ErrStandby) Error 

func (e *ErrStandby) Error() string

type ErrTransport 

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

ErrTransport is returned if an error was encountered trying to reach the API, as opposed to an error from the API, is returned

func (*ErrTransport) Error 

func (e *ErrTransport) Error() string

type ErrUninitialized 

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

ErrUninitialized represents a 503 status code being returned and the Vault being uninitialized.

func (*ErrUninitialized) Error 

func (e *ErrUninitialized) Error() string

type GenerateRoot 

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

GenerateRoot has functions for generating a new root token. Create this object with NewGenerateRoot(). That function performs the necessary initialization for the process

func (*GenerateRoot) Cancel 

func (g *GenerateRoot) Cancel() error

Cancel cancels the current generate root operation

func (*GenerateRoot) Remaining 

func (g *GenerateRoot) Remaining() int

Remaining returns the number of keys yet required by this generate root token operation. This does not refresh state, and only reflects the last action of this GenerateRoot object.

func (*GenerateRoot) RootToken 

func (g *GenerateRoot) RootToken() (string, error)

RootToken returns the new root token from this operation if the operation has been successful. The return value is undefined if the operation is not yet successful.

func (*GenerateRoot) State 

func (g *GenerateRoot) State() GenerateRootState

State returns the current state of the generate root operation. This does not refresh state, and only reflects the last action of this GenerateRoot object.

func (*GenerateRoot) Submit 

func (g *GenerateRoot) Submit(keys ...string) (done bool, err error)

Submit gives keys to the generate root token operation specified by this *GenerateRoot object. Any keys beyond the current required amount are ignored. If the Rekey is successful after all keys have been sent, then done will be returned as true. If the threshold is reached and any of the keys were incorrect, an *ErrBadRequest is returned and done is false. In this case, the generate root is not cancelled, but is instead reset. No error is given for an incorrect key before the threshold is reached. An *ErrBadRequest may also be returned if there is no longer any generate root token operation in progress, but in this case, done will be returned as true. To retrieve the new keys after submitting enough existing keys, call RootToken() on the GenerateRoot object.

type GenerateRootState 

type GenerateRootState struct {
	Started  bool   `json:"started"`
	Nonce    string `json:"nonce"`
	Progress int    `json:"progress"`
	Required int    `json:"required"`
	//Vault versions >= 0.9.x return the value as encoded_token
	EncodedToken string `json:"encoded_token"`
	//Vault versions before 0.9.x returned the value as encoded_root_token
	EncodedRootToken string `json:"encoded_root_token"`
	//Vault versions before 0.11.2 had the user generate their own 16-byte root token
	// Versions after that have the API generate it for you (at a length that is
	// decided by the API).
	OTP       string `json:"otp"`
	OTPLength int    `json:"otp_length"`
	Complete  bool   `json:"complete"`
}

GenerateRootState contains state information about the GenerateRoot operation

type InitConfig 

type InitConfig struct {
	//Split the master key into this many shares
	Shares int `json:"secret_shares"`
	//This many shares are required to reconstruct the master key
	Threshold       int      `json:"secret_threshold"`
	RootTokenPGPKey string   `json:"root_token_pgp_key"`
	PGPKeys         []string `json:"pgp_keys"`
}

InitConfig is the information passed to InitVault to configure the Vault. Shares and Threshold are required.

type InitVaultOutput 

type InitVaultOutput struct {
	Keys       []string `json:"keys"`
	KeysBase64 []string `json:"keys_base64"`
	RootToken  string   `json:"root_token"`
	// contains filtered or unexported fields
}

InitVaultOutput is the return value of InitVault, and contains the generated Keys and RootToken.

func (*InitVaultOutput) Unseal 

func (i *InitVaultOutput) Unseal() error

Unseal takes the keys in the InitVaultOutput object and sends each one to the unseal endpoint. If any of the unseal calls are unsuccessful, an error is returned.

type KV 

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

KV provides an abstraction to the Vault tree which makes dealing with the potential of both KV v1 and KV v2 backends easier to work with. KV v1 backends are exposed through this interface much like KV v2 backends with only one version. There are limitations around Delete and Undelete calls because of the lack of versioning in KV v1 backends. See the documentation around those functions for more details. An empty KV struct is not request-ready. Please call Client.NewKV instead.

func (*KV) Delete 

func (k *KV) Delete(path string, opts *KVDeleteOpts) (err error)

Delete attempts to mark the secret at the given path (and version) as deleted. For KV v1, temporarily deleting a secret is not possible. Use the V1Destroy option as a way to safeguard against unwanted destruction of secrets.

func (*KV) Destroy 

func (k *KV) Destroy(path string, versions []uint) (err error)

Destroy attempts to irrevocably delete the given versions at the given path. For KV v1 backends, this is a call to Client.Delete. for KV v2 backends, this is a call to Client.V2Destroy

func (*KV) DestroyAll 

func (k *KV) DestroyAll(path string) (err error)

DestroyAll attempts to irrevocably delete all versions of the secret at the given path. For KV v1 backends, this is a call to Client.Delete. For v2 backends, this is a call to Client.V2DestroyMetadata

func (*KV) Get 

func (k *KV) Get(path string, output interface{}, opts *KVGetOpts) (meta KVVersion, err error)

Get retrieves the value at the given path in the tree. This follows the semantics of Client.Get or Client.V2Get, chosen based on the backend mounted at the path given.

func (*KV) List 

func (k *KV) List(path string) (paths []string, err error)

List retrieves the paths under the given path. If the path does not exist or it is not a folder, ErrNotFound is thrown. Results ending with a slash are folders.

func (*KV) MountPath 

func (k *KV) MountPath(path string) (mount string, err error)

MountPath returns the path of the mount on which the given path is mounted. If no such mount can be found, an error is returned.

func (*KV) MountVersion 

func (k *KV) MountVersion(mount string) (version uint, err error)

MountVersion returns the KV version of the mount for the given path. v1 mounts return 1; v2 mounts return 2.

func (*KV) Set 

func (k *KV) Set(path string, values interface{}, opts *KVSetOpts) (meta KVVersion, err error)

Set puts the values given at the path given. If KV v1, the previous value, if any, is overwritten. If KV v2, a new version is created.

func (*KV) Undelete 

func (k *KV) Undelete(path string, versions []uint) (err error)

Undelete attempts to unmark deletion on a previously deleted version. KV v1 backends cannot do this, and so if the backend is KV v1, this returns an ErrKVUnsupported.

func (*KV) Versions 

func (k *KV) Versions(path string) (ret []KVVersion, err error)

Versions returns the versions of the secret available. If no secret exists at this path, ErrNotFound is returned. If the secret exists and this is a KV v1 backend, one version is returned.

type KVDeleteOpts 

type KVDeleteOpts struct {
	//Versions are the versions of the secret to delete. If left nil,
	// the latest version is deleted.
	Versions []uint
	//V1Destroy, if true, will call Client.Delete if the given path
	// to delete is a V1 backend (thus permanently destroying the secret).
	// If it is false and the backend is V1, an ErrKVUnsupported error will
	// be thrown. This has no effect on KV v2 backends.
	V1Destroy bool
}

KVDeleteOpts are options applicable to KV.Delete

type KVGetOpts 

type KVGetOpts struct {
	// Version is the version of the resource to retrieve. Setting this to zero (or
	// not setting it at all) will retrieve the latest version
	Version uint
}

KVGetOpts are options applicable to KV.Get

type KVMountOptions 

type KVMountOptions map[string]interface{}

KVMountOptions is a map[string]interface{} that can be given as the options when mounting a backend. It has Version manipulation functions to make life easier.

func (KVMountOptions) GetVersion 

func (o KVMountOptions) GetVersion() int

GetVersion retruns the version held in the KVMountOptions object

func (KVMountOptions) WithVersion 

func (o KVMountOptions) WithVersion(version int) KVMountOptions

WithVersion returns a new KVMountOptions object with the given version

type KVSetOpts 

type KVSetOpts struct{}

KVSetOpts are the options for a set call to the KV.Set() call. Currently there are none, but it exists in case the API adds support in the future for things that we can put here.

type KVVersion 

type KVVersion struct {
	//If KV version is 1, CreatedAt.IsZero() will be true
	CreatedAt time.Time
	Version   uint
	Deleted   bool
	Destroyed bool
}

KVVersion contains information about a version of a secret.

func (KVVersion) Alive added in v0.2.0 

func (k KVVersion) Alive() bool

Alive returns if the KVVersion is not deleted or destroyed.

type Mount 

type Mount struct {
	//The type of mount at this point
	Type        string
	Description string
	Config      *MountConfig
	Options     map[string]interface{}
}

Mount represents a backend mounted at a point in Vault.

type MountConfig 

type MountConfig struct {
	DefaultLeaseTTL time.Duration
	MaxLeaseTTL     time.Duration
	PluginName      string
	ForceNoCache    bool
}

MountConfig specifies configuration options given when initializing a backend.

type Rekey 

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

Rekey represents a rekey operation currently in progress in the Vault. This wraps an otherwise cumbersome rekey API. Remaining() can be called to see how many keys are still required by the rekey, and then those many keys can be sent through one or more calls to Submit(). This should be created through a call to NewRekey or CurrentRekey. Using an uninitialized Rekey struct will lead to undefined behavior.

func (*Rekey) Cancel 

func (r *Rekey) Cancel() error

Cancel tells Vault to forget about the current rekey operation

func (*Rekey) Keys 

func (r *Rekey) Keys() []string

Keys returns the new keys from this rekey operation if the operation has been successful. The return value is undefined if the rekey operation is not yet successful.

func (*Rekey) Remaining 

func (r *Rekey) Remaining() int

Remaining returns the number of keys yet required by this rekey operation. This does not refresh state. If you believe that an external agent may have changed the state of the rekey, get a new rekey object with CurrentRekey, or Submit another key.

func (*Rekey) State 

func (r *Rekey) State() RekeyState

State returns the current state of the rekey operation. This does not refresh state. If you believe that an external agent may have changed the state of the rekey, get a new rekey object with CurrentRekey, or Submit another key.

func (*Rekey) Submit 

func (r *Rekey) Submit(keys ...string) (done bool, err error)

Submit gives keys to the rekey operation specified by this *Rekey object. Any keys beyond the current required amount are ignored. If the Rekey is successful after all keys have been sent, then done will be returned as true. If the threshold is reached and any of the keys were incorrect, an *ErrBadRequest is returned and done is false. In this case, the rekey is not cancelled, but is instead reset. No error is given for an incorrect key before the threshold is reached. An *ErrBadRequest may also be returned if there is no longer any rekey in progress, but in this case, done will be returned as true. To retrieve the new keys after submitting enough existing keys, call Keys() on the Rekey object.

type RekeyConfig 

type RekeyConfig struct {
	Shares    int      `json:"secret_shares"`
	Threshold int      `json:"secret_threshold"`
	PGPKeys   []string `json:"pgp_keys,omitempty"`
	Backup    bool     `json:"backup,omitempty"`
}

RekeyConfig is given to NewRekey to configure the parameters of the rekey operation to be started.

type RekeyState 

type RekeyState struct {
	Started          bool   `json:"started"`
	Nonce            string `json:"nonce"`
	PendingThreshold int    `json:"t"`
	PendingShares    int    `json:"n"`
	//The number of keys given so far in this rekey operation
	Progress int `json:"progress"`
	//The total number of keys needed for this rekey operation
	Required        int      `json:"required"`
	PGPFingerprints []string `json:"pgp_fingerprints"`
	Backup          bool     `json:"backup"`
}

RekeyState gives the state of the rekey operation as of the last call to Submit, NewRekey, or CurrentRekey.

type SealState 

type SealState struct {
	//Type is the type of unseal key. It is not returned from Unseal
	Type   string `json:"type,omitempty"`
	Sealed bool   `json:"sealed"`
	//Threshold is the number of keys required to reconstruct the master key
	Threshold int `json:"t"`
	//NumShares is the number of keys the master key has been split into
	NumShares int `json:"n"`
	//Progress is the number of keys that have been provided in the current unseal attempt
	Progress int    `json:"progress"`
	Nonce    string `json:"nonce"`
	Version  string `json:"version"`
	//ClusterName is only returned from an unsealed Vault.
	ClusterName string `json:"cluster_name,omitempty"`
	//ClusterID is only returned from an unsealed Vault.
	ClusterID string `json:"cluster_id,omitempty"`
}

SealState is the return value from Unseal and SealStatus. Type is only populated by SealStatus. ClusterName and ClusterID are only populated is Vault is unsealed.

type TokenInfo 

type TokenInfo struct {
	Accessor       string
	CreationTime   time.Time
	CreationTTL    time.Duration
	DisplayName    string
	EntityID       string
	ExpireTime     time.Time
	ExplicitMaxTTL time.Duration
	ID             string
	IssueTime      time.Time
	NumUses        int64
	Orphan         bool
	Path           string
	Policies       []string
	Renewable      bool
	TTL            time.Duration
}

TokenInfo contains metadata about a token. Return values from the Vault API are converted into more easily usable Golang types.

type TuneMountOptions added in v0.2.0 

type TuneMountOptions struct {
	Description     string
	DefaultLeaseTTL time.Duration
	MaxLeaseTTL     time.Duration
	Options         map[string]interface{}
}

TuneMountOptions are parameters to be sent to the Vault when editing the configuration of a mount. Only non-empty values will be sent.

type V2DeleteOpts 

type V2DeleteOpts struct {
	Versions []uint `json:"versions"`
}

V2DeleteOpts are options that can be provided to a V2Delete call.

type V2GetOpts 

type V2GetOpts struct {
	// Version is the version of the resource to retrieve. Setting this to zero (or
	// not setting it at all) will retrieve the latest version
	Version uint
}

V2GetOpts are options to specify in a V2Get request.

type V2Metadata 

type V2Metadata struct {
	CreatedAt time.Time
	UpdatedAt time.Time
	//CurrentVersion is the highest version number that has been created for this
	//secret. Deleteing or destroying the highest version does not change this
	//number.
	CurrentVersion uint
	OldestVersion  uint
	MaxVersions    uint
	Versions       []V2Version
}

V2Metadata is the metadata associated with a secret

func (V2Metadata) Version 

func (m V2Metadata) Version(number uint) (version V2Version, err error)

Version returns the version with the given number in the metadata as a V2Version object , if present. If no version with that number is present, an error is returned.

type V2SetOpts 

type V2SetOpts struct {
	//CAS provides a check-and-set version number. If this is set to zero, then
	// the value will only be written if the key does not yet exist. If the CAS
	//number is non-zero, then this will only be written if the current version
	//for your this secret matches the CAS value.
	CAS *uint `json:"cas,omitempty"`
}

V2SetOpts are options that can be specified to a V2Set call

func (V2SetOpts) WithCAS 

func (s V2SetOpts) WithCAS(i uint) *V2SetOpts

WithCAS returns a pointer to a new V2SetOpts with the CAS value set to the given value. If i is zero, then the value will only be written if the key does not exist. If i is non-zero, then the value will only be written if the currently existing version matches i. Not calling CAS will result in no restriction on writing. If the mount is set up for requiring CAS, then not setting CAS with this function a valid number will result in a failure when attempting to write.

type V2Version 

type V2Version struct {
	CreatedAt time.Time
	DeletedAt *time.Time
	Destroyed bool
	Version   uint
}

V2Version is information about a version of a secret. The DeletedAt member will be nil to signify that a version is not deleted. Take note of the difference between "deleted" and "destroyed" - a deletion simply marks a secret as deleted, preventing it from being read. A destruction actually removes the data from storage irrevocably.

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.