C H A P T E R 9 - Porting the Networking Subsystem

C H A P T E R 9

Porting the Networking Subsystem

This chapter describes how to port the networking subsystem of the Java Wireless Client software. The networking subsystem consists of the set of classes that implement the networking protocols. Applications use these protocols using the Generic Connection Framework (GCF), and each protocol provides a class that implements the javax.microedition.io.Connection interface.

Note - Protocols required by the any of the optional packages are discussed in the appendix or chapter that describes how to port the optional package.

TABLE 9-1 lists the protocols that the networking subsystem provides to Java Wireless Client software.

TABLE 9-1 Networking Subsystem Protocols
Protocol	Description
`SocketConnection`	Client connection to a TCP server.
`ServerSocketConnection`	Server for TCP clients.
`DatagramConnection`	Interface for sending and receiving UDP datagrams.
`SecureSocketConnection`	Socket connection with SSL 3.0. Java Wireless Client software supports RSA RC4 128 and 40 bit cipher suites and does not support client authentication.
`HttpConnection`	Socket connection with the HTTP 1.1 protocol. The connection supports persistent connections, chunked data, and tunneling.
`HttpsConnection`	HTTP connection that uses an SSL connection instead of an unsecured socket connection.

The networking subsystem depends heavily on PCSL for its underlying networking implementations, and much of the networking subsystem is written in the Java programming language. Once PCSL is ported, most of the networking subsystem can be brought up quickly. See Chapter 8 for details about porting PCSL.

The push subsystem has some interdependencies with the networking subsystem. Networking protocols for which push functionality is provided must be supported in the networking subsystem. For example, if push support is provided for server sockets, then server socket support must also be provided in the networking subsystem. For each protocol with push support, the push registry provides functions that hand off network connections and any cached data to the networking subsystem. The networking subsystem uses the functions when the "pushed" MIDlet opens a connection. See Chapter 20 for more information about the push subsystem.

Generic Connection Framework and Protocol Implementations

The networking subsystem is built on CLDC's GCF. See the documentation for the javax.microedition.io.Connector class in the CLDC specification. The connection that corresponds to the scheme from the URL passed to the Connector.open() method is implemented by instantiating a class named Protocol that resides in the Java programming language package com.sun.midp.io.j2me.scheme. For example, if an application calls Connector.open("http://www.example.com"), the scheme is http. The entry point for the implementation of this protocol is found in the class com.sun.midp.io.j2me.http.Protocol.

The set of Java classes in this area use the common features listed in TABLE 9-2.

TABLE 9-2 Common Features Used by Java Classes
Feature	Description
`StreamConnection` interface	All of the necessary functionality, except for the native interface to a native resource. The interface covers the many subtle, easily overlooked details in implementing the interface.
`ConnectionBaseInterface` interface	All dynamically loaded protocols must implement this interface. The implementation supplies common functionality. For example, it disconnects only when the connection and all streams are closed, and throws an exception when a method is called after the connection is closed.
Common buffering requirements	Because some protocols have common buffering requirements, the networking subsystem provides classes with input and output buffering. For native resources that do not allow peeking ahead in the buffer, the subsystem provides an implementation that reads ahead into the input buffer.
Network Initialization	On some platforms, network protocols require native initialization before the network can be used. For these protocols, the networking subsystem provides a class in the `com.sun.midp.io` package that performs the native method call to initialize the network.

Some of the networking protocols are written entirely in the Java programming language and depend only upon other networking protocols. These protocols do not require any explicit porting and are simply configured into or out of the system. Other networking protocols have native interfaces and might require additional porting effort. This point is covered in the following steps for each networking protocol.

Porting the Networking Subsystem

The following high-level steps represent a reasonable path to port the networking subsystem. More detailed information is provided in the following sections.

1. Port PCSL.

PCSL has native-level support for basic networking utilities (for example, host name lookup), sockets, and datagrams. PCSL porting is covered in Chapter 8. Implementing basic networking utilities and sockets is required, but the datagram implementation is optional.

2. Port the Socket protocol.

The Java platform classes that implement the socket protocol have native interfaces that are implemented in by means of calls to PCSL. The Java programming language level socket protocol is in turn used by higher-level protocols such as HTTP and SSL.

3. Port the HTTP protocol.

The HTTP implementation is a pure Java programming language implementation (Java implementation) that relies only on the Java implementation of the socket protocol. Having TCP and HTTP available enables automated testing using the HTTP AutoTester. In addition, when the AMS is ported (see Chapter 19), the Graphical Installer uses HTTP to support OTA installation and manual testing.

Note - HTTP is the only protocol required to be supported in MIDP 2.0. Other protocols are optional. The following steps can therefore be performed in any order, or not at all, depending upon which protocols you decide must be supported in your port. The exception is that HTTPS depends upon SSL having first been implemented.

4. (Optional) Port SSL protocol.

The critical cryptographic functions of SSL are implemented in native code. The source code to the native implementation and the corresponding porting interface are optionally available. The protocol functions of SSL (for example, the handshake) are implemented in the Java programming language on top of the socket protocol implementation.

5. (Optional) Port the HTTPS protocol.

The HTTPS implementation is written in the Java programming language directly on top of the HTTP and SSL implementations. If these protocols are implemented, the HTTPS implementation can be brought up immediately.

6. Port the UDP Datagram protocol.

