User Guide

Introduction

Since Release 0.4, the JSocket Wrench library has become far more straightforward to use. The introduction of the IProtocolMessage and IServiceMessage interfaces and the resulting simplification of the JSWDatagramSocket class mean that it is now scarcely more difficult to send and receive complicated protocol messages from raw sockets than it is to use the standard JDK Socket and DatagramSocket classes.

In order to use the library, the user must:

• Load the native library. (In fact, this step is performed implicitly during the next step).
• Select the IP protocol to be used.
• Ensure that the necessary operating system permissions have been granted.
• Create a JSWDatagramSocket instance.
• Send or receive message classes that implement the IProtocolMessage or IServiceMessage interfaces.

To load the native library

The JSocket Wrench library contains a shared library of native code written in C++. Generally in Java, a shared library is loaded through the System.loadLibrary() function call. However, in the JSocketWrench library, the static initializer of the SocketWrenchSession class will call System.loadLibrary() on behalf of the user and, furthermore, will call any functions within the shared library necessary to initiate the socket library on the current platform. (No such calls are necessary on Linux but the Winsock 2 library on Windows has to be initiated and closed down explicitly). All the user has to do is to ensure that the shared library, which will carry the name libcom_act365_net_Sockets.so on Linux or com_act365_net_Sockets.dll on Windows, is placed on a path from which it is available to be loaded, i.e. the library should be placed on the directory from which the project is to be executed (the CLASSPATH) or on one of the standard directories from which shared libraries are loaded on the current platform, i.e. the directories listed on $LD_LIBRARY_PATH (Linux) or %PATH% (Windows).

The rules of Java dictate that when a class has been defined with a static initializer, the code will be executed prior to the first use of the class. So the first (and only) call to SocketWrenchSession.setProtocol() (the function is described in the next section) will implicitly load the native library. The user does not have to create an instance of the SocketWrenchSession class in order to complete the task.

To select the protocol

The rules of Java dictate that it is only possible to call the JDK functions Socket.setSocketImplFactory(), ServerSocket.setSocketFactory() or DatagramSocket.setDatagramSocketImplFactory() once within an application. Since the function SocketWrenchSession.setProtocol() typically calls each of these three functions, it follows that it is only possible to call SocketWrenchSession.setProtocol() once within an application, i.e. that any app is restricted to the use of a single IP protocol. This is not as stringent a limitation as it might seem at first given that it is possible to send any type of message from a raw socket. For instance, the traceroute application in UDP mode will send UDP messages and receive ICMP messages. The socket type is set to ICMP (it should always be set to the protocol that the app expects to receive), which necessitates the use of raw sockets, but manipulation of the header allows UDP messages to be sent from the socket.

There are two forms of the SocketWrenchSession.setProtocol() function. One accepts an enumeration argument, such as SocketConstants.JSWPROTO_HDRICMP, while the other accepts a string argument, such as "HdrICMP". The various available protocols are described fully on a separate page.

Permissions

Any call to create a raw socket in the JSocketWrench library is translated into the equivalent C runtime library call for the current platform, so it follows that the user will have to have the necessary operating system permissions for the call to succeed. In short, that means the user will have to have root privileges on Linux or Administrator privileges on Win 32. Default operating system installations on home PCs should grant these privileges.

The JSWDatagramSocket class

JSWDatagramSocket is a subclass of DatagramSocket. In addition to the datagram sockets supported by DatagramSocket, JSWDatagramSocket will support any socket type supported by the underlying operating system, including raw sockets. The class makes it straightforward to send or receive message classes that implement the IProtocolMessage or IServiceMessage interfaces.

Since the JSWDatagram class potentially has to construct IP or protocol-specific headers, it has several properties, some optional, which aren't encountered in the DatagramSocket class:

• IP-specific properties: Properties that directly relate to values that appear in the IP header.
• Source address: In principle, it should possible to obtain the local address of a host through the Java function InetAddress.getLocalHost(). However, the method will often return a local address, such as 127.0.0.1 instead of the expected network address. In order to work around this problem, the JSocket Wrench library allows the user to specify the network address of the socket. When the IP_HDRINCL option has been selected (i.e. when the chosen protocol name contains the string Hdr), the specified source address will be written directly into the IP header of any sent message. Regardless of whether this option has been selected, any received message with a destination address that differs from the specified source address will be discarded.
• Type of service: Relates directly to the value that appears in the IP header. It only has to be specified if the IP_HDRINCL option has been selected.
• Time to live: Relates directly to the value that appears in the IP header. It only has to be specified if the IP_HDRINCL option has been selected. Of course, it is this value that is amended by the traceroute application.
• Protocol-specific properties: Properties that directly relate to values that appear in the protocol-specific header.
• Source port: The source port is used to filter out received messages intended for other recipients in the case that a raw socket has been selected in conjunction with a protocol, such as UDP or TCP, that uses port numbers.
• Implementation-specific properties: The following properties don't relate directly to any values that appear in the IP or protocol headers.
• Checksum test: When set to true (the default), the IP and protocol-specific checksums of incoming messages will be tested. Possible reasons to avoid the checksum tests are to increase performance or to avoid possible problems where the sending host lies behind a NAT router tht can't adjust the protocol-specific checksum to compensate for the change in the source address from the LAN value to the WAN value (a problem sometimes seen with TCP/J).
• Buffer sizes: The sizes of the send- and receive-buffers are controlled by the user. The default sizes in Release 0.4 are 1K for both buffers, almost certainly too small.
• Debug stream: The debug stream should be set to a subclass of java.io.PrintStream in order to obtain a dump of all sent and received messages.

The IProtocolMessage and IServiceMessage interfaces

The user should create a new class that implements the IProtocolMessage interface in order to support a new protocol type. See the ICMPMessage, UDPMessage or TCPMessage classes for examples.

The user should create a new class that implements the IServiceMessage interface in order to support a new service type. See the DNSMessage class for an example.