libvault v0.1.0 Vault.Engine.KVV2

Get and put secrets using the v2 KV (versioned) secrets engine

See: Vault Docs for details.

Link to this section Summary

Functions

Soft or Hard Delete a versioned secret. Requires a list of versions to be removed. This request produces an empty body, so an empty map is returned

This endpoint returns a list of key names at the specified location. Folders are suffixed with /. The input must be a folder; list on a file will not return a value

Get a secret from vault. Optionally supply a version, otherwise gets latest value

Put a secret in vault, on a given path

Link to this section Types

Link to this type errors()
errors() :: list()
Link to this type options()
options() :: list()
Link to this type path()
path() :: String.t()
Link to this type token()
token() :: String.t()
Link to this type value()
value() :: map()
Link to this type vault()
vault() :: Vault.t()
Link to this type version()
version() :: integer()

Link to this section Functions

Link to this function delete(vault, path, options \\ [])
delete(vault(), path(), options()) :: {:ok, map()} | {:error, errors()}

Soft or Hard Delete a versioned secret. Requires a list of versions to be removed. This request produces an empty body, so an empty map is returned.

Examples

Soft delete a version of a secret

{:ok, %{
    "data" => nil,
    "metadata" => %{
      "created_time" => "2018-11-21T19:49:49.339727561Z",
      "deletion_time" => "2018-11-21T19:49:49.353904424Z",
      "destroyed" => false,
      "version" => 5
    }
  } 
} = Vault.Engine.KVV2.Delete(vault, "path/to/delete", versions: [5], full_response: true)

Hard delete a secret {:ok, %{

"data" => nil,
"metadata" => %{
  "created_time" => "2018-11-21T19:49:49.339727561Z",
  "deletion_time" => "2018-11-21T19:49:49.353904424Z",
  "destroyed" => true,
  "version" => 5
}

} } = Vault.Engine.KVV2.Delete(vault, “path/to/delete”, versions: [5], destroy: true, full_response: true)

Link to this function list(vault, path, options \\ [])
list(vault(), path(), options()) :: {:ok, map()} | {:error, errors()}

This endpoint returns a list of key names at the specified location. Folders are suffixed with /. The input must be a folder; list on a file will not return a value.

Examples

{:ok, %{ 
    "keys"=> ["foo", "foo/"] 
  } 
} = Vault.Engine.KVV2.List(vault, "path/to/list/", [full_response: true])

With the full Response:

{:ok, %{
    "data" => %{
      "keys"=> ["foo", "foo/"]
    },
  }
}  = Vault.Engine.KVV2.List(vault, "path/to/list/", [full_response: true])
Link to this function read(vault, path, options \\ [])
read(vault(), path(), options()) :: {:ok, value()} | {:error, errors()}

Get a secret from vault. Optionally supply a version, otherwise gets latest value.

Examples

Fetch a value at a specific version, with the :version option.

{:ok, %{"foo" => "bar"}} = Vault.Engine.KVV2.read(vault, "secret/to/get, [version: 1])
{:ok, %{"bar" => "baz"}} = Vault.Engine.KVV2.read(vault, "secret/to/get, [version: 2])

Because of the nature of soft deletes,fetching soft-deleted secrets will return an error.

{:error, ["Key not found"]} = Vault.Engine.KVV2.read(vault, "soft/deleted/secret", [version: 1])

However, if you wish to see the metadata or additional values, setting full_response to true will return can return a soft deleted key as a success.

{:ok,  %{
    "auth" => nil,
    "data" => %{
      "data" => nil,
      "metadata" => %{
        "created_time" => "2018-11-21T19:49:49.339727561Z",
        "deletion_time" => "2018-11-21T19:49:49.353904424Z",
        "destroyed" => false,
        "version" => 1
      }
    },
    "lease_duration" => 0,
    "lease_id" => "",
    "renewable" => false,
    "request_id" => "e289ff31-609f-44fa-7161-55c63fda3d43",
    "warnings" => nil,
    "wrap_info" => nil
  } 
} = Vault.Engine.KVV2.read(vault, "soft/deleted/secret", [version: 1, full_response: true])

Options:

  • version: integer - the version you want to return.
  • full_response: boolean - get the whole reponse back on success, not just the data field
Link to this function write(vault, path, value, options \\ [])
write(vault(), path(), value(), options()) :: {:ok, map()} | {:error, errors()}

Put a secret in vault, on a given path.

Examples

Write a new version:

{:ok, %{}} = Vault.Engine.Generic.write(vault, "path/to/write", %{ foo: "bar" })

Check and set - see Vault Docs for details

# write only if the value doesn't exist
{:ok, response } = Vault.Engine.Generic.write(vault, "path/to/write", %{ foo: "bar" }, [cas: 0])

# write only if the cas matches the current secret version
{:ok, response } = Vault.Engine.Generic.write(vault, "path/to/write", %{ foo: "bar" }, [cas: 1])

Get the full response body from vault:

  {:ok, %{
      "data" => %{
        "created_time" => "2018-03-22T02:36:43.986212308Z",
        "deletion_time" => "",
        "destroyed" => false,
        "version" => 1
      },
    }
  } = Vault.Engine.Generic.write(vault, "path/to/write", %{ foo: "bar" }, [full_response: true])

Options

  • cas: integer set a check-and-set value
  • full_response: boolean - get the whole reponse back on success, not just the data field