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

Class SslConfig

  • All Implemented Interfaces:
    java.io.Serializable
    public class SslConfig
extends java.lang.Object
implements java.io.Serializable

    A container for SSL-related configuration options, meant to be stored within a VaultConfig instance.

    Construct instances of this class using a builder pattern, calling setter methods for each value and then terminating with a call to build().

    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      SslConfig()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      SslConfig build()
      This is the terminating method in the builder pattern.
      SslConfig clientKeyPemFile​(java.io.File clientKeyPemFile)
      An RSA private key, for use with Vault's TLS Certificate auth backend.
      SslConfig clientKeyPemResource​(java.lang.String classpathResource)
      An RSA private key, for use with Vault's TLS Certificate auth backend.
      SslConfig clientKeyPemUTF8​(java.lang.String clientKeyPemUTF8)
      An RSA private key, for use with Vault's TLS Certificate auth backend.
      SslConfig clientPemFile​(java.io.File clientPemFile)
      An X.509 client certificate, for use with Vault's TLS Certificate auth backend.
      SslConfig clientPemResource​(java.lang.String classpathResource)
      An X.509 certificate, for use with Vault's TLS Certificate auth backend.
      SslConfig clientPemUTF8​(java.lang.String clientPemUTF8)
      An X.509 client certificate, for use with Vault's TLS Certificate auth backend.
      protected SslConfig environmentLoader​(EnvironmentLoader environmentLoader)
      The code used to load environment variables is encapsulated here, so that a mock version of that environment loader can be used by unit tests.
      protected java.lang.String getPemUTF8()  
      javax.net.ssl.SSLContext getSslContext()  
      boolean isVerify()  
      SslConfig keyStore​(java.security.KeyStore keyStore, java.lang.String password)
      A Java keystore, containing a client certificate that's registered with Vault's TLS Certificate auth backend.
      SslConfig keyStoreFile​(java.io.File keyStoreFile, java.lang.String password)
      A Java keystore, containing a client certificate that's registered with Vault's TLS Certificate auth backend.
      SslConfig keyStoreResource​(java.lang.String classpathResource, java.lang.String password)
      A Java keystore, containing a client certificate that's registered with Vault's TLS Certificate auth backend.
      SslConfig pemFile​(java.io.File pemFile)
      An X.509 certificate, to use when communicating with Vault over HTTPS.
      SslConfig pemResource​(java.lang.String classpathResource)
      An X.509 certificate, to use when communicating with Vault over HTTPS.
      SslConfig pemUTF8​(java.lang.String pemUTF8)
      An X.509 certificate, to use when communicating with Vault over HTTPS.
      SslConfig trustStore​(java.security.KeyStore trustStore)
      A Java keystore, containing the X509 certificate used by Vault.
      SslConfig trustStoreFile​(java.io.File trustStoreFile)
      A Java keystore, containing the X509 certificate used by Vault.
      SslConfig trustStoreResource​(java.lang.String classpathResource)
      A Java keystore, containing the X509 certificate used by Vault.
      SslConfig verify​(java.lang.Boolean verify)
      Whether or not HTTPS connections to the Vault server should verify that a valid SSL certificate is being used.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • SslConfig

        public SslConfig()

    • Method Detail

      • environmentLoader

        protected SslConfig environmentLoader​(EnvironmentLoader environmentLoader)

        The code used to load environment variables is encapsulated here, so that a mock version of that environment loader can be used by unit tests.

        This method is used by unit tests, to inject a mock environment variable when constructing a SslConfig instance using the builder pattern approach rather than the convenience constructor. There really shouldn't ever be a need to call this method outside of a unit test context (hence the protected access level).

        Parameters:
        environmentLoader - An environment variable loader implementation (presumably a mock)
        Returns:
        This object, with environmentLoader populated, ready for additional builder-pattern method calls or else finalization with the build() method

      • verify

        public SslConfig verify​(java.lang.Boolean verify)

        Whether or not HTTPS connections to the Vault server should verify that a valid SSL certificate is being used. Unless this is set to false, the default behavior is to always verify SSL certificates.

        SSL CERTIFICATE VERIFICATION SHOULD NOT BE DISABLED IN PRODUCTION! This feature is made available to facilitate development or testing environments, where you might be using a self-signed cert that will not pass verification. However, even if you are using a self-signed cert on your Vault server, you can still leave SSL verification enabled and have your application supply the cert using pemFile(), pemResource(), or pemUTF8().

        If no verify is explicitly set, either by this method in a builder pattern approach or else by one of the convenience constructors, then SslConfig will look to the VAULT_SSL_VERIFY environment variable.

        Parameters:
        verify - Whether or not to verify the SSL certificate used by Vault with HTTPS connections. Default is true.
        Returns:
        This object, with verify populated, ready for additional builder-pattern method calls or else finalization with the build() method

      • keyStore

        public SslConfig keyStore​(java.security.KeyStore keyStore,
                          java.lang.String password)

        A Java keystore, containing a client certificate that's registered with Vault's TLS Certificate auth backend. If you are not using certificate based client auth, then this field may remain un-set.

        Note that you cannot mix-and-match JKS based config with PEM based config. If any of the keyStore or trustStore setters are used, then the build() method will complete ignore any PEM data that was set.

        Parameters:
        keyStore - A keystore, containing a client certificate registered with Vault's TLS Certificate auth backend
        password - The password needed to access the keystore (can be null)
        Returns:
        This object, with keyStore and keyStorePassword populated, ready for additional builder-pattern method calls or else finalization with the build() method

      • keyStoreFile

        public SslConfig keyStoreFile​(java.io.File keyStoreFile,
                              java.lang.String password)
                       throws VaultException

        A Java keystore, containing a client certificate that's registered with Vault's TLS Certificate auth backend. If you are not using certificate based client auth, then this field may remain un-set. This method loads the keystore from a JKS file on the filesystem.

        Note that you cannot mix-and-match JKS based config with PEM based config. If any of the keyStore or trustStore setters are used, then the build() method will complete ignore any PEM data that was set.

        Parameters:
        keyStoreFile - A JKS keystore file, containing a client certificate registered with Vault's TLS Certificate auth backend
        password - The password needed to access the keystore (can be null)
        Returns:
        This object, with keyStore and keyStorePassword populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading the keystore

      • keyStoreResource

        public SslConfig keyStoreResource​(java.lang.String classpathResource,
                                  java.lang.String password)
                           throws VaultException

        A Java keystore, containing a client certificate that's registered with Vault's TLS Certificate auth backend. If you are not using certificate based client auth, then this field may remain un-set. This method loads the keystore from a classpath resource (e.g. you've bundled the JKS file into your library or application's JAR/WAR/EAR file).

        Note that you cannot mix-and-match JKS based config with PEM based config. If any of the keyStore or trustStore setters are used, then the build() method will complete ignore any PEM data that was set.

        Parameters:
        classpathResource - A JKS keystore file, containing a client certificate registered with Vault's TLS Certificate auth backend
        password - The password needed to access the keystore (can be null)
        Returns:
        This object, with keyStore and keyStorePassword populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading the keystore

      • trustStore

        public SslConfig trustStore​(java.security.KeyStore trustStore)

        A Java keystore, containing the X509 certificate used by Vault. Used by the driver to trust SSL connections from the server using this cert.

        Note that you cannot mix-and-match JKS based config with PEM based config. If any of the keyStore or trustStore setters are used, then the build() method will complete ignore any PEM data that was set.

        Parameters:
        trustStore - A truststore, containing the Vault server's X509 certificate
        Returns:
        This object, with trustStore populated, ready for additional builder-pattern method calls or else finalization with the build() method

      • trustStoreFile

        public SslConfig trustStoreFile​(java.io.File trustStoreFile)
                         throws VaultException

        A Java keystore, containing the X509 certificate used by Vault. Used by the driver to trust SSL connections from the server using this cert. This method load the truststore from a JKS file on the filesystem.

        Note that you cannot mix-and-match JKS based config with PEM based config. If any of the keyStore or trustStore setters are used, then the build() method will complete ignore any PEM data that was set.

        Parameters:
        trustStoreFile - A JKS truststore file, containing the Vault server's X509 certificate
        Returns:
        This object, with trustStore populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading the truststore

      • trustStoreResource

        public SslConfig trustStoreResource​(java.lang.String classpathResource)
                             throws VaultException

        A Java keystore, containing the X509 certificate used by Vault. Used by the driver to trust SSL connections from the server using this cert. This method load the truststore from a classpath resource (e.g. you've bundled the JKS file into your library or application's JAR/WAR/EAR file).

        Note that you cannot mix-and-match JKS based config with PEM based config. If any of the keyStore or trustStore setters are used, then the build() method will complete ignore any PEM data that was set.

        Parameters:
        classpathResource - A JKS truststore file, containing the Vault server's X509 certificate
        Returns:
        This object, with trustStore populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading the truststore

      • pemUTF8

        public SslConfig pemUTF8​(java.lang.String pemUTF8)

        An X.509 certificate, to use when communicating with Vault over HTTPS. This method accepts a string containing the certificate data. This string should meet the following requirements:

        • Contain an unencrypted X.509 certificate, in PEM format.
        • Use UTF-8 encoding.
        • Contain a line-break between the certificate header (e.g. "-----BEGIN CERTIFICATE-----") and the rest of the certificate content. It doesn't matter whether or not there are additional line breaks within the certificate content, or whether there is a line break before the certificate footer (e.g. "-----END CERTIFICATE-----"). But the Java standard library will fail to properly process the certificate without a break following the header (see http://www.doublecloud.org/2014/03/reading-x-509-certificate-in-java-how-to-handle-format-issue/).

        If no certificate data is provided, either by this method or pemFile() or pemResource(), then SslConfig will look to the VAULT_SSL_CERT environment variable.

        Parameters:
        pemUTF8 - An X.509 certificate, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with pemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method

      • pemFile

        public SslConfig pemFile​(java.io.File pemFile)
                  throws VaultException

        An X.509 certificate, to use when communicating with Vault over HTTPS. This method accepts the path of a file containing the certificate data. This file's contents should meet the following requirements:

        • Contain an unencrypted X.509 certificate, in PEM format.
        • Use UTF-8 encoding.
        • Contain a line-break between the certificate header (e.g. "-----BEGIN CERTIFICATE-----") and the rest of the certificate content. It doesn't matter whether or not there are additional line breaks within the certificate content, or whether there is a line break before the certificate footer (e.g. "-----END CERTIFICATE-----"). But the Java standard library will fail to properly process the certificate without a break following the header (see http://www.doublecloud.org/2014/03/reading-x-509-certificate-in-java-how-to-handle-format-issue/).

        If no certificate data is provided, either by this method or pemResource() or pemUTF8(), then SslConfig will look to the VAULT_SSL_CERT environment variable.

        Parameters:
        pemFile - The path of a file containing an X.509 certificate, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with pemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading and parsing the PEM file

      • pemResource

        public SslConfig pemResource​(java.lang.String classpathResource)
                      throws VaultException

        An X.509 certificate, to use when communicating with Vault over HTTPS. This method accepts the path of a classpath resource containing the certificate data (e.g. you've bundled the cert into your library or application's JAR/WAR/EAR file). This resource's contents should meet the following requirements:

        • Contain an unencrypted X.509 certificate, in PEM format.
        • Use UTF-8 encoding.
        • Contain a line-break between the certificate header (e.g. "-----BEGIN CERTIFICATE-----") and the rest of the certificate content. It doesn't matter whether or not there are additional line breaks within the certificate content, or whether there is a line break before the certificate footer (e.g. "-----END CERTIFICATE-----"). But the Java standard library will fail to properly process the certificate without a break following the header (see http://www.doublecloud.org/2014/03/reading-x-509-certificate-in-java-how-to-handle-format-issue/).

        If no certificate data is provided, either by this method or pemFile() or pemUTF8(), then SslConfig will look to the VAULT_SSL_CERT environment variable.

        Parameters:
        classpathResource - The path of a classpath resource containing an X.509 certificate, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with pemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading and parsing the PEM file

      • clientPemUTF8

        public SslConfig clientPemUTF8​(java.lang.String clientPemUTF8)

        An X.509 client certificate, for use with Vault's TLS Certificate auth backend. This string should meet the same formatting requirements as pemUTF8(String).

        Parameters:
        clientPemUTF8 - An X.509 client certificate, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with clientPemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method
        See Also:
        Auth.loginByCert()

      • clientPemFile

        public SslConfig clientPemFile​(java.io.File clientPemFile)
                        throws VaultException

        An X.509 client certificate, for use with Vault's TLS Certificate auth backend. This method accepts the path of a file containing the certificate data. This file should meet the same requirements as pemFile(File).

        Parameters:
        clientPemFile - The path of a file containing an X.509 certificate, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with clientPemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading and parsing the PEM file
        See Also:
        Auth.loginByCert()

      • clientPemResource

        public SslConfig clientPemResource​(java.lang.String classpathResource)
                            throws VaultException

        An X.509 certificate, for use with Vault's TLS Certificate auth backend. This method accepts the path of a classpath resource containing the certificate data (e.g. you've bundled the cert into your library or application's JAR/WAR/EAR file). This resource's contents should meet the same requirements as pemResource(String).

        Parameters:
        classpathResource - The path of a classpath resource containing an X.509 certificate, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with clientPemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading and parsing the PEM file
        See Also:
        Auth.loginByCert()

      • clientKeyPemUTF8

        public SslConfig clientKeyPemUTF8​(java.lang.String clientKeyPemUTF8)

        An RSA private key, for use with Vault's TLS Certificate auth backend. The string should meet the following requirements:

        • Contain an unencrypted RSA private key, in PEM format.
        • Use UTF-8 encoding.
        Parameters:
        clientKeyPemUTF8 - An RSA private key, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with clientKeyPemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method

      • clientKeyPemFile

        public SslConfig clientKeyPemFile​(java.io.File clientKeyPemFile)
                           throws VaultException

        An RSA private key, for use with Vault's TLS Certificate auth backend. This method accepts the path of a file containing the private key data. This file's contents should meet the following requirements:

        • Contain an unencrypted RSA private key, in PEM format.
        • Use UTF-8 encoding.
        Parameters:
        clientKeyPemFile - The path of a file containing an RSA private key, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with clientKeyPemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading and parsing the PEM file

      • clientKeyPemResource

        public SslConfig clientKeyPemResource​(java.lang.String classpathResource)
                               throws VaultException

        An RSA private key, for use with Vault's TLS Certificate auth backend. This method accepts the path of a classpath resource containing the private key data (e.g. you've bundled the private key into your library or application's JAR/WAR/EAR file). This file's contents should meet the following requirements:

        • Contain an unencrypted RSA private key, in PEM format.
        • Use UTF-8 encoding.
        Parameters:
        classpathResource - The path of a classpath resource containing an RSA private key, in unencrypted PEM format with UTF-8 encoding.
        Returns:
        This object, with clientKeyPemUTF8 populated, ready for additional builder-pattern method calls or else finalization with the build() method
        Throws:
        VaultException - If any error occurs while loading and parsing the PEM file

      • build

        public SslConfig build()
                throws VaultException

        This is the terminating method in the builder pattern. The method that validates all of the fields that has been set already, uses environment variables when available to populate any unset fields, and returns a SslConfig object that is ready for use.

        Returns:
        This object, with all available config options parsed and loaded
        Throws:
        VaultException - If SSL certificate verification is enabled, and any problem occurs while trying to build an SSLContext

      • isVerify

        public boolean isVerify()

      • getSslContext

        public javax.net.ssl.SSLContext getSslContext()

      • getPemUTF8

        protected java.lang.String getPemUTF8()