com.unboundid.util

Class SOCKSProxySocketFactory

java.lang.Object

javax.net.SocketFactory

com.unboundid.util.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 and 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

Methods

Modifier and Type	Method and Description
java.net.Socket	createSocket() Creates an unconnected socket that will use the configured proxy server for communication.
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.
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.

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.