SumoLogic/vault-java-driver

Name: vault-java-driver

Owner: Sumo Logic, Inc.

Description: Zero-dependency Java client for HashiCorp's Vault

Forked from: BetterCloud/vault-java-driver

Created: 2017-10-05 14:56:53.0

Updated: 2017-10-05 14:56:55.0

Pushed: 2018-01-03 15:40:41.0

Homepage: https://bettercloud.github.io/vault-java-driver/

Size: 914

Language: Java

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

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 7 and up. So it will play nice with all of your projects, greenfield and legacy alike, without causing conflicts with any other dependency.

Table of Contents
Installing the Driver

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

Gradle:

ndencies {
compile('com.bettercloud:vault-java-driver:3.0.0')

Maven:

endency>
<groupId>com.bettercloud</groupId>
<artifactId>vault-java-driver</artifactId>
<version>3.0.0</version>
pendency>
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:

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

ou may choose not to provide a root token initially, if you plan to use
he Vault driver to retrieve one programmatically from an auth backend.
l 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.

l 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:

l Vault vault = new Vault(config);
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 
ify(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:

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

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



ead operation
l 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:

etry up to 5 times if failures occur, waiting 1000 milliseconds in between each retry attempt.
l 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.

License

The MIT License (MIT)

Copyright (c) 2016-2017 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.

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.