The Java classes that implement the datagram protocol have native interfaces that are implemented by means of calls to PCSL. Port the PCSL datagram implementation now if you have not done so already. The Java implementation of datagrams can then be integrated.

7. (Optional) Port the server socket protocol.

The server socket implementation has its own native interface that must be ported. In addition, the server socket implementation also requires basic networking utilities from PCSL.

General Porting Considerations

Some of the Java implementations of the networking protocols use buffering to increase performance. This consumes about 4 kilobytes of Java platform heap memory per connection.

Some of the protocol implementations depend upon each other. This implementation dependency is reflected in the APIs exposed to applications. For example, the HTTP implementation uses the socket protocol implementation. Because the socket protocol implementation is present, this implies that the socket: protocol is visible to the application through the GCF. HTTP support is required, but if socket support is not provided to applications, additional work is necessary. Access to the socket: protocol must be disabled by modifying the javax.microedition.io.Connector class. This class is provided as part of the CLDC HotSpot Implementation source bundle. Similar dependencies exist between SSL and the socket protocol, and between HTTPS and SSL.

Porting Considerations for HTTP

This section discusses porting issues that might arise with the HTTP protocol involving HTTP proxies and persistent connections.

HTTP Requests Using Proxies

Java Wireless Client software's HTTP implementation can make requests through a proxy server. To have the device emulator use a proxy server, set the internal system property com.sun.midp.io.http.proxy. See the Build Guide for more information.

The HTTP implementation requires that HTTP proxy servers support the generic tunneling mechanism for TCP-based protocols through web proxy servers. Tunneling is used instead of the normal HTTP proxy because many proxies cannot handle certain advanced HTTP 1.1 features correctly and because tunneling is already implemented for HTTPS.

If you modify the HTTP porting-ready implementation to use a WAP gateway, the WAP gateway replaces the proxy access. To do this, replace references to the generic HTTP proxy with calls to a native WSP stack.

HTTP1.1 Persistent Connections

The MIDP 2.0 Specification supports HTTP 1.1 persistent connections.

Note - Do not change the porting-ready implementation to only include HTTP 1.0 connection behavior.

Persistent connections have many advantages, but on small devices with limited resources they can be a problem if they are not closed properly. Java Wireless Client software solves this problem by using the value of an internal system property to set the time that a connection can remain open and unused. After the time limit, Java Wireless Client software closes the connection and removes it from the connection pool.

The default value of the internal system property com.sun.midp.io.http.persistent_connection_linger_time is 60,000 milliseconds. Change it for your device, if necessary. See the Build Guide for information about configuring internal system properties.

Porting Considerations for HTTPS

This section discusses porting issues that might arise with the HTTPS protocol involving HTTPS proxies and persistent connections.

Porting HTTPS

Java Wireless Client software's implementation of HTTPS extends its HTTP implementation. It uses SSL to make secure connections and uses the sample web public key store for CA certificates. Java Wireless Client software's HTTPS implementation is compliant with HTTP over TLS as specified in RFC 2818, except that it uses SSL 3.0 instead of TLS 1.0 (SSL 3.1).

Note - Java Wireless Client software's implementation of HTTPS does not expose an API to control the handshake listener. Exposing such an API allows certain certificate errors to be overridden by higher level applications. It must not be possible for an end user to override policy decisions about expired certificates. For security reasons, your port must not expose this API either. If you do not export this API, it is compliant with the MIDP 2.0 Specification.

Using the Java Wireless Client Software SSL Implementations

The Java Wireless Client software SSL implementation is provided for reference purposes and is not intended for production use in devices. However, if the reference SSL reference implementation is used in a device you must provide secure random data in the com.sun.crypto.PRand class.

Java Wireless Client software does not provide secure random data. Its seed is based on time, which is predictable. You must change it so that it obtains an initial 128 bytes (not bits) of unpredictable data from your native platform. Use RFC 1750 Randomness Recommendations for Security as a guide for collecting the initial data. See http://www.ietf.org/rfc/rfc1750.txt.

Porting Considerations for Server Socket

The server socket protocol has its own native interface. To port the server socket implementation, you must provide implementations of the functions defined in the header file serverSocketProtocol.h. The server socket implementation also relies on the basic networking utilities of PCSL, so PCSL must be present as well. See the Native API Reference for further details.

References

The following references are helpful when porting the networking subsystem:

RFC 1750. Randomness Recommendations for Security - http://www.ietf.org/rfc/rfc1750.txt

RFC 2246. The TLS Protocol - http://www.ietf.org/rfc/rfc2246.txt

RFC 2817. Upgrading to TLS Within HTTP/1.1. This RFC describes HTTP tunneling, among other topics - http://www.ietf.org/rfc/rfc2817.txt

RFC 2818. HTTP over TLS - http://www.ietf.org/rfc/rfc2818.txt

WAP TLS Profile and Tunneling Specification. WAP-219-TLS-20010411-a. Wireless Application Protocol Forum Ltd., 2001 -
http://www.openmobilealliance.org

SSL 3.0 Draft Specification, November 1996 -
http://wp.netscape.com/eng/ssl3/.

Luotonen, A., Tunneling TCP Based Protocols Through Web Proxy Servers - Also see the (expired) Internet draft draft-luotonen-web-proxy-tunneling-01.txt, published in Luotonen, A., Web Proxy Servers. Prentice-Hall, 1977.