Vault Client for Secrets and Sensitive Data

Description

Vault client for secrets and sensitive data; this package provides wrappers for HashiCorp's vault server. The package wraps most of the high-level API, and includes support for authentication via a number of backends (tokens, username and password, github, and "AppRole"), as well as a number of secrets engines (two key-value stores, vault's cubbyhole and the transit backend for encryption-as-a-service).

Details

To get started, you might want to start with the "vaultr" vignette, available from the package with vignette("vaultr").

The basic design of the package is that it has very few entrypoints - for most uses one will interact almost entirely with the vault_client function. That function returns an R6 object with several methods (functions) but also several objects that themselves contain more methods and objects, creating a nested tree of functionality.

From any object, online help is available via the help method, for example

client <- vaultr::vault_client()
client$secrets$transit$help()

For testing packages that rely on vault, there is support for creating temporary vault servers; see vaultr::vault_test_server and the "packages" vignette.

Author(s)

Maintainer: Rich FitzJohn rich.fitzjohn@gmail.com

Authors:

• Robert Ashton

• Wes Hinsley

Other contributors:

• Imperial College of Science, Technology and Medicine [copyright holder]

See Also

Useful links:

• https://github.com/vimc/vaultr

• https://www.vaccineimpact.org/vaultr/

• Report bugs at https://github.com/vimc/vaultr/issues

Vault Low-Level Client

Description

Vault Low-Level Client

Vault Low-Level Client

Details

Low-level API client. This can be used to directly communicate with the vault server. This object will primarily be useful for debugging, testing or developing new vault methods, but is nonetheless described here.

Super class

vaultr::vault_client_object -> vault_api_client

Public fields

Methods

Public methods

• vault_api_client$new()

• vault_api_client$request()

• vault_api_client$is_authenticated()

• vault_api_client$set_token()

• vault_api_client$verify_token()

• vault_api_client$server_version()

• vault_api_client$GET()

• vault_api_client$LIST()

• vault_api_client$POST()

• vault_api_client$PUT()

• vault_api_client$DELETE()

Method new()

Create a new api client

Usage

vault_api_client$new(addr = NULL, tls_config = NULL, namespace = NULL)

Arguments

Method request()

Make a request to the api. Typically you should use one of the higher-level wrappers, such as ⁠$GET⁠ or ⁠$POST⁠.

Usage

vault_api_client$request(verb, path, ..., token = self$token)

Arguments

Method is_authenticated()

Test if the vault client currently holds a vault token. This method does not verify the token - only test that is present.

Usage

vault_api_client$is_authenticated()

Method set_token()

Set a token within the client

Usage

vault_api_client$set_token(token, verify = FALSE, quiet = FALSE)

Arguments

Method verify_token()

Test that a token is valid with the vault. This will call vault's ⁠/sys/capabilities-self⁠ endpoint with the token provided and check the ⁠/sys⁠ path.

Usage

vault_api_client$verify_token(token, quiet = TRUE)

Arguments

Method server_version()

Retrieve the vault server version. This is by default cached within the client for a session. Will return an R numeric_version object.

Usage

vault_api_client$server_version(refresh = FALSE)

Arguments

Method GET()

Send a GET request to the vault server

Usage

vault_api_client$GET(path, ...)

Arguments

Method LIST()

Send a LIST request to the vault server

Usage

vault_api_client$LIST(path, ...)

Arguments

Method POST()

Send a POST request to the vault server

Usage

vault_api_client$POST(path, ...)

Arguments

Method PUT()

Send a PUT request to the vault server

Usage

vault_api_client$PUT(path, ...)

Arguments

Method DELETE()

Send a DELETE request to the vault server

Usage

vault_api_client$DELETE(path, ...)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  # Ordinarily, we would use the "vault_client" object for
  # high-level access to the vault server
  client <- server$client()
  client$status()

  # The api() method returns the "api client" object:
  api <- client$api()
  api

  # This allows running arbitrary HTTP requests against the server:
  api$GET("/sys/seal-status")

  # this is how vaultr is internally implemented so anything can
  # be done here, for example following vault's API documentation
  # https://www.vaultproject.io/api/secret/kv/kv-v1.html#sample-request-2
  api$POST("/secret/mysecret", body = list(key = "value"))
  api$GET("/secret/mysecret")
  api$DELETE("/secret/mysecret")

  # cleanup
  server$kill()
}

Make a vault client

Description

Make a vault client. This must be done before accessing the vault. The default values for arguments are controlled by environment variables (see Details) and values provided as arguments override these defaults.

Usage

vault_client(
  login = FALSE,
  ...,
  addr = NULL,
  tls_config = NULL,
  namespace = NULL
)

Arguments

Environment variables

The creation of a client is affected by a number of environment variables, following the main vault command line client.

