Class SOCKSProxySocketFactory


  • @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class SOCKSProxySocketFactory
    extends javax.net.SocketFactory
    This class provides an implementation of a socket factory that can be used to forward traffic through a SOCKSv4 or SOCKSv5 proxy server. Because of limitations in the Java support for SOCKS proxy servers, the following constraints will be imposed:
    • Communication with the proxy server itself cannot be encrypted. However, it is possible to encrypt all communication through the proxy server to the actual target server using TLS (by providing an SSLSocketFactory instance when creating the SOCKSProxySocketFactory), in which case the data will still be protected from the client to that target server, and anyone observing the communication between the client and the SOCKS proxy, or between the SOCKS proxy and the target server, would not be able to decipher that communication.
    • This implementation only provides direct support for proxy servers that do not require authentication. Although it may be possible to configure authentication using Java system properties, this implementation does not provide any direct support for authentication.


    Example

    The following example demonstrates the process for establishing an LDAPS connection through a SOCKS proxy server:
       final String socksProxyServerAddress = "socks-proxy.example.com";
       final int socksProxyServerPort = 1080;
       final int connectTimeoutMillis = 10_000;
    
       final SSLUtil sslUtil =
            new SSLUtil(new TrustStoreTrustManager("/path/to/trust/store"));
       final SSLSocketFactory ldapsSocketFactory =
            sslUtil.createSSLSocketFactory();
    
       final SOCKSProxySocketFactory socksProxySocketFactory =
            new SOCKSProxySocketFactory(socksProxyServerAddress,
                 socksProxyServerPort, connectTimeoutMillis,
                 ldapsSocketFactory);
    
       final String ldapsServerAddress = "ds.example.com";
       final int ldapsServerPort = 636;
    
       try (LDAPConnection conn = new LDAPConnection(socksProxySocketFactory,
            ldapsServerAddress, ldapsServerPort))
       {
         // Do something with the connection here.
       }
     
    • Constructor Summary

      Constructors 
      Constructor Description
      SOCKSProxySocketFactory​(java.lang.String socksProxyHost, int socksProxyPort, int connectTimeoutMillis)
      Creates a new instance of this SOCKS socket factory with the provided settings.
      SOCKSProxySocketFactory​(java.lang.String socksProxyHost, int socksProxyPort, int connectTimeoutMillis, javax.net.ssl.SSLSocketFactory sslSocketFactory)
      Creates a new instance of this SOCKS socket factory with the provided settings.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.net.Socket createSocket()
      Creates an unconnected socket that will use the configured proxy server for communication.
      java.net.Socket createSocket​(java.lang.String host, int port)
      Creates a new socket that is connected to the specified system through the proxy server.
      java.net.Socket createSocket​(java.lang.String host, int port, java.net.InetAddress localHost, int localPort)
      Creates a new socket that is connected to the specified system through the proxy server.
      java.net.Socket createSocket​(java.net.InetAddress host, int port)
      Creates a new socket that is connected to the specified system through the proxy server.
      java.net.Socket createSocket​(java.net.InetAddress host, int port, java.net.InetAddress localHost, int localPort)
      Creates a new socket that is connected to the specified system through the proxy server.
      • Methods inherited from class javax.net.SocketFactory

        getDefault
      • Methods inherited from class java.lang.Object

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

      • SOCKSProxySocketFactory

        public SOCKSProxySocketFactory​(@NotNull
                                       java.lang.String socksProxyHost,
                                       int socksProxyPort,
                                       int connectTimeoutMillis)
        Creates a new instance of this SOCKS socket factory with the provided settings. The resulting socket factory will provide support for unencrypted LDAP communication.
        Parameters:
        socksProxyHost - The address of the SOCKS proxy server. It must not be null.
        socksProxyPort - The port on which the SOCKS proxy is listening for new connections.
        connectTimeoutMillis - The maximum length of time in milliseconds to wait for a connection to be established. A value that is less than or equal to zero indicates that no explicit timeout will be imposed.
      • SOCKSProxySocketFactory

        public SOCKSProxySocketFactory​(@NotNull
                                       java.lang.String socksProxyHost,
                                       int socksProxyPort,
                                       int connectTimeoutMillis,
                                       @Nullable
                                       javax.net.ssl.SSLSocketFactory sslSocketFactory)
        Creates a new instance of this SOCKS socket factory with the provided settings. The resulting socket factory may provide support for either unencrypted LDAP communication (if the provided sslSocketFactory value is null) or encrypted LDAPS communication (if the provided sslSocketFactory value is non-null).
        Parameters:
        socksProxyHost - The address of the SOCKS proxy server. It must not be null.
        socksProxyPort - The port on which the SOCKS proxy is listening for new connections.
        connectTimeoutMillis - The maximum length of time in milliseconds to wait for a connection to be established. A value that is less than or equal to zero indicates that no explicit timeout will be imposed.
        sslSocketFactory - An SSL socket factory that should be used if communication with the target LDAP server should be encrypted with TLS. It must be null if communication should not be encrypted, and it must not be null if communication should be encrypted with TLS.
    • Method Detail

      • createSocket

        @NotNull
        public final java.net.Socket createSocket()
                                           throws java.lang.UnsupportedOperationException
        Creates an unconnected socket that will use the configured proxy server for communication. Note that this method can only be used when communication through the proxy server will not be encrypted.
        Overrides:
        createSocket in class javax.net.SocketFactory
        Throws:
        java.lang.UnsupportedOperationException - If an SSLSocketFactory has been configured to secure communication with end servers.
      • createSocket

        @NotNull
        public final java.net.Socket createSocket​(@NotNull
                                                  java.lang.String host,
                                                  int port)
                                           throws java.io.IOException
        Creates a new socket that is connected to the specified system through the proxy server.
        Specified by:
        createSocket in class javax.net.SocketFactory
        Parameters:
        host - The address of the server to which the socket should be established. It must not be null.
        port - The port of the server to which the socket should be established.
        Throws:
        java.io.IOException - If a problem is encountered while attempting to establish the connection.
      • createSocket

        @NotNull
        public final java.net.Socket createSocket​(@NotNull
                                                  java.lang.String host,
                                                  int port,
                                                  @Nullable
                                                  java.net.InetAddress localHost,
                                                  int localPort)
                                           throws java.io.IOException
        Creates a new socket that is connected to the specified system through the proxy server.
        Specified by:
        createSocket in class javax.net.SocketFactory
        Parameters:
        host - The address of the server to which the socket should be established. It must not be null.
        port - The port of the server to which the socket should be established.
        localHost - The local address to which the socket should be bound. It may optionally be null it may be bound to any local address.
        localPort - The local port to which the socket should be bound.
        Throws:
        java.io.IOException - If a problem is encountered while attempting to establish the connection.
      • createSocket

        @NotNull
        public final java.net.Socket createSocket​(@NotNull
                                                  java.net.InetAddress host,
                                                  int port)
                                           throws java.io.IOException
        Creates a new socket that is connected to the specified system through the proxy server.
        Specified by:
        createSocket in class javax.net.SocketFactory
        Parameters:
        host - The address of the server to which the socket should be established. It must not be null.
        port - The port of the server to which the socket should be established.
        Throws:
        java.io.IOException - If a problem is encountered while attempting to establish the connection.
      • createSocket

        @NotNull
        public final java.net.Socket createSocket​(@NotNull
                                                  java.net.InetAddress host,
                                                  int port,
                                                  @Nullable
                                                  java.net.InetAddress localHost,
                                                  int localPort)
                                           throws java.io.IOException
        Creates a new socket that is connected to the specified system through the proxy server.
        Specified by:
        createSocket in class javax.net.SocketFactory
        Parameters:
        host - The address of the server to which the socket should be established. It must not be null.
        port - The port of the server to which the socket should be established.
        localHost - The local address to which the socket should be bound. It may optionally be null if it may be bound to any local address.
        localPort - The local port to which the socket should be bound.
        Throws:
        java.io.IOException - If a problem is encountered while attempting to establish the connection.