Package com.microstrategy.utils.ssl

Class TLSHelper

  • public class TLSHelper
extends java.lang.Object

    TLSHelper is a factory (see getSocketFactory()) for TLS connections to other services such as the Intelligence Server or OpenRefine Server.

    It collates the features of several SSL/TLS legacy libraries, enabling control of TLS version, restriction of cipher suites, management of key stores as well as trust stores (mutual authentication or client certificates), and several other TLS related configurations.

    EnumTLSCipherStrategy helps simplify configuration of secure cipher suites - the default EnumTLSCipherStrategy.MOZILLA_INTERMEDIATE uses the Intermediate ciphers recommended in Mozilla

    See Also:
    getInstance(), getSocketFactory()

    • Method Detail

      • getInstance

        public static TLSHelper getInstance()
        Entry point for obtaining singleton helper.

      • getSocketFactory

        public javax.net.ssl.SSLSocketFactory getSocketFactory()
                                                throws MSTRSecurityException
        Obtains a SSLSocketFactory. Avoid caching this in order to retrieve an instance that has the most recent configuration changes.
        Returns:
        the SSLSocketFactory
        Throws:
        MSTRSecurityException

      • requireSecure

        public boolean requireSecure​(java.lang.String url)
                      throws MSTRSecurityException

        If the URL protocol/scheme, such as "http" or "https" is not specified, it is assumed to be a connection to the Intelligence Server XML API endpoints. Normally, a URL must specify a protocol (see URL), but we permit this exception because Intelligence Server does not have a registered scheme.

        Throws:
        MSTRSecurityException

      • setProtocol

        public void setProtocol​(java.lang.String p)
                 throws MSTRSecurityException
        Manually set the TLS protocol. Protocol must be supported by SSLContext.getInstance(String).
        Parameters:
        p - TLS protocol.
        Throws:
        MSTRSecurityException - if unsupported protocol.

      • getProtocol

        public java.lang.String getProtocol()
        Returns the TLS protocol. Default is TLS 1.2.
        Returns:
        TLS protocol used in getSSLContext().

      • setTruststore

        public void setTruststore​(java.lang.String path,
                          char[] tsPassword)
                   throws java.lang.IllegalArgumentException,
                          MSTRSecurityException
        Sets the details about the trust store to be used. Note that if the trust store does not exist or is empty, the system trust store will be used instead.
        Parameters:
        absPathToTruststore - Absolute path to the trust store file.
        tsPassword - Trust store password as char array.
        Throws:
        java.lang.IllegalArgumentException - if the trust store path is null or empty.
        MSTRSecurityException - errors associated with the password or the truststore.

      • setKeystore

        public void setKeystore​(java.lang.String path,
                        char[] ksPassword)
                 throws java.lang.IllegalArgumentException,
                        MSTRSecurityException
        Sets the details about the client key store to be used. Required to support TLS with client certificates (mutual authentication).
        Parameters:
        absPathToKeystore - Absolute path to the key store file
        ksPassword - Key store password as char array.
        Throws:
        java.lang.IllegalArgumentException - if the key store path is null or empty
        EncryptedObjectException - if the EncryptedObject for the password encounters some problem
        MSTRSecurityException

      • addTruststoreCertificate

        public void addTruststoreCertificate​(java.security.cert.Certificate serverCert)
                              throws java.lang.IllegalArgumentException,
                                     MSTRSecurityException
        Adds certificate to the trust store.
        Throws:
        java.lang.IllegalArgumentException - thrown if serverCert is null.
        MSTRSecurityException - thrown if certificate is invalid, could not be read, or imported.

      • getTrustManagers

        public java.util.List<javax.net.ssl.TrustManager> getTrustManagers()

      • reset

        public void reset()
        Resets all configuration.

      • mergeTruststore

        public void mergeTruststore​(java.lang.String fromPath,
                            char[] pwd)
                     throws MSTRSecurityException

        Merges all certificates from a specified trust store into the existing trust store previously configured with setTruststore(String, char[]).

        If the file cannot be found or is empty, this operation is simply ignored.

        Parameters:
        fromPath - file location to the specified trust store to be merged from
        pwd - password of the specified trust store
        Throws:
        MSTRSecurityException - if target trust store does not exist, problems reading it, or merging