• VAULT_ADDR: The url of the vault server. Must include a protocol (most likely ⁠https://⁠ but in testing ⁠http://⁠ might be used)

• VAULT_CAPATH: The path to CA certificates

• VAULT_TOKEN: A vault token to use in authentication. Only used for token-based authentication

• VAULT_AUTH_GITHUB_TOKEN: As for the command line client, a github token for authentication using the github authentication backend

• VAULTR_AUTH_METHOD: The method to use for authentication

Super class

vaultr::vault_client_object -> vault_client

Public fields

Methods

Public methods

• vault_client_$new()

• vault_client_$api()

• vault_client_$read()

• vault_client_$write()

• vault_client_$delete()

• vault_client_$list()

• vault_client_$login()

• vault_client_$status()

• vault_client_$unwrap()

• vault_client_$wrap_lookup()

Method new()

Create a new vault client. Not typically called directly, but via the vault_client method.

Usage

vault_client_$new(addr, tls_config, namespace)

Arguments

Method api()

Returns an api client object that can be used to directly interact with the vault server.

Usage

vault_client_$api()

Method read()

Read a value from the vault. This can be used to read any value that you have permission to read, and can also be used as an interface to a version 1 key-value store (see vault_client_kv1. Similar to the vault CLI command ⁠vault read⁠.

Usage

vault_client_$read(path, field = NULL, metadata = FALSE)

Arguments

Method write()

Write data into the vault. This can be used to write any value that you have permission to write, and can also be used as an interface to a version 1 key-value store (see vault_client_kv1. Similar to the vault CLI command ⁠vault write⁠.

Usage

vault_client_$write(path, data)

Arguments

Method delete()

Delete a value from the vault

Usage

vault_client_$delete(path)

Arguments

Method list()

List data in the vault at a given path. This can be used to list keys, etc (e.g., at ⁠/secret⁠).

Usage

vault_client_$list(path, full_names = FALSE)

Arguments

Returns

A character vector (of zero length if no keys are found). Paths that are "directories" (i.e., that contain keys and could themselves be listed) will be returned with a trailing forward slash, e.g. ⁠path/⁠

Method login()

Login to the vault. This method is more complicated than most.

Usage

vault_client_$login(
  ...,
  method = "token",
  mount = NULL,
  renew = FALSE,
  quiet = FALSE,
  token_only = FALSE,
  use_cache = TRUE
)

Arguments

Method status()

Return the status of the vault server, including whether it is sealed or not, and the vault server version.

Usage

vault_client_$status()

Method unwrap()

Returns the original response inside the given wrapping token. The vault endpoints used by this method perform validation checks on the token, returns the original value on the wire rather than a JSON string representation of it, and ensures that the response is properly audit-logged.

Usage

vault_client_$unwrap(token)

Arguments

Method wrap_lookup()

Look up properties of a wrapping token.

Usage

vault_client_$wrap_lookup(token)

Arguments

Author(s)

Rich FitzJohn

Examples

# We work with a test vault server here (see ?vault_test_server) for
# details.  To use it, you must have a vault binary installed on your
# system.  These examples will not affect any real running vault
# instance that you can connect to.
server <- vaultr::vault_test_server(if_disabled = message)

if (!is.null(server)) {
  # Create a vault_client object by providing the address of the vault
  # server.
  client <- vaultr::vault_client(addr = server$addr)

  # The client has many methods, grouped into a structure:
  client

  # For example, token related commands:
  client$token

  # The client is not authenticated by default:
  try(client$list("/secret"))

  # A few methods are unauthenticated and can still be run
  client$status()

  # Login to the vault, using the token that we know from the server -
  # ordinarily you would use a login approach suitable for your needs
  # (see the vault documentation).
  token <- server$token
  client$login(method = "token", token = token)

  # The vault contains no secrets at present
  client$list("/secret")

  # Secrets can contain any (reasonable) number of key-value pairs,
  # passed in as a list
  client$write("/secret/users/alice", list(password = "s3cret!"))

  # The whole list can be read out
  client$read("/secret/users/alice")
  # ...or just a field
  client$read("/secret/users/alice", "password")

  # Reading non-existant values returns NULL, not an error
  client$read("/secret/users/bob")

  client$delete("/secret/users/alice")
}

Vault Audit Devices

Description

Vault Audit Devices

Vault Audit Devices

Details

Interact with vault's audit devices. For more details, see https://developer.hashicorp.com/vault/docs/audit

Super class

vaultr::vault_client_object -> vault_client_audit

Methods

Public methods

• vault_client_audit$new()

• vault_client_audit$list()

• vault_client_audit$enable()

• vault_client_audit$disable()

• vault_client_audit$hash()

Method new()

Create an audit object

Usage

vault_client_audit$new(api_client)

Arguments

Method list()

List active audit devices. Returns a data.frame of names, paths and descriptions of active audit devices.

Usage

vault_client_audit$list()

Method enable()

This endpoint enables a new audit device at the supplied path.

Usage

vault_client_audit$enable(
  type,
  description = NULL,
  options = NULL,
  path = NULL
)

Arguments

Method disable()

Disable an audit device

Usage

vault_client_audit$disable(path)

Arguments

Method hash()

The hash method is used to calculate the hash of the data used by an audit device's hash function and salt. This can be used to search audit logs for a hashed value when the original value is known.

Usage

vault_client_audit$hash(input, device)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()
  # By default no audit engines are enabled with the testing server
  client$audit$list()

  # Create a file-based audit device on a temporary file:
  path <- tempfile()
  client$audit$enable("file", options = list(file_path = path))
  client$audit$list()

  # Generate some activity on the server:
  client$write("/secret/mysecret", list(key = "value"))

  # The audit logs contain details about the activity - see the
  # vault documentation for details in interpreting this
  readLines(path)

  # cleanup
  server$kill()
  unlink(path)
}

Vault Authentication Configuration

Description

Vault Authentication Configuration

Vault Authentication Configuration

Details

Interact with vault's authentication backends.

Super class

vaultr::vault_client_object -> vault_client_auth

Public fields

Methods

Public methods

• vault_client_auth$new()

• vault_client_auth$backends()

• vault_client_auth$list()

• vault_client_auth$enable()

• vault_client_auth$disable()

Method new()

Create a vault_client_auth object. Not typically called by users.

Usage

vault_client_auth$new(api_client)

Arguments

Method backends()

Return a character vector of supported authentication backends. If a backend x is present, then you can access it with ⁠$auth$x⁠. Note that vault calls these authentication methods but we use backends here to differentiate with R6 methods. Note that these are backends supported by vaultr and not necessarily supported by the server - the server may not have enabled some of these backends, and may support other authentication backends not directly supported by vaultr. See the ⁠$list()⁠ method to query what the server supports.

Usage

vault_client_auth$backends()

Method list()

List authentication backends supported by the vault server, including information about where these backends are mounted.

Usage

vault_client_auth$list(detailed = FALSE)

Arguments

Method enable()

Enable an authentication backend in the vault server.

Usage

vault_client_auth$enable(type, description = NULL, local = FALSE, path = NULL)

Arguments

Method disable()

Disable an active authentication backend.

Usage

vault_client_auth$disable(path)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # List configured authentication backends
  client$auth$list()

  # cleanup
  server$kill()
}

Vault AppRole Authentication Configuration

Description

Vault AppRole Authentication Configuration

Vault AppRole Authentication Configuration

Details

Interact with vault's AppRole authentication backend. For more details about this, see the vault documentation at https://developer.hashicorp.com/vault/docs/auth/approle

Super class

vaultr::vault_client_object -> vault_client_auth_approle

Methods

Public methods

• vault_client_auth_approle$new()

• vault_client_auth_approle$custom_mount()

• vault_client_auth_approle$role_list()

• vault_client_auth_approle$role_write()

• vault_client_auth_approle$role_read()

• vault_client_auth_approle$role_delete()

• vault_client_auth_approle$role_id_read()

• vault_client_auth_approle$role_id_write()

• vault_client_auth_approle$secret_id_generate()

• vault_client_auth_approle$secret_id_list()

• vault_client_auth_approle$secret_id_read()

• vault_client_auth_approle$secret_id_delete()

• vault_client_auth_approle$login()

Method new()

Create a vault_client_approle object. Not typically called by users.

Usage

vault_client_auth_approle$new(api_client, mount)

Arguments

Method custom_mount()

Set up a vault_client_auth_approle object at a custom mount. For example, suppose you mounted the approle authentication backend at ⁠/approle-dev⁠ you might use ar <- vault$auth$approle2$custom_mount("/approle-dev") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_auth_approle$custom_mount(mount)

Arguments

Method role_list()

This endpoint returns a list the existing AppRoles in the method.

Usage

vault_client_auth_approle$role_list()

Method role_write()

Creates a new AppRole or updates an existing AppRole. This endpoint supports both create and update capabilities. There can be one or more constraints enabled on the role. It is required to have at least one of them enabled while creating or updating a role.

Usage

vault_client_auth_approle$role_write(
  role_name,
  bind_secret_id = NULL,
  secret_id_bound_cidrs = NULL,
  token_bound_cidrs = NULL,
  policies = NULL,
  secret_id_num_uses = NULL,
  secret_id_ttl = NULL,
  token_num_uses = NULL,
  token_ttl = NULL,
  token_max_ttl = NULL,
  period = NULL,
  enable_local_secret_ids = NULL,
  token_type = NULL
)

Arguments

Method role_read()

Reads the properties of an existing AppRole.

Usage

vault_client_auth_approle$role_read(role_name)

Arguments

Method role_delete()

Deletes an existing AppRole from the method.

Usage

vault_client_auth_approle$role_delete(role_name)

Arguments

Method role_id_read()

Reads the RoleID of an existing AppRole.

Usage

vault_client_auth_approle$role_id_read(role_name)

Arguments

Method role_id_write()

Updates the RoleID of an existing AppRole to a custom value.

Usage

vault_client_auth_approle$role_id_write(role_name, role_id)

Arguments

Method secret_id_generate()

Generates and issues a new SecretID on an existing AppRole. Similar to tokens, the response will also contain a secret_id_accessor value which can be used to read the properties of the SecretID without divulging the SecretID itself, and also to delete the SecretID from the AppRole.

Usage

vault_client_auth_approle$secret_id_generate(
  role_name,
  metadata = NULL,
  cidr_list = NULL,
  token_bound_cidrs = NULL
)

Arguments

Method secret_id_list()

Lists the accessors of all the SecretIDs issued against the AppRole. This includes the accessors for "custom" SecretIDs as well.

Usage

vault_client_auth_approle$secret_id_list(role_name)

Arguments

Method secret_id_read()

Reads out the properties of a SecretID.

Usage

vault_client_auth_approle$secret_id_read(
  role_name,
  secret_id,
  accessor = FALSE
)

Arguments

Method secret_id_delete()

Delete an AppRole secret ID

Usage

vault_client_auth_approle$secret_id_delete(
  role_name,
  secret_id,
  accessor = FALSE
)

Arguments

Method login()

Log into the vault using AppRole authentication. Normally you would not call this directly but instead use ⁠$login⁠ with method = "approle" and proving the role_id and secret_id arguments. This function returns a vault token but does not set it as the client token.

Usage

vault_client_auth_approle$login(role_id, secret_id)

Arguments

Examples

vaultr::vault_client(addr = "https://localhost:8200")$auth$approle

Vault GitHub Authentication Configuration

Description

Vault GitHub Authentication Configuration

Vault GitHub Authentication Configuration

Details

Interact with vault's GitHub authentication backend. For more details, please see the vault documentation at https://developer.hashicorp.com/vault/docs/auth/github

Super class

vaultr::vault_client_object -> vault_client_auth_github

Methods

Public methods

• vault_client_auth_github$new()

• vault_client_auth_github$custom_mount()

• vault_client_auth_github$configure()

• vault_client_auth_github$configuration()

• vault_client_auth_github$write()

• vault_client_auth_github$read()

• vault_client_auth_github$login()

Method new()

Create a vault_client_github object. Not typically called by users.

Usage

vault_client_auth_github$new(api_client, mount)

Arguments

Method custom_mount()

Set up a vault_client_auth_github object at a custom mount. For example, suppose you mounted the github authentication backend at ⁠/github-myorg⁠ you might use gh <- vault$auth$github2$custom_mount("/github-myorg") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_auth_github$custom_mount(mount)

Arguments

Method configure()

Configures the connection parameters for GitHub-based authentication.

Usage

vault_client_auth_github$configure(
  organization,
  base_url = NULL,
  ttl = NULL,
  max_ttl = NULL
)

Arguments

Method configuration()

Reads the connection parameters for GitHub-based authentication.

Usage

vault_client_auth_github$configuration()

Method write()

Write a mapping between a GitHub team or user and a set of vault policies.

Usage

vault_client_auth_github$write(team_name, policies, user = FALSE)

Arguments

Method read()

Write a mapping between a GitHub team or user and a set of vault policies.

Usage

vault_client_auth_github$read(team_name, user = FALSE)

Arguments

Method login()

Log into the vault using GitHub authentication. Normally you would not call this directly but instead use ⁠$login⁠ with method = "github" and proving the token argument. This function returns a vault token but does not set it as the client token.

Usage

vault_client_auth_github$login(token = NULL)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
token <- Sys.getenv("VAULT_TEST_AUTH_GITHUB_TOKEN")
if (!is.null(server) && nzchar(token)) {
  client <- server$client()

  client$auth$enable("github")
  # To enable login for members of the organisation "example":
  client$auth$github$configure(organization = "example")
  # To map members of the "robots" team *within* that organisation
  # to the "defaut" policy:
  client$auth$github$write("development", "default")

  # Once configured like this, if we have a PAT for a member of
  # the "development" team saved as an environment variable
  # "VAULT_AUTH_GITHUB_TOKEN" then doing
  #
  #   vaultr::vault_client(addr = ..., login = "github")
  #
  # will contact GitHub to verify the user token and vault will
  # then issue a client token

  # cleanup
  server$kill()
}

Vault LDAP Authentication Configuration

Description

Vault LDAP Authentication Configuration

Vault LDAP Authentication Configuration

Details

Interact with vault's LDAP authentication backend. This backend can be used to configure users based on their presence or group membership in an LDAP server. For more information, please see the vault documentation https://developer.hashicorp.com/vault/docs/auth/ldap

Super class

vaultr::vault_client_object -> vault_client_auth_ldap

Methods

Public methods

• vault_client_auth_ldap$new()

• vault_client_auth_ldap$custom_mount()

• vault_client_auth_ldap$configure()

• vault_client_auth_ldap$configuration()

• vault_client_auth_ldap$write()

• vault_client_auth_ldap$read()

• vault_client_auth_ldap$list()

• vault_client_auth_ldap$delete()

• vault_client_auth_ldap$login()

Method new()

Create a vault_client_auth_ldap object. Not typically called by users.

Usage

vault_client_auth_ldap$new(api_client, mount)

Arguments

Method custom_mount()

Set up a vault_client_auth_ldap object at a custom mount. For example, suppose you mounted the ldap authentication backend at ⁠/ldap-dev⁠ you might use ldap <- vault$auth$ldap2$custom_mount("/ldap-dev") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_auth_ldap$custom_mount(mount)

Arguments

Method configure()

Configures the connection parameters for LDAP-based authentication. Note that there are many options here and not all may be well supported. You are probably best to configure your vault-LDAP interaction elsewhere, and this method should be regarded as experimental and for testing purposes only.

See the official docs (https://developer.hashicorp.com/vault/api-docs/auth/ldap, "Configure LDAP") for the list of accepted parameters here via the dots argument; these are passed through directly (with the exception of url which is the only required parameter and for which concatenation of multiple values is done for you.

Usage

vault_client_auth_ldap$configure(url, ...)

Arguments

Method configuration()

Reads the connection parameters for LDAP-based authentication.

Usage

vault_client_auth_ldap$configuration()

Method write()

Create or update a policy

Usage

vault_client_auth_ldap$write(name, policies, user = FALSE)

Arguments

Method read()

Write a mapping between a LDAP group or user and a set of vault policies.

Usage

vault_client_auth_ldap$read(name, user = FALSE)

Arguments

Method list()

List groups or users known to vault via LDAP

Usage

vault_client_auth_ldap$list(user = FALSE)

Arguments

Method delete()

Delete a group or user (just the mapping to vault, no data on the LDAP server is modified).

Usage

vault_client_auth_ldap$delete(name, user = FALSE)

Arguments

Method login()

Log into the vault using LDAP authentication. Normally you would not call this directly but instead use ⁠$login⁠ with method = "ldap" and proving the username and optionally the password argument. argument. This function returns a vault token but does not set it as the client token.

Usage

vault_client_auth_ldap$login(username, password)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  root <- server$client()

  # The ldap authentication backend is not enabled by default,
  # so we need to enable it first
  root$auth$enable("ldap")

  # Considerable configuration is required to make this work. Here
  # we use the public server available at
  # https://www.forumsys.com/2022/05/10/online-ldap-test-server/
  root$auth$ldap$configure(
    url = "ldap://ldap.forumsys.com",
    binddn = "cn=read-only-admin,dc=example,dc=com",
    bindpass = "password",
    userdn = "dc=example,dc=com",
    userattr = "uid",
    groupdn = "dc=example,dc=com",
    groupattr = "ou",
    groupfilter = "(uniqueMember={{.UserDN}})")

  # You can associate groups of users with policies:
  root$auth$ldap$write("scientists", "default")

  # Create a new client and login with this user:
  newton <- vaultr::vault_client(
    addr = server$addr,
    login = "ldap",
    username = "newton",
    password = "password")

  # (it is not recommended to login with the password like this as
  # it will end up in the command history, but in interactive use
  # you will be prompted securely for password)

  # Isaac Newton has now logged in and has only "default" policies
  newton$auth$token$lookup_self()$policies

  # (wheras our original root user has the "root" policy)
  root$auth$token$lookup_self()$policies
}

Vault Username/Password Authentication Configuration

Description

Vault Username/Password Authentication Configuration

Vault Username/Password Authentication Configuration

Details

Interact with vault's username/password authentication backend. This backend can be used to configure basic username+password authentication, suitable for human users. For more information, please see the vault documentation https://developer.hashicorp.com/vault/docs/auth/userpass

Super class

vaultr::vault_client_object -> vault_client_auth_userpass

Methods

Public methods

• vault_client_auth_userpass$new()

• vault_client_auth_userpass$custom_mount()

• vault_client_auth_userpass$write()

• vault_client_auth_userpass$read()

• vault_client_auth_userpass$delete()

• vault_client_auth_userpass$update_password()

• vault_client_auth_userpass$update_policies()

• vault_client_auth_userpass$list()

• vault_client_auth_userpass$login()

Method new()

Create a vault_client_userpass object. Not typically called by users.

Usage

vault_client_auth_userpass$new(api_client, mount)

Arguments

Method custom_mount()

Set up a vault_client_auth_userpass object at a custom mount. For example, suppose you mounted the userpass authentication backend at ⁠/userpass2⁠ you might use up <- vault$auth$userpass2$custom_mount("/userpass2") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_auth_userpass$custom_mount(mount)

Arguments

Method write()

Create or update a user.

Usage

vault_client_auth_userpass$write(
  username,
  password = NULL,
  policies = NULL,
  ttl = NULL,
  max_ttl = NULL,
  bound_cidrs = NULL
)

Arguments

Method read()

Reads the properties of an existing username.

Usage

vault_client_auth_userpass$read(username)

Arguments

Method delete()

Delete a user

Usage

vault_client_auth_userpass$delete(username)

Arguments

Method update_password()

Update password for a user

Usage

vault_client_auth_userpass$update_password(username, password)

Arguments

Method update_policies()

Update vault policies for a user

Usage

vault_client_auth_userpass$update_policies(username, policies)

Arguments

Method list()

List users known to vault

Usage

vault_client_auth_userpass$list()

Method login()

Log into the vault using username/password authentication. Normally you would not call this directly but instead use ⁠$login⁠ with method = "userpass" and proving the username argument and optionally the password argument. This function returns a vault token but does not set it as the client token.

Usage

vault_client_auth_userpass$login(username, password = NULL)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  root <- server$client()

  # The userpass authentication backend is not enabled by default,
  # so we need to enable it first
  root$auth$enable("userpass")

  # Then we can add users:
  root$auth$userpass$write("alice", "p4ssw0rd")

  # Create a new client and login with this user:
  alice <- vaultr::vault_client(
    addr = server$addr,
    login = "userpass",
    username = "alice",
    password = "p4ssw0rd")

  # (it is not recommended to login with the password like this as
  # it will end up in the command history, but in interactive use
  # you will be prompted securely for password)

  # Alice has now logged in and has only "default" policies
  alice$auth$token$lookup_self()$policies

  # (wheras our original root user has the "root" policy)
  root$auth$token$lookup_self()$policies
}

