Module vault.java.driver
Package io.github.jopenlibs.vault.api.pki

Class Pki

  • public class Pki
extends OperationsBase

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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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.
      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, java.lang.String csr)
      Operation to generate a new set of credentials or sign the embedded CSR, in the PKI backend.
      PkiResponse revoke​(java.lang.String serialNumber)
      Operation to revike a certificate in the vault using the PKI backend.
      Pki withNameSpace​(java.lang.String nameSpace)  

      • 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

      • withNameSpace

        public Pki withNameSpace​(java.lang.String nameSpace)

      • 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(...).build();
 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(...).build();
 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(...).build();
 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

      • revoke

        public PkiResponse revoke​(java.lang.String serialNumber)
                   throws VaultException

        Operation to revike a certificate in the vault 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(...).build();
 final Vault vault = new Vault(config);

 final PkiResponse response = vault.pki().revoke("serialnumber");
 assertEquals(204, response.getRestResponse().getStatus();
        Parameters:
        serialNumber - 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

      • 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(...).build();
 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(...).build();
 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

      • 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,
                         java.lang.String csr)
                  throws VaultException

        Operation to generate a new set of credentials or sign the embedded CSR, in the PKI backend. If CSR is passed the sign function of the vault will be called if not, issue will be used. 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(...).build();
 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.
        csr - (optional) PEM Encoded CSR
        Returns:
        A container for the information returned by Vault
        Throws:
        VaultException - If any error occurs or unexpected response is received from Vault