Class SSLUtil


  • @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class SSLUtil
    extends java.lang.Object
    This class provides a simple interface for creating SSLContext and SSLSocketFactory instances, which may be used to create SSL-based connections, or secure existing connections with StartTLS. Support for the TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 protocols will be enabled by default (if the JVM supports them), with TLSv1.3 being the preferred protocol.

    Example 1

    The following example demonstrates the use of the SSL helper to create an SSL-based LDAP connection that will blindly trust any certificate that the server presents. Using the TrustAllTrustManager is only recommended for testing purposes, since blindly trusting any certificate is not secure.
     // Create an SSLUtil instance that is configured to trust any certificate,
     // and use it to create a socket factory.
     SSLUtil sslUtil = new SSLUtil(new TrustAllTrustManager());
     SSLSocketFactory sslSocketFactory = sslUtil.createSSLSocketFactory();
    
     // Establish a secure connection using the socket factory.
     LDAPConnection connection = new LDAPConnection(sslSocketFactory);
     connection.connect(serverAddress, serverSSLPort);
    
     // Process operations using the connection....
     RootDSE rootDSE = connection.getRootDSE();
    
     connection.close();
     

    Example 2

    The following example demonstrates the use of the SSL helper to create a non-secure LDAP connection and then use the StartTLS extended operation to secure it. It will use a trust store to determine whether to trust the server certificate.
     // Establish a non-secure connection to the server.
     LDAPConnection connection = new LDAPConnection(serverAddress, serverPort);
    
     // Create an SSLUtil instance that is configured to trust certificates in
     // a specified trust store file, and use it to create an SSLContext that
     // will be used for StartTLS processing.
     SSLUtil sslUtil = new SSLUtil(new TrustStoreTrustManager(trustStorePath));
     SSLContext sslContext = sslUtil.createSSLContext();
    
     // Use the StartTLS extended operation to secure the connection.
     StartTLSExtendedRequest startTLSRequest =
          new StartTLSExtendedRequest(sslContext);
     ExtendedResult startTLSResult;
     try
     {
       startTLSResult = connection.processExtendedOperation(startTLSRequest);
     }
     catch (LDAPException le)
     {
       startTLSResult = new ExtendedResult(le);
     }
     LDAPTestUtils.assertResultCodeEquals(startTLSResult, ResultCode.SUCCESS);
    
     // Process operations using the connection....
     RootDSE rootDSE = connection.getRootDSE();
    
     connection.close();
     
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String PROPERTY_DEFAULT_SSL_PROTOCOL
      The name of the system property that can be used to specify the initial value for the default SSL protocol that should be used.
      static java.lang.String PROPERTY_ENABLED_SSL_CIPHER_SUITES
      The name of the system property that can be used to provide the initial set of enabled SSL cipher suites that should be used, as a comma-delimited list.
      static java.lang.String PROPERTY_ENABLED_SSL_PROTOCOLS
      The name of the system property that can be used to provide the initial set of enabled SSL protocols that should be used, as a comma-delimited list.
      static java.lang.String SSL_PROTOCOL_SSL_2_HELLO
      The name of the SSL protocol that can be used to request SSLv2Hello.
      static java.lang.String SSL_PROTOCOL_SSL_3
      The name of the SSL protocol that can be used to request SSLv3.
      static java.lang.String SSL_PROTOCOL_TLS_1
      The name of the SSL protocol that can be used to request TLSv1.
      static java.lang.String SSL_PROTOCOL_TLS_1_1
      The name of the SSL protocol that can be used to request TLSv1.1.
      static java.lang.String SSL_PROTOCOL_TLS_1_2
      The name of the SSL protocol that can be used to request TLSv1.2.
      static java.lang.String SSL_PROTOCOL_TLS_1_3
      The name of the SSL protocol that can be used to request TLSv1.3.
    • Constructor Summary

      Constructors 
      Constructor Description
      SSLUtil()
      Creates a new SSLUtil instance that will not have a custom key manager or trust manager.
      SSLUtil​(javax.net.ssl.KeyManager[] keyManagers, javax.net.ssl.TrustManager[] trustManagers)
      Creates a new SSLUtil instance that will use the provided key managers to obtain certificates to present to the server, and the provided trust managers to determine whether to trust server certificates presented to the client.
      SSLUtil​(javax.net.ssl.KeyManager keyManager, javax.net.ssl.TrustManager trustManager)
      Creates a new SSLUtil instance that will use the provided key manager to obtain certificates to present to the server, and the provided trust manager to determine whether to trust server certificates presented to the client.
      SSLUtil​(javax.net.ssl.TrustManager trustManager)
      Creates a new SSLUtil instance that will use the provided trust manager to determine whether to trust server certificates presented to the client.
      SSLUtil​(javax.net.ssl.TrustManager[] trustManagers)
      Creates a new SSLUtil instance that will use the provided trust managers to determine whether to trust server certificates presented to the client.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void applyEnabledSSLCipherSuites​(java.net.Socket socket)
      Updates the provided socket to apply the appropriate set of enabled SSL cipher suites.
      static void applyEnabledSSLProtocols​(java.net.Socket socket)
      Updates the provided socket to apply the appropriate set of enabled SSL protocols.
      static java.lang.String certificateToString​(java.security.cert.X509Certificate certificate)
      Creates a string representation of the provided certificate.
      static void certificateToString​(java.security.cert.X509Certificate certificate, java.lang.StringBuilder buffer)
      Appends a string representation of the provided certificate to the given buffer.
      javax.net.ssl.SSLContext createSSLContext()
      Creates an initialized SSL context created with the configured key and trust managers.
      javax.net.ssl.SSLContext createSSLContext​(java.lang.String protocol)
      Creates an initialized SSL context created with the configured key and trust managers.
      javax.net.ssl.SSLContext createSSLContext​(java.lang.String protocol, java.lang.String provider)
      Creates an initialized SSL context created with the configured key and trust managers.
      javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory()
      Creates an SSL server socket factory using the configured key and trust manager providers.
      javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory​(java.lang.String protocol)
      Creates an SSL server socket factory using the configured key and trust manager providers.
      javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory​(java.lang.String protocol, java.lang.String provider)
      Creates an SSL server socket factory using the configured key and trust manager providers.
      javax.net.ssl.SSLSocketFactory createSSLSocketFactory()
      Creates an SSL socket factory using the configured key and trust manager providers.
      javax.net.ssl.SSLSocketFactory createSSLSocketFactory​(java.lang.String protocol)
      Creates an SSL socket factory with the configured key and trust managers.
      javax.net.ssl.SSLSocketFactory createSSLSocketFactory​(java.lang.String protocol, java.lang.String provider)
      Creates an SSL socket factory with the configured key and trust managers.
      static java.lang.String getDefaultSSLProtocol()
      Retrieves the SSL protocol string that will be used by calls to createSSLContext() that do not explicitly specify which protocol to use.
      static java.util.Set<java.lang.String> getEnabledSSLCipherSuites()
      Retrieves the set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
      static java.util.Set<java.lang.String> getEnabledSSLProtocols()
      Retrieves the set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
      javax.net.ssl.KeyManager[] getKeyManagers()
      Retrieves the set of key managers configured for use by this class, if any.
      javax.net.ssl.TrustManager[] getTrustManagers()
      Retrieves the set of trust managers configured for use by this class, if any.
      static void setDefaultSSLProtocol​(java.lang.String defaultSSLProtocol)
      Specifies the SSL protocol string that will be used by calls to createSSLContext() that do not explicitly specify which protocol to use.
      static void setEnabledSSLCipherSuites​(java.util.Collection<java.lang.String> enabledSSLCipherSuites)
      Specifies the set of SSL cipher suites that will be enabled for SSL sockets created within the LDAP SDK.
      static void setEnabledSSLProtocols​(java.util.Collection<java.lang.String> enabledSSLProtocols)
      Specifies the set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • SSLUtil

        public SSLUtil()
        Creates a new SSLUtil instance that will not have a custom key manager or trust manager. It will not be able to provide a certificate to the server if one is requested, and it will only trust certificates signed by a predefined set of authorities.
      • SSLUtil

        public SSLUtil​(javax.net.ssl.TrustManager trustManager)
        Creates a new SSLUtil instance that will use the provided trust manager to determine whether to trust server certificates presented to the client. It will not be able to provide a certificate to the server if one is requested.
        Parameters:
        trustManager - The trust manager to use to determine whether to trust server certificates presented to the client. It may be null if the default set of trust managers should be used.
      • SSLUtil

        public SSLUtil​(javax.net.ssl.TrustManager[] trustManagers)
        Creates a new SSLUtil instance that will use the provided trust managers to determine whether to trust server certificates presented to the client. It will not be able to provide a certificate to the server if one is requested.
        Parameters:
        trustManagers - The set of trust managers to use to determine whether to trust server certificates presented to the client. It may be null or empty if the default set of trust managers should be used.
      • SSLUtil

        public SSLUtil​(javax.net.ssl.KeyManager keyManager,
                       javax.net.ssl.TrustManager trustManager)
        Creates a new SSLUtil instance that will use the provided key manager to obtain certificates to present to the server, and the provided trust manager to determine whether to trust server certificates presented to the client.
        Parameters:
        keyManager - The key manager to use to obtain certificates to present to the server if requested. It may be null if no client certificates will be required or should be provided.
        trustManager - The trust manager to use to determine whether to trust server certificates presented to the client. It may be null if the default set of trust managers should be used.
      • SSLUtil

        public SSLUtil​(javax.net.ssl.KeyManager[] keyManagers,
                       javax.net.ssl.TrustManager[] trustManagers)
        Creates a new SSLUtil instance that will use the provided key managers to obtain certificates to present to the server, and the provided trust managers to determine whether to trust server certificates presented to the client.
        Parameters:
        keyManagers - The set of key managers to use to obtain certificates to present to the server if requested. It may be null or empty if no client certificates will be required or should be provided.
        trustManagers - The set of trust managers to use to determine whether to trust server certificates presented to the client. It may be null or empty if the default set of trust managers should be used.
    • Method Detail

      • getKeyManagers

        public javax.net.ssl.KeyManager[] getKeyManagers()
        Retrieves the set of key managers configured for use by this class, if any.
        Returns:
        The set of key managers configured for use by this class, or null if none were provided.
      • getTrustManagers

        public javax.net.ssl.TrustManager[] getTrustManagers()
        Retrieves the set of trust managers configured for use by this class, if any.
        Returns:
        The set of trust managers configured for use by this class, or null if none were provided.
      • createSSLContext

        public javax.net.ssl.SSLContext createSSLContext()
                                                  throws java.security.GeneralSecurityException
        Creates an initialized SSL context created with the configured key and trust managers. It will use the protocol returned by the getDefaultSSLProtocol() method and the JVM-default provider.
        Returns:
        The created SSL context.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL context.
      • createSSLContext

        public javax.net.ssl.SSLContext createSSLContext​(java.lang.String protocol)
                                                  throws java.security.GeneralSecurityException
        Creates an initialized SSL context created with the configured key and trust managers. It will use the default provider.
        Parameters:
        protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.
        Returns:
        The created SSL context.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL context.
      • createSSLContext

        public javax.net.ssl.SSLContext createSSLContext​(java.lang.String protocol,
                                                         java.lang.String provider)
                                                  throws java.security.GeneralSecurityException
        Creates an initialized SSL context created with the configured key and trust managers.
        Parameters:
        protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.
        provider - The name of the provider to use for cryptographic operations. It must not be null.
        Returns:
        The created SSL context.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL context.
      • createSSLSocketFactory

        public javax.net.ssl.SSLSocketFactory createSSLSocketFactory()
                                                              throws java.security.GeneralSecurityException
        Creates an SSL socket factory using the configured key and trust manager providers. It will use the protocol returned by the getDefaultSSLProtocol() method and the JVM-default provider.
        Returns:
        The created SSL socket factory.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL socket factory.
      • createSSLSocketFactory

        public javax.net.ssl.SSLSocketFactory createSSLSocketFactory​(java.lang.String protocol)
                                                              throws java.security.GeneralSecurityException
        Creates an SSL socket factory with the configured key and trust managers. It will use the default provider.
        Parameters:
        protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.
        Returns:
        The created SSL socket factory.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL socket factory.
      • createSSLSocketFactory

        public javax.net.ssl.SSLSocketFactory createSSLSocketFactory​(java.lang.String protocol,
                                                                     java.lang.String provider)
                                                              throws java.security.GeneralSecurityException
        Creates an SSL socket factory with the configured key and trust managers.
        Parameters:
        protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.
        provider - The name of the provider to use for cryptographic operations. It must not be null.
        Returns:
        The created SSL socket factory.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL socket factory.
      • createSSLServerSocketFactory

        public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory()
                                                                          throws java.security.GeneralSecurityException
        Creates an SSL server socket factory using the configured key and trust manager providers. It will use the protocol returned by the getDefaultSSLProtocol() method and the JVM-default provider.
        Returns:
        The created SSL server socket factory.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL server socket factory.
      • createSSLServerSocketFactory

        public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory​(java.lang.String protocol)
                                                                          throws java.security.GeneralSecurityException
        Creates an SSL server socket factory using the configured key and trust manager providers. It will use the JVM-default provider.
        Parameters:
        protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.
        Returns:
        The created SSL server socket factory.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL server socket factory.
      • createSSLServerSocketFactory

        public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory​(java.lang.String protocol,
                                                                                 java.lang.String provider)
                                                                          throws java.security.GeneralSecurityException
        Creates an SSL server socket factory using the configured key and trust manager providers.
        Parameters:
        protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.
        provider - The name of the provider to use for cryptographic operations. It must not be null.
        Returns:
        The created SSL server socket factory.
        Throws:
        java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL server socket factory.
      • getDefaultSSLProtocol

        public static java.lang.String getDefaultSSLProtocol()
        Retrieves the SSL protocol string that will be used by calls to createSSLContext() that do not explicitly specify which protocol to use.
        Returns:
        The SSL protocol string that will be used by calls to create an SSL context that do not explicitly specify which protocol to use.
      • setDefaultSSLProtocol

        public static void setDefaultSSLProtocol​(java.lang.String defaultSSLProtocol)
        Specifies the SSL protocol string that will be used by calls to createSSLContext() that do not explicitly specify which protocol to use.
        Parameters:
        defaultSSLProtocol - The SSL protocol string that will be used by calls to create an SSL context that do not explicitly specify which protocol to use. It must not be null.
      • getEnabledSSLProtocols

        public static java.util.Set<java.lang.String> getEnabledSSLProtocols()
        Retrieves the set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
        Returns:
        The set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
      • setEnabledSSLProtocols

        public static void setEnabledSSLProtocols​(java.util.Collection<java.lang.String> enabledSSLProtocols)
        Specifies the set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK. When creating an SSL socket, the SSLSocket.getSupportedProtocols method will be used to determine which protocols are supported for that socket, and then the SSLSocket.setEnabledProtocols method will be used to enable those protocols which are listed as both supported by the socket and included in this set. If the provided set is null or empty, then the default set of enabled protocols will be used.
        Parameters:
        enabledSSLProtocols - The set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK. It may be null or empty to indicate that the JDK-default set of enabled protocols should be used for the socket.
      • applyEnabledSSLProtocols

        public static void applyEnabledSSLProtocols​(java.net.Socket socket)
                                             throws LDAPException
        Updates the provided socket to apply the appropriate set of enabled SSL protocols. This will only have any effect for sockets that are instances of javax.net.ssl.SSLSocket, but it is safe to call for any kind of java.net.Socket. This should be called before attempting any communication over the socket.
        Parameters:
        socket - The socket on which to apply the configured set of enabled SSL protocols.
        Throws:
        LDAPException - If getEnabledSSLProtocols() returns a non-empty set but none of the values in that set are supported by the socket.
      • getEnabledSSLCipherSuites

        public static java.util.Set<java.lang.String> getEnabledSSLCipherSuites()
        Retrieves the set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
        Returns:
        The set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
      • setEnabledSSLCipherSuites

        public static void setEnabledSSLCipherSuites​(java.util.Collection<java.lang.String> enabledSSLCipherSuites)
        Specifies the set of SSL cipher suites that will be enabled for SSL sockets created within the LDAP SDK. When creating an SSL socket, the SSLSocket.getSupportedCipherSuites method will be used to determine which cipher suites are supported for that socket, and then the SSLSocket.setEnabledCipherSuites method will be used to enable those suites which are listed as both supported by the socket and included in this set. If the provided set is null or empty, then the default set of enabled cipher suites will be used.
        Parameters:
        enabledSSLCipherSuites - The set of SSL cipher suites that will be enabled for use for SSL sockets created within the LDAP SDK. It may be null or empty to indicate that the JDK-default set of enabled cipher suites should be used for the socket.
      • applyEnabledSSLCipherSuites

        public static void applyEnabledSSLCipherSuites​(java.net.Socket socket)
                                                throws LDAPException
        Updates the provided socket to apply the appropriate set of enabled SSL cipher suites. This will only have any effect for sockets that are instances of javax.net.ssl.SSLSocket, but it is safe to call for any kind of java.net.Socket. This should be called before attempting any communication over the socket.
        Parameters:
        socket - The socket on which to apply the configured set of enabled SSL cipher suties.
        Throws:
        LDAPException - If getEnabledSSLCipherSuites() returns a non-empty set but none of the values in that set are supported by the socket.
      • certificateToString

        public static java.lang.String certificateToString​(java.security.cert.X509Certificate certificate)
        Creates a string representation of the provided certificate.
        Parameters:
        certificate - The certificate for which to generate the string representation. It must not be null.
        Returns:
        A string representation of the provided certificate.
      • certificateToString

        public static void certificateToString​(java.security.cert.X509Certificate certificate,
                                               java.lang.StringBuilder buffer)
        Appends a string representation of the provided certificate to the given buffer.
        Parameters:
        certificate - The certificate for which to generate the string representation. It must not be null.
        buffer - The buffer to which to append the string representation.