Cubbyhole secret store

Description

Cubbyhole secret store

Cubbyhole secret store

Details

Interact with vault's cubbyhole key-value store. This is useful for storing simple key-value data without versioning or metadata (c.f. vault_client_kv2) that is scoped to your current token only and not accessible to anyone else. For more details please see the vault documentation https://developer.hashicorp.com/vault/docs/secrets/cubbyhole

Super class

vaultr::vault_client_object -> vault_client_cubbyhole

Methods

Public methods

• vault_client_cubbyhole$new()

• vault_client_cubbyhole$read()

• vault_client_cubbyhole$write()

• vault_client_cubbyhole$list()

• vault_client_cubbyhole$delete()

Method new()

Create a vault_client_cubbyhole object. Not typically called by users.

Usage

vault_client_cubbyhole$new(api_client)

Arguments

Method read()

Read a value from your cubbyhole

Usage

vault_client_cubbyhole$read(path, field = NULL, metadata = FALSE)

Arguments

Method write()

Write data into your cubbyhole.

Usage

vault_client_cubbyhole$write(path, data)

Arguments

Method list()

List data in the vault at a give path. This can be used to list keys, etc (e.g., at ⁠/cubbyhole⁠).

Usage

vault_client_cubbyhole$list(path, full_names = FALSE)

