ABOUT
In its simplest usage, SocketSwitchboard forwards all incoming traffic on a single network port to a designated host and port on a LAN or on the Internet. An XML configuration file is used to set up one or more of these "socket mappings." However, the configuration schema also allows the administrator to specify complex boolean access restrictions, called constraints, to be applied to incoming network connections. Configured in this way, SocketSwitchboard can act as a virtual router or proxy, allowing restricted access to network services. Currently, SocketSwitchboard supports constraints based on IP address range, IP address pattern match, hostname pattern match, time of day, day of week, and SSL client authentication. The constraint framework is extensible, allowing new constraint classes to be written and specified in the configuration. In addition, either or both ends of a socket mapping may be configured to require the use of SSL sockets. Using two instances of SocketSwitchboad configured to use SSL, one running on a server behind a firewall and the other on a mobile client, a poor man's VPN can be achieved.
DOWNLOAD AND INSTALLATION
SocketSwitchboard can be downloaded from SourceForge.net at the SocketSwitchboard project homepage: http://sbdaemon.sourceforge.net. It requires the Java 2 Platform, Standard Edition (J2SE) v1.2 or later runtime environment, available at: http://java.sun.com/j2se.
SocketSwitchboard is available as a single JAR file containing all of the resources needed by the application except the XML configuration file. To install the application, follow these steps:
RUNNING THE PROGRAM
Run SocketSwitchboard by executing the following command from your $SB_HOME directory, substituting the path to your $SB_HOME directory (or an environment variable that contains its path) for the string "$SB_HOME":
java -classpath $SB_HOME/Switchboard.jar com.ihafer.switchboard.Switchboard
RUNTIME OPTIONS:
If you want to use a configuration file in a different location than the default $SB_HOME/switchboard.xml, specify the path to the desired file at the end of the command as shown in the example below:
java -classpath $SB_HOME/Switchboard.jar com.ihafer.switchboard.Switchboard
C:\Switchboard\config.xml
If your configuration specifies that one or more sockets should use SSL, then you must specify keystore and truststore files and passwords as shown below:
java -classpath $SB_HOME/Switchboard.jar
-Djavax.net.ssl.keyStore=keystore-file-path
-Djavax.net.ssl.keyStorePassword=keystore-password
-Djavax.net.ssl.trustStore=truststore-file-path
-Djavax.net.ssl.trustStorePassword=truststore-password
com.ihafer.switchboard.Switchboard
For help generating keystore files, see Sun's keytool documentation at: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html.
CONFIGURATION
SocketSwitchboard is configured via an XML file located by default at $SB_HOME/switchboard.xml. Please refer to the sample switchboard.xml file below for examples while reading these instructions.
SOCKET MAPPINGS:
The root element of the file is <switchboard>. The <switchboard> element must contain one or more <mapping> elements or SocketSwitchboard will not do anything.
Each <mapping> element consists of exactly two elements, <inbound> and <outbound>, that specify how to handle client connections and how to create connections to another server for the client.
The <inbound> element must contain a <port> element specifying the local port on which to listen for connections.
Similarly, the <outbound> element must contain a <host> element and a <port> element specifying the host and port to route all network activity to for this mapping.
With just these few elements, the SocketSwitchboard can be configured to perform as a flexible network traffic forwarder. However, additional elements can be used to further control the behavior of the application.
SSL:
The optional <ssl> element can be placed within the <inbound> element to specify that the server require SSL connections on that port. Also, the <ssl> element, when used within the <inbound> element, may contain the optional <need-client-auth> element. This will cause SocketSwitchboard to only accept connections from clients for which the application has trusted SSL certificates in its truststore.
The optional <ssl> element can also be placed within the <outbound> element to specify that SocketSwitchboard create SSL connections to the remote host. In this case, the application must have a trusted SSL certificate for the remote host in its truststore or it will not be able to connect to the remote host.
CONNECTION CONSTRAINTS:
SocketSwitchboard allows the administrator to setup complex boolean rules to control which client connections will be allowed by placing a <constraint-set> element within the <inbound> element.
The <constraint-set> element can contain one or more <constraint> elements and one or more <constraint-option> elements. However, the <constraint> elements must all appear first. A *CONSTRAINT SET* signifies that *ALL* constraints and constraint options within it must be satisfied or the client connection will be refused (i.e., a boolean AND).
The <constraint-option> element can contain one or more <constraint> elements and one or more <constraint-set> elements. However, the <constraint> elements must all appear first. A *CONSTRAINT OPTION* signifies that *ANY* constraint or constraint set within it must be satisfied or the client connection will be refused (i.e., a boolean OR).
Constraint sets and constraint options can be nested within each other to create complex rules, and the <constraint> elements dictate the specific criteria that the incoming connnections must meet.
SocketSwitchboard includes constraints that allow the restriction of connections based on IP address range, IP address pattern match, hostname pattern match, time of day, and day of week.
Each <constraint> element must contain a <classname> element that specifies where the constraint class can be found. Each constraint may also require that one or more <parameter> elements be placed within the <constraint> element.
A <parameter> element consists of one <name> element and one <value> element.
IP ADDRESS RANGE:
A constraint that allows connections only if the remote IP address falls within the configured range. The minimum and maximum endpoints are inclusive. Note, the minimum IP must be less than the maximum IP.
Specify com.ihafer.switchboard.constraints.IpRange for the <classname> element.
This constraint requires the following parameters:
NAME VALUES
min [0-255].[0-255].[0-255].[0-255]
e.g., 0.0.0.0
max [0-255].[0-255].[0-255].[0-255]
e.g., 255.255.255.255
IP ADDRESS PATTERN MATCH:
A constraint that allows connections only if the remote IP address matches the configured pattern, which may use wildcards. The character ? may be used as a wildcard to match any single numeric character. The character * may be used as a wildcard to match zero or more numeric characters.
Specify com.ihafer.switchboard.constraints.IpMatch for the <classname> element.
This constraint requires the following parameter:
NAME VALUES
pattern IP address match pattern.
e.g., 192.168.0.1
e.g., 192.168.?.*
HOSTNAME PATTERN MATCH:
A constraint that allows connections only if the remote hostname matches the configured pattern, which may use wildcards and is not case-sensitive. The character ? may be used as a wildcard to match any single character. The character * may be used as a wildcard to match zero or more characters. Note, be careful using * wildcards, as they will match any number of characters, including periods.
Specify com.ihafer.switchboard.constraints.HostnameMatch for the <classname> element.
This constraint requires the following parameter:
NAME VALUES
pattern Hostname match pattern.
e.g., domain.com
e.g., domain.???
e.g., *domain.com
TIME OF DAY:
A constraint that allows connections only if the current time of day falls within the configured range. The time endpoints are inclusive and are specified as HH:MM:SS in 24-hour time format. Note, the minimum time must be less than the maximum time.
Specify com.ihafer.switchboard.constraints.TimeRange for the <classname> element.
This constraint requires the following parameters:
NAME VALUES
min HH:MM:SS
e.g., 00:00:00
max HH:MM:SS
e.g., 23:59:59
DAY OF WEEK:
A constraint that allows connections only if the current day of the week falls within the configured range. The endpoints are inclusive and are specified as the first three characters of the day of the week. Parameters are not case-sensitive and can wrap around the end of the week (e.g., Fri-Mon).
Specify com.ihafer.switchboard.constraints.DayRange for the <classname> element.
This constraint requires the following parameters:
NAME VALUES
start Mon|Tue|Wed|Thu|Fri|Sat|Sun
stop Mon|Tue|Wed|Thu|Fri|Sat|Sun
LOG FILES
By default, SocketSwitchboard logs audit information about connection attempts to the $SB_HOME/logs directory. The log files roll over daily to provide a hostorical record and can be deleted at will. However, the $SB_HOME/logs directory cannot be deleted or the application will raise an error.
SocketSwitchboard uses Commons-Logging with Log4j. Users with knowledge of how to use these packages can modify their configuration files in the root directory of the Switchboard.jar file.
CREATING NEW CONSTRAINTS
The constraints framework allows Java developers to create new constraint classes that implement the com.ihafer.switchboard.IConstraint interface. The new constraint can then be specified in the configuration file by referencing its full classname in the <classname> element of a constraint. Any <parameter> elements specified in the configuration will be made available to the class as a Map, along with the Socket on which the client connection is attempted. See the javadocs for more information.
SOURCE CODE AND JAVADOCS
The Switchboard.jar file contains two directories named src/ and docs/ that contain the application source code and javadocs, respectively.
SAMPLE SWITCHBOARD.XML FILE
<?xml version="1.0" encoding="ISO-8859-1"?>
<switchboard xmlns="http://www.ihafer.com/xml/switchboard">
<!--
This mapping forwards all traffic on local port 80 to local port 8080.
-->
<!--
<mapping>
<inbound>
<port>80</port>
</inbound>
<outbound>
<host>localhost</host>
<port>8080</port>
</outbound>
</mapping>
-->
<!--
This mapping forwards all traffic on local port 80 to port 80 on another
LAN host.
-->
<!--
<mapping>
<inbound>
<port>80</port>
</inbound>
<outbound>
<host>192.168.0.100</host>
<port>80</port>
</outbound>
</mapping>
-->
<!--
This mapping forwards all traffic on local port 80 to port 80 on a remote
host.
-->
<!--
<mapping>
<inbound>
<port>80</port>
</inbound>
<outbound>
<host>www.yahoo.com</host>
<port>80</port>
</outbound>
</mapping>
-->
<!--
This mapping forwards all SSL traffic on local port 443 to local port 80.
-->
<!--
<mapping>
<inbound>
<port>443</port>
<ssl/>
</inbound>
<outbound>
<host>localhost</host>
<port>80</port>
</outbound>
</mapping>
-->
<!--
This mapping forwards all SSL traffic on local port 443 to local port 80 and
only allows trusted SSL clients client.
-->
<!--
<mapping>
<inbound>
<port>443</port>
<ssl>
<need-client-auth/>
</ssl>
</inbound>
<outbound>
<host>localhost</host>
<port>80</port>
</outbound>
</mapping>
-->
<!--
This mapping forwards all traffic on local port 80 to local port 443 using SSL.
-->
<!--
<mapping>
<inbound>
<port>80</port>
</inbound>
<outbound>
<host>localhost</host>
<port>443</port>
<ssl/>
</outbound>
</mapping>
-->
<!--
This mapping forwards all traffic on local port 80 to local port 8080 and only
allows connections from localhost.
-->
<!--
<mapping>
<inbound>
<port>80</port>
<constraint-set>
<constraint>
<classname>com.ihafer.switchboard.constraints.HostnameMatch</classname>
<parameter>
<name>pattern</name>
<value>localhost</value>
</parameter>
</constraint>
</constraint-set>
</inbound>
<outbound>
<host>localhost</host>
<port>8080</port>
</outbound>
</mapping>
-->
<!--
This mapping forwards all traffic on local port 80 to local port 8080 and uses
a complex constraint rule: 1) users on any mydomain.com hosts can connect
anytime; 2) other hosts can only connect Mon-Fri between 9AM and 6PM.
-->
<!--
<mapping>
<inbound>
<port>80</port>
<constraint-set>
<constraint-option>
<constraint>
<classname>com.ihafer.switchboard.constraints.HostnameMatch</classname>
<parameter>
<name>pattern</name>
<value>*mydomain.com</value>
</parameter>
</constraint>
<constraint-set>
<constraint>
<classname>com.ihafer.switchboard.constraints.DayRange</classname>
<parameter>
<name>start</name>
<value>Mon</value>
</parameter>
<parameter>
<name>stop</name>
<value>Fri</value>
</parameter>
</constraint>
<constraint>
<classname>com.ihafer.switchboard.constraints.TimeRange</classname>
<parameter>
<name>min</name>
<value>09:00:00</value>
</parameter>
<parameter>
<name>max</name>
<value>18:00:00</value>
</parameter>
</constraint>
</constraint-set>
</constraint-option>
</constraint-set>
</inbound>
<outbound>
<host>localhost</host>
<port>8080</port>
</outbound>
</mapping>
-->
</switchboard>