search

BetterCloud / vault-java-driver

Zero-dependency Java client for HashiCorp's Vault
https://bettercloud.github.io/vault-java-driver/
334 stars 224 forks source link

readme

Vault Java Driver

A zero-dependency Java client for the Vault secrets management solution from HashiCorp.

This driver strives to implement Vault's full HTTP API, along with supporting functionality such as automatic retry handling. It does so without relying on any other external libraries beyond the Java standard library, and is compatible with Java 8 and up. So it will play nice with all of your projects, greenfield and legacy alike, without causing conflicts with any other dependency.

NOTE: Although the binary artifact produced by the project is backwards-compatible with Java 8, you do need JDK 9 or higher to modify or build the source code of this library itself.

This Change

Table of Contents

Installing the Driver

The driver is available from Maven Central, for all modern Java build systems.

Gradle:

dependencies {
    implementation 'com.bettercloud:vault-java-driver:5.1.0'
}

Maven:

<dependency>
    <groupId>com.bettercloud</groupId>
    <artifactId>vault-java-driver</artifactId>
    <version>5.1.0</version>
</dependency>

Initializing a Driver Instance

The com.bettercloud.vault.VaultConfig class is used to initialize a driver instance with desired settings. In the most basic use cases, where you are only supplying a Vault server address and perhaps a root token, there are convenience constructor methods available:

final VaultConfig config = new VaultConfig()
                                  .address("http://127.0.0.1:8200")
                                  .token("3c9fd6be-7bc2-9d1f-6fb3-cd746c0fc4e8")
                                  .build();

// You may choose not to provide a root token initially, if you plan to use
// the Vault driver to retrieve one programmatically from an auth backend.
final VaultConfig config = new VaultConfig().address("http://127.0.0.1:8200").build();

To explicitly set additional config parameters (*), you can use a builder pattern style to construct the VaultConfig instance. Either way, the initialization process will try to populate any unset values by looking to environment variables.

final VaultConfig config =
    new VaultConfig()
        .address("http://127.0.0.1:8200")               // Defaults to "VAULT_ADDR" environment variable
        .token("3c9fd6be-7bc2-9d1f-6fb3-cd746c0fc4e8")  // Defaults to "VAULT_TOKEN" environment variable
        .openTimeout(5)                                 // Defaults to "VAULT_OPEN_TIMEOUT" environment variable
        .readTimeout(30)                                // Defaults to "VAULT_READ_TIMEOUT" environment variable
        .sslConfig(new SslConfig().build())             // See "SSL Config" section below
        .build();

Once you have initialized a VaultConfig object, you can use it to construct an instance of the Vault primary driver class:

final Vault vault = new Vault(config);

Key Value Secret Engine Config

Shortly before its 1.0 release, Vault added a Version 2 of its Key/Value Secrets Engine. This supports some addition features beyond the Version 1 that was the default in earlier Vault builds (e.g. secret rotation, soft deletes, etc).

Unfortunately, K/V V2 introduces some breaking changes, in terms of both request/response payloads as well as how URL's are constructed for Vault's REST API. Therefore, version 4.0.0 of this Vault Driver likewise had to introduce some breaking changes, to allow support for both K/V versions.

Version 2 of the K/V engine dynamically injects a qualifier element into your secret paths, which varies depending on the type of for read and write operations, in between the root version operation. For example, for read and write operations, the secret path:

v1/mysecret

... has a "data" qualifier injected:

v1/data/mysecret

The default behavior of this driver is to insert the appropriate qualifier one level deep (i.e. in between the root version number and the rest of the path). However, if your secret path is prefixed, such that the qualifier should be injected further down:

v1/my/long/prefix/data/anything/else

... then you should accordingly set the VaultConfig.prefixPathDepth property when constructing your Vault instance.

SSL Config

If your Vault server uses a SSL certificate, then you must supply that certificate to establish connections. Also, if you are using certificate-based client authentication, then you must supply a client certificate and private key that have been previously registered with your Vault server.

SSL configuration has been broken off from the VaultConfig class, and placed in its own SslConfig class. This class likewise using a builder pattern.

General Options

.verify(false)    // Defaults to "VAULT_SSL_VERIFY" environment variable (or else "true")

To disable SSL certificate verification altogether, set sslVerify(false). YOU SHOULD NOT DO THIS IS A REAL PRODUCTION SETTING! However, it can be useful in a development or testing server context. If this value is explicitly set to false, then all other SSL config is basically unused.

Java Keystore (JKS) based config

You can provide the driver with a JKS truststore, containing Vault's server-side certificate for basic SSL, using one of the following three options:

.trustStore(object) - Supply an in-memory java.security.KeyStore file, containing Vault server cert(s) that can be trusted.

.trustStoreFile(path) - Same as the above, but the path references a JKS file on the filesystem.

.trustStoreResource(path) - Same as the above, but the path references a classpath resource rather than a filesystem path (e.g. if you've bundled the JKS file into your application's JAR, WAR, or EAR file).

If you are only using basic SSL, then no keystore need be provided. However, if you would like to use Vault's TLS Certificate auth backend for client side auth, then you need to provide a JKS keystore containing your client-side certificate and private key:

.keyStore(object, password) - Supply an in-memory java.security.KeyStore file containing a client certificate and private key, and the password needed to access it (can be null). can be trusted.

.keyStoreFile(path, password) - Same as the above, but the path references a JKS file on the filesystem.

.keyStoreResource(path, password) - Same as the above, but the path references a classpath resource rather than a filesystem path (e.g. if you've bundled the JKS file into your application's JAR, WAR, or EAR file).

NOTE: JKS-based config trumps PEM-based config (see below). If for some reason you build an SslConfig object with both JKS and PEM data present, then only the JKS data will be used. You cannot "mix-and-match", providing a JKS-based truststore and PEM-based client auth data.

OpenSSL (PEM) based config

To supply Vault's server-side certificate for basic SSL, you can use one of the following three options:

.pemFile(path) - Supply the path to an X.509 certificate in unencrypted PEM format, using UTF-8 encoding (defaults to "VAULT_SSL_CERT" environment variable).

.pemResource(path) - Same as above, but the path references a classpath resource rather than a filesystem path (e.g. if you've bundled the PEM file into your applications's JAR, WAR, or EAR file).

.pemUTF8(contents) - The string contents extracted from the PEM file. For Java to parse the certificate properly, there must be a line-break in between the certificate header and body (see the SslConfig Javadocs for more detail).

If SSL verification is enabled, no JKS-based config is provided, AND none of these three methods are called, then SslConfig will by default check for a VAULT_SSL_CERT environment variable. If that's setw then it will be treated as a filesystem path.

To use Vault's TLS Certificate auth backend for SSL client auth, you must provide your client certificate and private key, using some pair from the following options:

.clientPemUTF8(path) - Supply the path to an X.509 certificate in unencrypted PEM format, using UTF-8 encoding.

.clientPemResource(path) - Same as above, but the path references a classpath resource rather than a filesystem path (e.g. if you've bundled the PEM file into your applications's JAR, WAR, or EAR file).

.clientPemUTF8(contents) - The string contents extracted from the PEM file. For Java to parse the certificate properly, there must be a line-break in between the certificate header and body (see the SslConfig Javadocs for more detail).

.clientKeyPemUTF8(path) - Supply the path to an RSA private key in unencrypted PEM format, using UTF-8 encoding.

.clientKeyPemResource(path) - Same as above, but the path references a classpath resource rather than a filesystem path (e.g. if you've bundled the PEM file into your applications's JAR, WAR, or EAR file).

.clientKeyPemUTF8(contents) - The string contents extracted from the PEM file. For Java to parse the certificate properly, there must be a line-break in between the certificate header and body (see the SslConfig Javadocs for more detail).

Using the Driver

Like the VaultConfig class, Vault too supports a builder pattern DSL style:

final Map<String, String> secrets = new HashMap<String, String>();
secrets.put("value", "world");
secrets.put("other_value", "You can store multiple name/value pairs under a single key");

// Write operation
final LogicalResponse writeResponse = vault.logical()
                                        .write("secret/hello", secrets);

...

// Read operation
final String value = vault.logical()
                       .read("secret/hello")
                       .getData().get("value");

Vault has a number of methods for accessing the classes that implement the various endpoints of Vault's HTTP API:

The driver DSL also allows you to specify retry logic, by chaining the withRetries() ahead of accessing the endpoint implementation:

// Retry up to 5 times if failures occur, waiting 1000 milliseconds in between each retry attempt.
final LogicalResponse response = vault.withRetries(5, 1000)
                                   .logical()
                                   .read("secret/hello");

API Reference (Javadocs)

Full Javadoc documentation.

Version History

Note that changes to the major version (i.e. the first number) represent possible breaking changes, and may require modifications in your code to migrate. Changes to the minor version (i.e. the second number) should represent non-breaking changes. The third number represents any very minor bugfix patches.

Development

Pull requests are welcomed for bugfixes or enhancements that do not alter the external facing class and method signatures. For any breaking changes that would alter the contract provided by this driver, please open up an issue to discuss it first.

All code changes should include unit test and/or integration test coverage as appropriate. Unit tests are any that can be run in isolation, with no external dependencies. Integration tests are those which require a Vault server instance (at least a Dev Server) up and running.

Unit tests are located under the src/test directory, and can be run with the Grade unitTest task.

Integration tests are located under the src/test-integration directory, and can be run with the Gradle integrationTest task. See the additional README.md file in this directory for more detailed information.

Although this library now includes a module-info class for use by Java 9+, the library currently targets Java 8 compatibility. Please do not attempt to introduce any features or syntax not compatible with Java 8 (the Gradle build script should prevent you from doing so without modification).

License

The MIT License (MIT)

Copyright (c) 2016-2019 BetterCloud

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Other Notes

The Vault server system itself is a product of HashiCorp, a completely separate organization.

This client driver adapts JSON parsing code from Ralf Sternberg's excellent minimal-json library, likewise available under the MIT License. Package names have all been changed, to prevent any conflicts should you happen to be using a different version of that library elsewhere in your project dependencies.