Arguments

Method delete()

Delete a value from the vault

Usage

vault_client_cubbyhole$delete(path)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # Shorter path for easier reading:
  cubbyhole <- client$secrets$cubbyhole
  cubbyhole

  # Write a value
  cubbyhole$write("cubbyhole/secret", list(key = "value"))
  # List it
  cubbyhole$list("cubbyhole")
  # Read it
  cubbyhole$read("cubbyhole/secret")
  # Delete it
  cubbyhole$delete("cubbyhole/secret")

  # cleanup
  server$kill()
}

Key-Value Store (Version 1)

Description

Key-Value Store (Version 1)

Key-Value Store (Version 1)

Details

Interact with vault's version 1 key-value store. This is useful for storing simple key-value data without versioning or metadata (see vault_client_kv2 for a richer key-value store).

Up to vault version 0.12.0 this was mounted by default at ⁠/secret⁠. It can be accessed from vault with either the ⁠$read⁠, ⁠$write⁠, ⁠$list⁠ and ⁠$delete⁠ methods on the main vault_client object or by the ⁠$kv1⁠ member of the secrets member of the main vault client (vault_client_secrets)

Super class

vaultr::vault_client_object -> vault_client_kv1

Methods

Public methods

• vault_client_kv1$new()

• vault_client_kv1$custom_mount()

• vault_client_kv1$read()

• vault_client_kv1$write()

• vault_client_kv1$list()

• vault_client_kv1$delete()

Method new()

Create a vault_client_kv1 object. Not typically called by users.

Usage

vault_client_kv1$new(api_client, mount)

Arguments

Method custom_mount()

Set up a vault_client_kv1 object at a custom mount. For example, suppose you mounted another copy of the kv1 secret backend at ⁠/secret2⁠ you might use kv <- vault$secrets$kv1$custom_mount("/secret2") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_kv1$custom_mount(mount)

Arguments

Method read()

Read a value from the vault. This can be used to read any value that you have permission to read in this store.

Usage

vault_client_kv1$read(path, field = NULL, metadata = FALSE)

Arguments

Method write()

Write data into the vault. This can be used to write any value that you have permission to write in this store.

Usage

vault_client_kv1$write(path, data)

Arguments

Method list()

List data in the vault at a give path. This can be used to list keys, etc (e.g., at ⁠/secret⁠).

Usage

vault_client_kv1$list(path, full_names = FALSE)

Arguments

Method delete()

Delete a value from the vault

Usage

vault_client_kv1$delete(path)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # Write secrets
  client$secrets$kv1$write("/secret/path/mysecret", list(key = "value"))

  # List secrets - note the trailing "/" indicates a folder
  client$secrets$kv1$list("/secret")
  client$secrets$kv1$list("/secret/path")

  # Read secrets
  client$secrets$kv1$read("/secret/path/mysecret")
  client$secrets$kv1$read("/secret/path/mysecret", field = "key")

  # Delete secrets
  client$secrets$kv1$delete("/secret/path/mysecret")
  client$secrets$kv1$read("/secret/path/mysecret")

  # cleanup
  server$kill()
}

Key-Value Store (Version 2)

Description

Key-Value Store (Version 2)

Key-Value Store (Version 2)

Details

Interact with vault's version 2 key-value store. This is useful for storing simple key-value data that can be versioned and for storing metadata alongside the secrets (see vault_client_kv1 for a simpler key-value store, and see https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2 for detailed information about this secret store.

A kv2 store can be mounted anywhere, so all methods accept a mount argument. This is different to the CLI which lets you try and read values from any vault path, but similar to other secret and auth backends which accept arguments like -mount-point. So if the kv2 store is mounted at ⁠/project-secrets⁠ for example, with a vault client vault one could write

vault$secrets$kv2$get("/project-secrets/mysecret",
                      mount = "project-secrets")

or

kv2 <- vault$secrets$kv2$custom_mount("project-secrets")
kv2$get("mysecret")

If the leading part of of a path to secret within a kv2 store does not match the mount point, vaultr will throw an error. This approach results in more predictable error messages, though it is a little more typing than for the CLI vault client.

Super class

vaultr::vault_client_object -> vault_client_kv2

Methods

Public methods

• vault_client_kv2$new()

• vault_client_kv2$config()

• vault_client_kv2$custom_mount()

• vault_client_kv2$delete()

• vault_client_kv2$destroy()

• vault_client_kv2$get()

• vault_client_kv2$list()

• vault_client_kv2$metadata_get()

• vault_client_kv2$metadata_put()

• vault_client_kv2$metadata_delete()

• vault_client_kv2$put()

• vault_client_kv2$undelete()

Method new()

Create a vault_client_kv2 object. Not typically called by users.

Usage

vault_client_kv2$new(api_client, mount)

Arguments

Method config()

Fetch the configuration for this kv2 store. Returns a named list of values, the contents of which will depend on the vault version.

Usage

vault_client_kv2$config(mount = NULL)

Arguments

Method custom_mount()

Set up a vault_client_kv2 object at a custom mount. For example, suppose you mounted another copy of the kv2 secret backend at ⁠/secret2⁠ you might use kv <- vault$secrets$kv2$custom_mount("/secret2") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_kv2$custom_mount(mount)

