Module vault.java.driver

Package io.github.jopenlibs.vault.api

Class Logical

java.lang.Object

io.github.jopenlibs.vault.api.OperationsBase

io.github.jopenlibs.vault.api.Logical

public class Logical
extends OperationsBase

The implementing class for Vault's core/logical operations (e.g. read, write).

This class is not intended to be constructed directly. Rather, it is meant to used by way of Vault in a DSL-style builder pattern. See the Javadoc comments of each public method for usage examples.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Logical.logicalOperations

Nested classes/interfaces inherited from class io.github.jopenlibs.vault.api.OperationsBase

OperationsBase.EndpointOperation<T>

Field Summary

Fields inherited from class io.github.jopenlibs.vault.api.OperationsBase

config

Constructor Summary

Constructors

Constructor	Description
Logical(VaultConfig config)

Method Summary

Modifier and Type	Method	Description
LogicalResponse	delete(java.lang.String path)	Deletes the key/value pair located at the provided path.
LogicalResponse	delete(java.lang.String path, int[] versions)	Soft deletes the specified version of the key/value pair located at the provided path.
LogicalResponse	destroy(java.lang.String path, int[] versions)	Performs a hard delete of the specified version of the key/value pair located at the provided path.
java.lang.Integer	getEngineVersionForSecretPath(java.lang.String path)	Provides the version of the secrets engine of the specified path, e.g.
LogicalResponse	list(java.lang.String path)	Retrieve a list of keys corresponding to key/value pairs at a given Vault path.
LogicalResponse	read(java.lang.String path)	Basic read operation to retrieve a secret.
LogicalResponse	read(java.lang.String path, java.lang.Boolean shouldRetry, java.lang.Integer version)	Basic read operation to retrieve a specified secret version for KV engine version 2.
LogicalResponse	unDelete(java.lang.String path, int[] versions)	Recovers a soft delete of the specified version of the key/value pair located at the provided path.
LogicalResponse	upgrade(java.lang.String kvPath)	Performs an upgrade of the secrets engine version of the specified KV store to version 2.
Logical	withNameSpace(java.lang.String nameSpace)	Adds the requested namespace to the logical operation, which is then passed into the REST headers for said operation.
LogicalResponse	write(java.lang.String path, java.util.Map<java.lang.String,java.lang.Object> nameValuePairs)	Basic operation to store secrets.

Methods inherited from class io.github.jopenlibs.vault.api.OperationsBase

retry

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Logical

public Logical(VaultConfig config)

Method Detail

withNameSpace

public Logical withNameSpace(java.lang.String nameSpace)

Adds the requested namespace to the logical operation, which is then passed into the REST headers for said operation.

Parameters:

nameSpace - The Vault namespace to access (e.g. secret/).

Returns:

The Logical instance, with the namespace set.

read

public LogicalResponse read(java.lang.String path)
                     throws VaultException

Basic read operation to retrieve a secret. A single secret key can map to multiple name-value pairs, which can be retrieved from the response object. E.g.:

 final LogicalResponse response = vault.logical().read("secret/hello");

 final String value = response.getData().get("value");
 final String otherValue = response.getData().get("other_value");
 

Parameters:

path - The Vault key value from which to read (e.g. secret/hello)

Returns:

The response information returned from Vault

Throws:

VaultException - If any errors occurs with the REST request (e.g. non-200 status code, invalid JSON payload, etc), and the maximum number of retries is exceeded.

read

public LogicalResponse read(java.lang.String path,
                            java.lang.Boolean shouldRetry,
                            java.lang.Integer version)
                     throws VaultException

Basic read operation to retrieve a specified secret version for KV engine version 2. A single secret key version can map to multiple name-value pairs, which can be retrieved from the response object. E.g.:

 final LogicalResponse response = vault.logical().read("secret/hello", true, 1);

 final String value = response.getData().get("value");
 final String otherValue = response.getData().get("other_value");
 

Parameters:

path - The Vault key value from which to read (e.g. secret/hello

shouldRetry - Whether to try more than once

version - The Integer version number of the secret to read, e.g. "1"

Returns:

The response information returned from Vault

Throws:

VaultException - If any errors occurs with the REST request (e.g. non-200 status code, invalid JSON payload, etc), and the maximum number of retries is exceeded.

write

public LogicalResponse write(java.lang.String path,
                             java.util.Map<java.lang.String,java.lang.Object> nameValuePairs)
                      throws VaultException

Basic operation to store secrets. Multiple name value pairs can be stored under the same secret key. E.g.:

 final Map<String, String> nameValuePairs = new HashMap<String, Object>();
 nameValuePairs.put("value", "foo");
 nameValuePairs.put("other_value", "bar");

 final LogicalResponse response = vault.logical().write("secret/hello", nameValuePairs);
 

The values in these name-value pairs may be booleans, numerics, strings, or nested JSON objects. However, be aware that this method does not recursively parse any nested structures. If you wish to write arbitrary JSON objects to Vault... then you should parse them to JSON outside of this method, and pass them here as JSON strings.

Parameters:

path - The Vault key value to which to write (e.g. secret/hello)

nameValuePairs - Secret name and value pairs to store under this Vault key (can be null for writing to keys that do not need or expect any fields to be specified)

Returns:

The response information received from Vault

Throws:

VaultException - If any errors occurs with the REST request, and the maximum number of retries is exceeded.

list

public LogicalResponse list(java.lang.String path)
                     throws VaultException

Retrieve a list of keys corresponding to key/value pairs at a given Vault path.

Key values ending with a trailing-slash characters are sub-paths. Running a subsequent list() call, using the original path appended with this key, will retrieve all secret keys stored at that sub-path.

This method returns only the secret keys, not values. To retrieve the actual stored value for a key, use read() with the key appended onto the original base path.

Parameters:

path - The Vault key value at which to look for secrets (e.g. secret)

Returns:

A list of keys corresponding to key/value pairs at a given Vault path, or an empty list if there are none

Throws:

VaultException - If any errors occur, or unexpected response received from Vault

delete

public LogicalResponse delete(java.lang.String path)
                       throws VaultException

Deletes the key/value pair located at the provided path.

If the path represents a sub-path, then all of its contents must be deleted prior to deleting the empty sub-path itself.

Parameters:

path - The Vault key value to delete (e.g. secret/hello).

Returns:

The response information received from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

delete

public LogicalResponse delete(java.lang.String path,
                              int[] versions)
                       throws VaultException

Soft deletes the specified version of the key/value pair located at the provided path.

Only supported for KV Engine version 2. If the data is desired, it can be recovered with a matching unDelete operation.

If the path represents a sub-path, then all of its contents must be deleted prior to deleting the empty sub-path itself.

Parameters:

path - The Vault key value to delete (e.g. secret/hello).

versions - An array of Integers corresponding to the versions you wish to delete, e.g. [1, 2] etc.

Returns:

The response information received from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

unDelete

public LogicalResponse unDelete(java.lang.String path,
                                int[] versions)
                         throws VaultException

Recovers a soft delete of the specified version of the key/value pair located at the provided path.

Only supported for KV Engine version 2.

Parameters:

path - The Vault key value to undelete (e.g. secret/hello).

versions - An array of Integers corresponding to the versions you wish to undelete, e.g. [1, 2] etc.

Returns:

The response information received from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

destroy

public LogicalResponse destroy(java.lang.String path,
                               int[] versions)
                        throws VaultException

Performs a hard delete of the specified version of the key/value pair located at the provided path.

Only supported for KV Engine version 2. There are no recovery options for the specified version of the data deleted in this method.

Parameters:

path - The Vault key value to destroy (e.g. secret/hello).

versions - An array of Integers corresponding to the versions you wish to destroy, e.g. [1, 2] etc.

Returns:

The response information received from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

upgrade

public LogicalResponse upgrade(java.lang.String kvPath)
                        throws VaultException

Performs an upgrade of the secrets engine version of the specified KV store to version 2.

There is no downgrading this operation back to version 1.

Parameters:

kvPath - The Vault kv engine to upgrade (e.g. secret/).

Returns:

The response information received from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

getEngineVersionForSecretPath

public java.lang.Integer getEngineVersionForSecretPath(java.lang.String path)

Provides the version of the secrets engine of the specified path, e.g. 1 or 2.

First checks if the Vault config secrets engine path map contains the path. If not, then defaults to the Global Engine version fallback.

Parameters:

path - The Vault secret path to check (e.g. secret/).

Returns:

The response information received from Vault