com.bettercloud.vault.api.pki

Class Pki

java.lang.Object

com.bettercloud.vault.api.pki.Pki

public class Pki
extends java.lang.Object

The implementing class for operations on Vault's PKI backend.

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.

Constructor Summary

Constructors

Constructor and Description
Pki(VaultConfig config) Constructor for use when the PKI backend is mounted on the default path (i.e.
Pki(VaultConfig config, java.lang.String mountPath) Constructor for use when the PKI backend is mounted on some non-default custom path (e.g.

Method Summary

Modifier and Type	Method and Description
PkiResponse	createOrUpdateRole(java.lang.String roleName) Operation to create an role using the PKI backend.
PkiResponse	createOrUpdateRole(java.lang.String roleName, RoleOptions options) Operation to create an role using the PKI backend.
PkiResponse	deleteRole(java.lang.String roleName) Operation to delete an role using the PKI backend.
PkiResponse	getRole(java.lang.String roleName) Operation to retrieve an role using the PKI backend.
PkiResponse	issue(java.lang.String roleName, java.lang.String commonName, java.util.List<java.lang.String> altNames, java.util.List<java.lang.String> ipSans, java.lang.String ttl, CredentialFormat format) Operation to generate a new set of credentials (private key and certificate) based on a given role using the PKI backend.

Methods inherited from class java.lang.Object

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

Constructor Detail

Pki

public Pki(VaultConfig config)

Constructor for use when the PKI backend is mounted on the default path (i.e. /v1/pki).

Parameters:

config - A container for the configuration settings needed to initialize a Vault driver instance

Pki

public Pki(VaultConfig config,
           java.lang.String mountPath)

Constructor for use when the PKI backend is mounted on some non-default custom path (e.g. /v1/root-ca).

Parameters:

config - A container for the configuration settings needed to initialize a Vault driver instance

mountPath - The path on which your Vault PKI backend is mounted, without the /v1/ prefix (e.g. "root-ca")

Method Detail

createOrUpdateRole

public PkiResponse createOrUpdateRole(java.lang.String roleName)
                               throws VaultException

Operation to create an role using the PKI backend. Relies on an authentication token being present in the VaultConfig instance.

This version of the method uses default values for all optional settings. Example usage:

 final VaultConfig config = new VaultConfig(address, token);
 final Vault vault = new Vault(config);
 final PkiResponse response = vault.pki().createOrUpdateRole("testRole");

 assertEquals(204, response.getRestResponse().getStatus());
 

Parameters:

roleName - A name for the role to be created or updated

Returns:

A container for the information returned by Vault

Throws:

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

createOrUpdateRole

public PkiResponse createOrUpdateRole(java.lang.String roleName,
                                      RoleOptions options)
                               throws VaultException

Operation to create an role using the PKI backend. Relies on an authentication token being present in the VaultConfig instance.

This version of the method accepts a RoleOptions parameter, containing optional settings for the role creation operation. Example usage:

 final VaultConfig config = new VaultConfig(address, token);
 final Vault vault = new Vault(config);

 final RoleOptions options = new RoleOptions()
                              .allowedDomains(new ArrayList<String>(){{ add("myvault.com"); }})
                              .allowSubdomains(true)
                              .maxTtl("9h");
 final PkiResponse response = vault.pki().createOrUpdateRole("testRole", options);

 assertEquals(204, response.getRestResponse().getStatus());
 

Parameters:

roleName - A name for the role to be created or updated

options - Optional settings for the role to be created or updated (e.g. allowed domains, ttl, etc)

Returns:

A container for the information returned by Vault

Throws:

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

getRole

public PkiResponse getRole(java.lang.String roleName)
                    throws VaultException

Operation to retrieve an role using the PKI backend. Relies on an authentication token being present in the VaultConfig instance.

The role information will be populated in the roleOptions field of the PkiResponse return value. Example usage:

 final VaultConfig config = new VaultConfig(address, token);
 final Vault vault = new Vault(config);
 final PkiResponse response = vault.pki().getRole("testRole");

 final RoleOptions details = response.getRoleOptions();
 

Parameters:

roleName - The name of the role to retrieve

Returns:

A container for the information returned by Vault

Throws:

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

deleteRole

public PkiResponse deleteRole(java.lang.String roleName)
                       throws VaultException

Operation to delete an role using the PKI backend. Relies on an authentication token being present in the VaultConfig instance.

A successful operation will return a 204 HTTP status. A VaultException will be thrown if the role does not exist, or if any other problem occurs. Example usage:

 final VaultConfig config = new VaultConfig(address, token);
 final Vault vault = new Vault(config);

 final PkiResponse response = vault.pki().deleteRole("testRole");
 assertEquals(204, response.getRestResponse().getStatus();
 

Parameters:

roleName - The name of the role to delete

Returns:

A container for the information returned by Vault

Throws:

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

issue

public PkiResponse issue(java.lang.String roleName,
                         java.lang.String commonName,
                         java.util.List<java.lang.String> altNames,
                         java.util.List<java.lang.String> ipSans,
                         java.lang.String ttl,
                         CredentialFormat format)
                  throws VaultException

Operation to generate a new set of credentials (private key and certificate) based on a given role using the PKI backend. The issuing CA certificate is returned as well, so that only the root CA need be in a client's trust store.

A successful operation will return a 204 HTTP status. A VaultException will be thrown if the role does not exist, or if any other problem occurs. Credential information will be populated in the credential field of the PkiResponse return value. Example usage:

 final VaultConfig config = new VaultConfig(address, token);
 final Vault vault = new Vault(config);

 final PkiResponse response = vault.pki().deleteRole("testRole");
 assertEquals(204, response.getRestResponse().getStatus();
 

Parameters:

roleName - The role on which the credentials will be based.

commonName - The requested CN for the certificate. If the CN is allowed by role policy, it will be issued.

altNames - (optional) Requested Subject Alternative Names, in a comma-delimited list. These can be host names or email addresses; they will be parsed into their respective fields. If any requested names do not match role policy, the entire request will be denied.

ipSans - (optional) Requested IP Subject Alternative Names, in a comma-delimited list. Only valid if the role allows IP SANs (which is the default).

ttl - (optional) Requested Time To Live. Cannot be greater than the role's max_ttl value. If not provided, the role's ttl value will be used. Note that the role values default to system values if not explicitly set.

format - (optional) Format for returned data. Can be pem, der, or pem_bundle; defaults to pem. If der, the output is base64 encoded. If pem_bundle, the certificate field will contain the private key, certificate, and issuing CA, concatenated.

Returns:

A container for the information returned by Vault

Throws:

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