Arguments

Method delete()

Delete a secret from the vault. This marks the version as deleted and will stop it from being returned from reads, but the underlying data will not be removed. A delete can be undone using the undelete method.

Usage

vault_client_kv2$delete(path, version = NULL, mount = NULL)

Arguments

Method destroy()

Delete a secret entirely. Unlike delete this operation is irreversible and is more like the delete operation on vault_client_kv1 stores.

Usage

vault_client_kv2$destroy(path, version, mount = NULL)

Arguments

Method get()

Read a secret from the vault

Usage

vault_client_kv2$get(
  path,
  version = NULL,
  field = NULL,
  metadata = FALSE,
  mount = NULL
)

Arguments

Method list()

List data in the vault at a give path. This can be used to list keys, etc (e.g., at ⁠/secret⁠).

Usage

vault_client_kv2$list(path, full_names = FALSE, mount = NULL)

Arguments

Method metadata_get()

Read secret metadata and versions at the specified path

Usage

vault_client_kv2$metadata_get(path, mount = NULL)

Arguments

Method metadata_put()

Update metadata for a secret. This is allowed even if a secret does not yet exist, though this requires the create vault permission at this path.

Usage

vault_client_kv2$metadata_put(
  path,
  cas_required = NULL,
  max_versions = NULL,
  mount = NULL
)

Arguments

Method metadata_delete()

This method permanently deletes the key metadata and all version data for the specified key. All version history will be removed.

Usage

vault_client_kv2$metadata_delete(path, mount = NULL)

Arguments

Method put()

Create or update a secret in this store.

Usage

vault_client_kv2$put(path, data, cas = NULL, mount = NULL)

Arguments

Method undelete()

Undeletes the data for the provided version and path in the key-value store. This restores the data, allowing it to be returned on get requests. This works with data deleted with ⁠$delete⁠ but not with ⁠$destroy⁠.

Usage

vault_client_kv2$undelete(path, version, mount = NULL)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()
  # With the test server as created by vaultr, the kv2 storage
  # engine is not enabled.  To use the kv2 store we must first
  # enable it; the command below will add it at the path /kv on
  # our vault server
  client$secrets$enable("kv", version = 2)

  # For ease of reading, create a 'kv' object for interacting with
  # the store (see below for the calls without this object)
  kv <- client$secrets$kv2$custom_mount("kv")
  kv$config()

  # The version-2 kv store can be treated largely the same as the
  # version-1 store, though with slightly different command names
  # (put instead of write, get instead of read)
  kv$put("/kv/path/secret", list(key = "value"))
  kv$get("/kv/path/secret")

  # But it also allows different versions to be stored at the same path:
  kv$put("/kv/path/secret", list(key = "s3cret!"))
  kv$get("/kv/path/secret")

  # Old versions can be retrieved still:
  kv$get("/kv/path/secret", version = 1)

  # And metadata about versions can be retrieved
  kv$metadata_get("/kv/path/secret")

  # cleanup
  server$kill()
}

Base object type

Description

Base object type

Base object type

Details

Base object used by vaultr for all objects

Methods

Public methods

• vault_client_object$new()

• vault_client_object$format()

• vault_client_object$help()

Method new()

Construct an object

Usage

vault_client_object$new(description)

Arguments

Method format()

Format method, overriding the R6 default

Usage

vault_client_object$format(brief = FALSE)

Arguments

Method help()

Display help for this object

Usage

vault_client_object$help()

Examples

server <- vaultr::vault_test_server(if_disabled = message)

if (!is.null(server)) {
  client <- vaultr::vault_client(addr = server$addr)
  client$operator$format()
  client$operator$format(TRUE)
}

Vault Administration

Description

Vault Administration

Vault Administration

Details

Administration commands for vault operators. Very few of these commands should be used without consulting the vault documentation as they affect the administration of a vault server, but they are included here for completeness.

Super class

vaultr::vault_client_object -> vault_client_operator

Methods

Public methods

• vault_client_operator$new()

• vault_client_operator$key_status()

• vault_client_operator$is_initialized()

• vault_client_operator$init()

• vault_client_operator$leader_status()

• vault_client_operator$rekey_status()

• vault_client_operator$rekey_start()

• vault_client_operator$rekey_cancel()

• vault_client_operator$rekey_submit()

• vault_client_operator$rotate()

• vault_client_operator$seal()

• vault_client_operator$seal_status()

• vault_client_operator$unseal()

Method new()

Create a vault_client_operator object. Not typically called by users.

Usage

vault_client_operator$new(api_client)

Arguments

Method key_status()

Return information about the current encryption key of Vault.

Usage

vault_client_operator$key_status()

Method is_initialized()

Returns the initialization status of Vault

Usage

vault_client_operator$is_initialized()

Method init()

This endpoint initializes a new Vault. The Vault must not have been previously initialized.

Usage

vault_client_operator$init(secret_shares, secret_threshold)

Arguments

Method leader_status()

Check the high availability status and current leader of Vault

Usage

vault_client_operator$leader_status()

Method rekey_status()

Reads the configuration and progress of the current rekey attempt

Usage

vault_client_operator$rekey_status()

Method rekey_start()

This method begins a new rekey attempt. Only a single rekey attempt can take place at a time, and changing the parameters of a rekey requires cancelling and starting a new rekey, which will also provide a new nonce.

Usage

vault_client_operator$rekey_start(secret_shares, secret_threshold)

Arguments

Method rekey_cancel()

This method cancels any in-progress rekey. This clears the rekey settings as well as any progress made. This must be called to change the parameters of the rekey. Note verification is still a part of a rekey. If rekeying is cancelled during the verification flow, the current unseal keys remain valid.

Usage

vault_client_operator$rekey_cancel()

Method rekey_submit()

This method is used to enter a single master key share to progress the rekey of the Vault. If the threshold number of master key shares is reached, Vault will complete the rekey. Otherwise, this method must be called multiple times until that threshold is met. The rekey nonce operation must be provided with each call.

Usage

vault_client_operator$rekey_submit(key, nonce)

Arguments

Method rotate()

This method triggers a rotation of the backend encryption key. This is the key that is used to encrypt data written to the storage backend, and is not provided to operators. This operation is done online. Future values are encrypted with the new key, while old values are decrypted with previous encryption keys.

Usage

vault_client_operator$rotate()

Method seal()

Seal the vault, preventing any access to it. After the vault is sealed, it must be unsealed for further use.

Usage

vault_client_operator$seal()

Method seal_status()

Check the seal status of a Vault. This method can be used even when the client is not authenticated with the vault (which will the case for a sealed vault).

Usage

vault_client_operator$seal_status()

Method unseal()

Submit a portion of a key to unseal the vault. This method is typically called by multiple different operators to assemble the master key.

Usage

vault_client_operator$unseal(key, reset = FALSE)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # Our test server is by default unsealed:
  client$status()$sealed

  # We can seal the vault to prevent all access:
  client$operator$seal()
  client$status()$sealed

  # And then unseal it again
  client$operator$unseal(server$keys)
  client$status()$sealed
}

Vault Policy Configuration

Description

Vault Policy Configuration

Vault Policy Configuration

Details

Interact with vault's policies. To get started, you may want to read up on policies as described in the vault manual, here: https://developer.hashicorp.com/vault/docs/concepts/policies

Super class

vaultr::vault_client_object -> vault_client_policy

Methods

Public methods

• vault_client_policy$new()

• vault_client_policy$delete()

• vault_client_policy$list()

• vault_client_policy$read()

• vault_client_policy$write()

Method new()

Create a vault_client_policy object. Not typically called by users.

Usage

vault_client_policy$new(api_client)

Arguments

Method delete()

This endpoint deletes the policy with the given name. This will immediately affect all users associated with this policy.

Usage

vault_client_policy$delete(name)

Arguments

Method list()

Lists all configured policies.

Usage

vault_client_policy$list()

Method read()

Retrieve the policy body for the named policy

Usage

vault_client_policy$read(name)

Arguments

Method write()

Create or update a policy. Once a policy is updated, it takes effect immediately to all associated users.

Usage

vault_client_policy$write(name, rules)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # The test server starts with only the policies "root" (do
  # everything) and "default" (do nothing).
  client$policy$list()

  # Here let's make a policy that allows reading secrets from the
  # path /secret/develop/* but nothing else
  rules <- 'path "secret/develop/*" {policy = "read"}'
  client$policy$write("read-secret-develop", rules)

  # Our new rule is listed and can be read
  client$policy$list()
  client$policy$read("read-secret-develop")

  # For testing, let's create a secret under this path, and under
  # a different path:
  client$write("/secret/develop/password", list(value = "password"))
  client$write("/secret/production/password", list(value = "k2e89be@rdC#"))

  # Create a token that can use this policy:
  token <- client$auth$token$create(policies = "read-secret-develop")

  # Login to the vault using this token:
  alice <- vaultr::vault_client(addr = server$addr,
                                login = "token", token = token)

  # We can read the paths that we have been granted access to:
  alice$read("/secret/develop/password")

  # We can't read secrets that are outside our path:
  try(alice$read("/secret/production/password"))

  # And we can't write:
  try(alice$write("/secret/develop/password", list(value = "secret")))

  # cleanup
  server$kill()
}

Vault Secret Configuration

Description

Vault Secret Configuration

Vault Secret Configuration

Details

Interact with vault's secret backends.

Super class

vaultr::vault_client_object -> vault_client_secrets

Public fields

Methods

Public methods

• vault_client_secrets$new()

• vault_client_secrets$disable()

• vault_client_secrets$enable()

• vault_client_secrets$list()

• vault_client_secrets$move()

Method new()

Create a vault_client_secrets object. Not typically called by users.

Usage

vault_client_secrets$new(api_client)

Arguments

Method disable()

Disable a previously-enabled secret engine

Usage

vault_client_secrets$disable(path)

Arguments

Method enable()

Enable a secret backend in the vault server

Usage

vault_client_secrets$enable(
  type,
  path = type,
  description = NULL,
  version = NULL
)

Arguments

Method list()

List enabled secret engines

Usage

vault_client_secrets$list(detailed = FALSE)

Arguments

Method move()

Move the path that a secret engine is mounted at

Usage

vault_client_secrets$move(from, to)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # To remove the default version 1 kv store and replace with a
  # version 2 store:
  client$secrets$disable("/secret")
  client$secrets$enable("kv", "/secret", version = 2)

  # cleanup
  server$kill()
}

Vault Tokens

Description

Vault Tokens

Vault Tokens

Details

Interact with vault's token methods. This includes support for querying, creating and deleting tokens. Tokens are fundamental to the way that vault works, so there are a lot of methods here. The vault documentation has a page devoted to token concepts: https://developer.hashicorp.com/vault/docs/concepts/tokens - there is also a page with commands: https://developer.hashicorp.com/vault/docs/commands/token - these have names very similar to the names used here.

Token Accessors

Many of the methods use "token accessors" - whenever a token is created, an "accessor" is created at the same time. This is another token that can be used to perform limited actions with the token such as

• Look up a token's properties (not including the actual token ID)

• Look up a token's capabilities on a path

• Revoke the token

However, accessors cannot be used to login, nor to retrieve the actual token itself.

Super class

vaultr::vault_client_object -> vault_client_token

Methods

Public methods

• vault_client_token$new()

• vault_client_token$list()

• vault_client_token$capabilities()

• vault_client_token$capabilities_self()

• vault_client_token$capabilities_accessor()

• vault_client_token$client()

• vault_client_token$create()

• vault_client_token$lookup()

• vault_client_token$lookup_self()

• vault_client_token$lookup_accessor()

• vault_client_token$renew()

• vault_client_token$renew_self()

• vault_client_token$revoke()

• vault_client_token$revoke_self()

• vault_client_token$revoke_accessor()

• vault_client_token$revoke_and_orphan()

• vault_client_token$role_read()

• vault_client_token$role_list()

• vault_client_token$role_write()

• vault_client_token$role_delete()

• vault_client_token$tidy()

• vault_client_token$login()

Method new()

Create a vault_client_token object. Not typically called by users.

Usage

vault_client_token$new(api_client)

Arguments

Method list()

List token accessors, returning a character vector

Usage

vault_client_token$list()

Method capabilities()

Fetch the capabilities of a token on the given paths. The capabilities returned will be derived from the policies that are on the token, and from the policies to which the token is entitled to through the entity and entity's group memberships.

Usage

vault_client_token$capabilities(path, token)

Arguments

Method capabilities_self()

As for the capabilities method, but for the client token used to make the request.

Usage

vault_client_token$capabilities_self(path)

Arguments

Method capabilities_accessor()

As for the capabilities method, but using a token accessor rather than a token itself.

Usage

vault_client_token$capabilities_accessor(path, accessor)

Arguments

Method client()

Return the current client token

Usage

vault_client_token$client()

Method create()

Create a new token

Usage

vault_client_token$create(
  role_name = NULL,
  id = NULL,
  policies = NULL,
  meta = NULL,
  orphan = FALSE,
  no_default_policy = FALSE,
  max_ttl = NULL,
  display_name = NULL,
  num_uses = 0L,
  period = NULL,
  ttl = NULL,
  wrap_ttl = NULL
)

Arguments

Method lookup()

Returns information about the client token

Usage

vault_client_token$lookup(token = NULL)

Arguments

Method lookup_self()

Returns information about the current client token (as if calling ⁠$lookup⁠ with the token the client is using.

Usage

vault_client_token$lookup_self()

Method lookup_accessor()

Returns information about the client token from the accessor.

Usage

vault_client_token$lookup_accessor(accessor)

Arguments

Method renew()

Renews a lease associated with a token. This is used to prevent the expiration of a token, and the automatic revocation of it. Token renewal is possible only if there is a lease associated with it.

Usage

vault_client_token$renew(token, increment = NULL)

Arguments

Method renew_self()

Renews a lease associated with the calling token. This is used to prevent the expiration of a token, and the automatic revocation of it. Token renewal is possible only if there is a lease associated with it. This is equivalent to calling ⁠$renew()⁠ with the client token.

Usage

vault_client_token$renew_self(increment = NULL)

Arguments

Method revoke()

Revokes a token and all child tokens. When the token is revoked, all dynamic secrets generated with it are also revoked.

Usage

vault_client_token$revoke(token)

Arguments

Method revoke_self()

Revokes the token used to call it and all child tokens. When the token is revoked, all dynamic secrets generated with it are also revoked. This is equivalent to calling ⁠$revoke()⁠ with the client token.

Usage

vault_client_token$revoke_self()

Method revoke_accessor()

Revoke the token associated with the accessor and all the child tokens. This is meant for purposes where there is no access to token ID but there is need to revoke a token and its children.

Usage

vault_client_token$revoke_accessor(accessor)

Arguments

Method revoke_and_orphan()

Revokes a token but not its child tokens. When the token is revoked, all secrets generated with it are also revoked. All child tokens are orphaned, but can be revoked subsequently using /auth/token/revoke/. This is a root-protected method.

Usage

vault_client_token$revoke_and_orphan(token)

Arguments

Method role_read()

Fetches the named role configuration.

Usage

vault_client_token$role_read(role_name)

Arguments

Method role_list()

List available token roles.

Usage

vault_client_token$role_list()

Method role_write()

Creates (or replaces) the named role. Roles enforce specific behaviour when creating tokens that allow token functionality that is otherwise not available or would require sudo/root privileges to access. Role parameters, when set, override any provided options to the create endpoints. The role name is also included in the token path, allowing all tokens created against a role to be revoked using the ⁠/sys/leases/revoke-prefix⁠ endpoint.

Usage

vault_client_token$role_write(
  role_name,
  allowed_policies = NULL,
  disallowed_policies = NULL,
  orphan = NULL,
  period = NULL,
  renewable = NULL,
  explicit_max_ttl = NULL,
  path_suffix = NULL,
  bound_cidrs = NULL,
  token_type = NULL
)

Arguments

Method role_delete()

Delete a named token role

Usage

vault_client_token$role_delete(role_name)

Arguments

Method tidy()

Performs some maintenance tasks to clean up invalid entries that may remain in the token store. Generally, running this is not needed unless upgrade notes or support personnel suggest it. This may perform a lot of I/O to the storage method so should be used sparingly.

Usage

vault_client_token$tidy()

Method login()

Unlike other auth backend login methods, this does not actually log in to the vault. Instead it verifies that a token can be used to communicate with the vault.

Usage

vault_client_token$login(token = NULL, quiet = FALSE)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # There are lots of token methods here:
  client$token

  # To demonstrate, it will be useful to create a restricted
  # policy that can only read from the /secret path
  rules <- 'path "secret/*" {policy = "read"}'
  client$policy$write("read-secret", rules)
  client$write("/secret/path", list(key = "value"))

  # Create a token that has this policy
  token <- client$auth$token$create(policies = "read-secret")
  alice <- vaultr::vault_client(addr = server$addr)
  alice$login(method = "token", token = token)
  alice$read("/secret/path")

  client$token$lookup(token)

  # We can query the capabilities of this token
  client$token$capabilities("secret/path", token)

  # Tokens are not safe to pass around freely because they *are*
  # the ability to login, but the `token$create` command also
  # provides an accessor:
  accessor <- attr(token, "info")$accessor

  # It is not possible to derive the token from the accessor, but
  # we can use the accessor to ask vault what it could do if it
  # did have the token (and do things like revoke the token)
  client$token$capabilities_accessor("secret/path", accessor)

  client$token$revoke_accessor(accessor)
  try(client$token$capabilities_accessor("secret/path", accessor))

  # cleanup
  server$kill()
}

Vault Tools

Description

Vault Tools

Vault Tools

Details

Interact with vault's cryptographic tools. This provides support for high-quality random numbers and cryptographic hashes. This functionality is also available through the transit secret engine.

Super class

vaultr::vault_client_object -> vault_client_tools

Methods

Public methods

• vault_client_tools$new()

• vault_client_tools$random()

• vault_client_tools$hash()

Method new()

Create a vault_client_tools object. Not typically called by users.

Usage

vault_client_tools$new(api_client)

Arguments

Method random()

Generates high-quality random bytes of the specified length. This is totally independent of R's random number stream and provides random numbers suitable for cryptographic purposes.

Usage

vault_client_tools$random(bytes = 32, format = "hex")

Arguments

Method hash()

Generates a cryptographic hash of given data using the specified algorithm.

Usage

vault_client_tools$hash(data, algorithm = NULL, format = "hex")

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # Random bytes in hex
  client$tools$random()
  # base64
  client$tools$random(format = "base64")
  # raw
  client$tools$random(10, format = "raw")

  # Hash data:
  data <- charToRaw("hello vault")
  # will produce 55e702...92efd40c2a4
  client$tools$hash(data)

  # sha2-512 hash:
  client$tools$hash(data, "sha2-512")

  # cleanup
  server$kill()
}

Transit Engine

Description

Transit Engine

Transit Engine

Details

Interact with vault's transit engine. This is useful for encrypting arbitrary data without storing it in the vault - like "cryptography as a service" or "encryption as a service". The transit secrets engine can also sign and verify data; generate hashes and HMACs of data; and act as a source of random bytes. See https://developer.hashicorp.com/vault/docs/secrets/transit for an introduction to the capabilities of the transit engine.

Super class

vaultr::vault_client_object -> vault_client_transit

Methods

Public methods

• vault_client_transit$new()

• vault_client_transit$custom_mount()

• vault_client_transit$key_create()

• vault_client_transit$key_read()

• vault_client_transit$key_list()

• vault_client_transit$key_delete()

• vault_client_transit$key_update()

• vault_client_transit$key_rotate()

• vault_client_transit$key_export()

• vault_client_transit$data_encrypt()

• vault_client_transit$data_decrypt()

• vault_client_transit$data_rewrap()

• vault_client_transit$datakey_create()

• vault_client_transit$random()

• vault_client_transit$hash()

• vault_client_transit$hmac()

• vault_client_transit$sign()

• vault_client_transit$verify_signature()

• vault_client_transit$verify_hmac()

• vault_client_transit$key_backup()

• vault_client_transit$key_restore()

• vault_client_transit$key_trim()

Method new()

Create a vault_client_transit object. Not typically called by users.

Usage

vault_client_transit$new(api_client, mount)

Arguments

Method custom_mount()

Set up a vault_client_transit object at a custom mount. For example, suppose you mounted the transit secret backend at ⁠/transit2⁠ you might use tr <- vault$secrets$transit$custom_mount("/transit2") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_transit$custom_mount(mount)

Arguments

Method key_create()

Create a new named encryption key of the specified type. The values set here cannot be changed after key creation.

Usage

vault_client_transit$key_create(
  name,
  key_type = NULL,
  convergent_encryption = NULL,
  derived = NULL,
  exportable = NULL,
  allow_plaintext_backup = NULL
)

Arguments

Method key_read()

Read information about a previously generated key. The returned object shows the creation time of each key version; the values are not the keys themselves. Depending on the type of key, different information may be returned, e.g. an asymmetric key will return its public key in a standard format for the type.

Usage

vault_client_transit$key_read(name)

Arguments

Method key_list()

List names of all keys

Usage

vault_client_transit$key_list()

Method key_delete()

Delete a key by name. It will no longer be possible to decrypt any data encrypted with the named key. Because this is a potentially catastrophic operation, the deletion_allowed tunable must be set using ⁠$key_update()⁠.

Usage

vault_client_transit$key_delete(name)

Arguments

Method key_update()

This method allows tuning configuration values for a given key. (These values are returned during a read operation on the named key.)

Usage

vault_client_transit$key_update(
  name,
  min_decryption_version = NULL,
  min_encryption_version = NULL,
  deletion_allowed = NULL,
  exportable = NULL,
  allow_plaintext_backup = NULL
)

Arguments

Method key_rotate()

Rotates the version of the named key. After rotation, new plaintext requests will be encrypted with the new version of the key. To upgrade ciphertext to be encrypted with the latest version of the key, use the rewrap endpoint. This is only supported with keys that support encryption and decryption operations.

Usage

vault_client_transit$key_rotate(name)

Arguments

Method key_export()

Export the named key. If version is specified, the specific version will be returned. If latest is provided as the version, the current key will be provided. Depending on the type of key, different information may be returned. The key must be exportable to support this operation and the version must still be valid.

For more details see https://github.com/hashicorp/vault/issues/2667 where HashiCorp says "Part of the "contract" of transit is that the key is never exposed outside of Vault. We added the ability to export keys because some enterprises have key escrow requirements, but it leaves a permanent mark in the key metadata. I suppose we could at some point allow importing a key and also leave such a mark."

Usage

vault_client_transit$key_export(name, key_type, version = NULL)

Arguments

Method data_encrypt()

This endpoint encrypts the provided plaintext using the named key.

Usage

vault_client_transit$data_encrypt(
  key_name,
  data,
  key_version = NULL,
  context = NULL
)

Arguments

Method data_decrypt()

Decrypts the provided ciphertext using the named key.

Usage

vault_client_transit$data_decrypt(key_name, data, context = NULL)

Arguments

Method data_rewrap()

Rewraps the provided ciphertext using the latest version of the named key. Because this never returns plaintext, it is possible to delegate this functionality to untrusted users or scripts.

Usage

vault_client_transit$data_rewrap(
  key_name,
  data,
  key_version = NULL,
  context = NULL
)

Arguments

Method datakey_create()

This endpoint generates a new high-entropy key and the value encrypted with the named key. Optionally return the plaintext of the key as well.

Usage

vault_client_transit$datakey_create(
  name,
  plaintext = FALSE,
  bits = NULL,
  context = NULL
)

Arguments

Method random()

Generates high-quality random bytes of the specified length. This is totally independent of R's random number stream and provides random numbers suitable for cryptographic purposes.

Usage

vault_client_transit$random(bytes = 32, format = "hex")

Arguments

Method hash()

Generates a cryptographic hash of given data using the specified algorithm.

Usage

vault_client_transit$hash(data, algorithm = NULL, format = "hex")

Arguments

Method hmac()

This endpoint returns the digest of given data using the specified hash algorithm and the named key. The key can be of any type supported by the transit engine; the raw key will be marshalled into bytes to be used for the HMAC function. If the key is of a type that supports rotation, the latest (current) version will be used.

Usage

vault_client_transit$hmac(name, data, key_version = NULL, algorithm = NULL)

Arguments

Method sign()

Returns the cryptographic signature of the given data using the named key and the specified hash algorithm. The key must be of a type that supports signing.

Usage

vault_client_transit$sign(
  name,
  data,
  key_version = NULL,
  hash_algorithm = NULL,
  prehashed = FALSE,
  signature_algorithm = NULL,
  context = NULL
)

Arguments

Method verify_signature()

Determine whether the provided signature is valid for the given data.

Usage

vault_client_transit$verify_signature(
  name,
  data,
  signature,
  hash_algorithm = NULL,
  signature_algorithm = NULL,
  context = NULL,
  prehashed = FALSE
)

Arguments

Method verify_hmac()

Determine whether the provided signature is valid for the given data.

Usage

vault_client_transit$verify_hmac(
  name,
  data,
  signature,
  hash_algorithm = NULL,
  signature_algorithm = NULL,
  context = NULL,
  prehashed = FALSE
)

Arguments

Method key_backup()

Returns a plaintext backup of a named key. The backup contains all the configuration data and keys of all the versions along with the HMAC key. The response from this endpoint can be used with ⁠$key_restore⁠ to restore the key.

Usage

vault_client_transit$key_backup(name)

Arguments

Method key_restore()

Restores the backup as a named key. This will restore the key configurations and all the versions of the named key along with HMAC keys. The input to this method should be the output of ⁠$key_restore⁠ method.

Usage

vault_client_transit$key_restore(name, backup, force = FALSE)

Arguments

Method key_trim()

This endpoint trims older key versions setting a minimum version for the keyring. Once trimmed, previous versions of the key cannot be recovered.

Usage

vault_client_transit$key_trim(name, min_version)

Arguments

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  client$secrets$enable("transit")
  transit <- client$secrets$transit

  # Before encrypting anything, create a key.  Note that it will
  # not be returned to you, and is accessed purely by name
  transit$key_create("test")

  # Some text to encrypt
  plaintext <- "hello world"

  # Encrypted:
  cyphertext <- transit$data_encrypt("test", charToRaw(plaintext))

  # Decrypt the data
  res <- transit$data_decrypt("test", cyphertext)
  rawToChar(res)

  # This approach works with R objects too, if used with serialise.
  # First, serialise an R object to a raw vector:
  data <- serialize(mtcars, NULL)

  # Then encrypt this data:
  enc <- transit$data_encrypt("test", data)

  # The resulting string can be safely passed around (e.g., over
  # email) or written to disk, and can later be decrypted by
  # anyone who has access to the "test" key in the vault:
  data2 <- transit$data_decrypt("test", enc)

  # Once decrypted, the data can be "unserialised" back into an R
  # object:
  unserialize(data2)

  # cleanup
  server$kill()
}

Resolve secrets from R objects

Description

Use vault to resolve secrets. This is a convenience function that wraps a pattern that we have used in a few applications of vault. The idea is to allow replacement of data in configuration with special strings that indicate that the string refers to a vault secret. This function resolves those secrets.

Usage

vault_resolve_secrets(x, ..., login = TRUE, vault_args = NULL)

Arguments

Details

For each element of the data, if a string matches the form:

  VAULT:<path to secret>:<field>

then it will be treated as a vault secret and resolved. The ⁠<path to get>⁠ will be something like ⁠/secret/path/password⁠ and the ⁠<field>⁠ the name of a field in the key/value data stored at that path. For example, suppose you have the data list(username = "alice", password = "s3cret!") stored at ⁠/secret/database/user⁠, then the string

  VAULT:/secret/database/user:password

would refer to the value ⁠s3cret!⁠

Value

List of properties with any vault secrets resolved.

Examples

server <- vaultr::vault_test_server(if_disabled = message)

if (!is.null(server)) {
  client <- server$client()
  # The example from above:
  client$write("/secret/database/user",
               list(username = "alice", password = "s3cret!"))

  # A list of data that contains a mix of secrets to be resolved
  # and other data:
  x <- list(user = "alice",
            password = "VAULT:/secret/database/user:password",
            port = 5678)

  # Explicitly pass in the login details and resolve the secrets:
  vaultr::vault_resolve_secrets(x, login = "token", token = server$token,
                                addr = server$addr)

  # Alternatively, if appropriate environment variables are set
  # then this can be done more easily:
  if (requireNamespace("withr", quietly = TRUE)) {
    env <- c(VAULTR_AUTH_METHOD = "token",
             VAULT_TOKEN = server$token,
             VAULT_ADDR = server$addr)
    withr::with_envvar(env, vault_resolve_secrets(x))
  }
}

Control a test vault server

Description

Control a server for use with testing. This is designed to be used only by other packages that wish to run tests against a vault server. You will need to set VAULTR_TEST_SERVER_BIN_PATH to point at the directory containing the vault binary, to the binary itself, or to the value auto to try and find it on your PATH.

Usage

vault_test_server(
  https = FALSE,
  init = TRUE,
  if_disabled = testthat::skip,
  quiet = FALSE
)

Arguments

Details

Once created with vault_test_server, a server will stay alive for as long as the R process is alive or until the vault_server_instance object goes out of scope and is garbage collected. Calling ⁠$kill()⁠ will explicitly stop the server, but this is not strictly needed. See below for methods to control the server instance.

Warning

Starting a server in test mode must not be used for production under any circumstances. As the name suggests, vault_test_server is a server suitable for tests only and lacks any of the features required to make vault secure. For more information, please see the the official Vault documentation on development servers: https://developer.hashicorp.com/vault/docs/concepts/dev-server

Super class

vaultr::vault_client_object -> vault_server_instance

Public fields

Methods

Public methods

• vault_server_instance$new()

• vault_server_instance$version()

• vault_server_instance$client()

• vault_server_instance$env()

• vault_server_instance$export()

• vault_server_instance$clear_cached_token()

• vault_server_instance$kill()

Method new()

Create a vault_server_instance object. Not typically called by users.

Usage

vault_server_instance$new(bin, port, https, init, quiet = FALSE)

Arguments

Method version()

Return the server version, as a numeric_version object.

Usage

vault_server_instance$version()

Method client()

Create a new client that can use this server. The client will be a vault_client object.

Usage

vault_server_instance$client(login = TRUE, quiet = TRUE)

Arguments

Method env()

Return a named character vector of environment variables that can be used to communicate with this vault server (VAULT_ADDR, VAULT_TOKEN, etc).

Usage

vault_server_instance$env()

Method export()

Export the variables returned by the ⁠$env()⁠ method to the environment. This makes them available to child processes.

Usage

vault_server_instance$export()

Method clear_cached_token()

Clear any session-cached token for this server. This is intended for testing new authentication backends.

Usage

vault_server_instance$clear_cached_token()

Method kill()

Kill the server.

Usage

vault_server_instance$kill()

Examples

# Try and start a server; if one is not enabled (see details
# above) then this will return NULL
server <- vault_test_server(if_disabled = message)

if (!is.null(server)) {
  # We now have a server running on an arbitrary high port - note
  # that we are running over http and in dev mode: this is not at
  # all suitable for production use, just for tests
  server$addr

  # Create clients using the client method - by default these are
  # automatically authenticated against the server
  client <- server$client()
  client$write("/secret/password", list(value = "s3cret!"))
  client$read("/secret/password")

  # The server stops automatically when the server object is
  # garbage collected, or it can be turned off with the
  # 'kill' method:
  server$kill()
  tryCatch(client$status(), error = function(e) message(e$message))
}