Chapter 14 Using SSL and Proxy Connections in Java Clients

Connecting through proxy servers

Proxy servers are typically used to constrain and secure connections from an organization's computers to sites that require connecting across the Internet. To enhance security, some network configurations require all Internet connections to go through a proxy server, including IIOP connections to a Jaguar server.

Jaguar supports two types of proxy servers for Java clients, Web proxies and reverse proxies.

Using Web proxies

Web proxies typically act as a gateway for outgoing connections from a group of workstations. Web proxies can be used to enhance network security, for example, a proxy may constrain which servers clients can connect to and which protocols may be used, and log outgoing connections. Web proxies may also be used to improve network performance, by caching the results of frequently executed Web requests. Web proxies are also referred to as HTTP-connect-based proxies. Figure 14-1 illustrates how clients connect to servers through a Web proxy:

Figure 14-1: Connecting through a Web proxy

Clients connect to Jaguar through a Web proxy as follows:

Using the HTTP protocol, the client connects to the Web proxy, embedding the destination server address inside a specially formatted HTTP connect request.
The Web proxy connects over the Internet to the host and port indicated in the initial HTTP connect request.
Subsequent traffic is forwarded unchanged between the client and server until the connection is closed.

Java applets can use the built-in proxy configuration provided by Web browsers such as Netscape Navigator. See your Web browser's documentation for information on configuring proxy addresses. For applets running in a Web browser, HTTP and HTTPS tunnelled IIOP connections will automatically use the browser's proxy connection settings. HTTP-tunnelled IIOP connections go through the browser's configured HTTP proxy. HTTPS-tunnelled IIOP connections go through the browser's configured secure proxy.

Java applications must specify the Web proxy address by setting the com.sybase.CORBA.WebProxyPort and com.sybase.CORBA.WebProxyHost properties described below.

Properties that affect Web proxy use

Table 14-2 describes the Java client properties that apply to Java applets or applications that connect through a Web proxy. You must set these properties in addition to any properties that you would set to connect directly to the Jaguar server.

Table 14-2: Properties that affect Web proxy use
CORBA property	EJB property	Specifies
com.sybase.CORBA. WebProxyHost	com.sybase.ejb. WebProxyHost	Specifies the host name or IP address of the Web proxy server. Applies to Java applications only. Java applets running in a Web browser will use the proxy address specified by the browser's proxy configuration. In Java applications, there is no default for this property, and you must specify both the host name and port number properties.
com.sybase.CORBA. WebProxyPort	com.sybase.ejb. WebProxyPort	Specifies the port number at which the Web proxy server accepts connections. Applies to Java applications only. Java applets running in a Web browser will use the proxy address specified by the browser's proxy configuration. In Java applications, there is no default for this property, and you must specify both the host name and port properties.
com.sybase.CORBA. http	com.sybase.ejb. http	By default, the client ORB attempts to open IIOP connections, then attempts an HTTP tunnelled connection if plain IIOP fails. Since Web proxy connections require HTTP tunnelling, set this to true to eliminate the performance overhead of trying plain IIOP connections before trying HTTP-tunnelled IIOP.
com.sybase.CORBA. HttpExtraHeader	com.sybase.ejb. HttpExtraHeader	An optional setting to specify what extra information is appended to the header of each HTTP packet sent to the Web proxy server. There is no need to set this property unless your HTTP proxy server has special protocol requirements. By default, the following line is appended to each packet: User-agent: Jaguar/major.minor where major and minor are the major and minor version numbers of your Jaguar client software, respectively. You can set this property to specify text to be included at the end of each HTTP header. If multiple lines are included in the setting, they must be separated by carriage return and line feed characters. If the setting does not include a "User-agent: " line, then the default setting above is included in the HTTP header.

Using reverse proxies

Reverse proxies typically act as a gateway for incoming connections to an organization's network servers, preventing direct connections from clients outside the firewall to servers inside the firewall. The reverse proxy can enhance security, by restricting protocols and logging connection activity. Reverse proxies may also act as caches to respond to common requests. In some cases, multiple reverse proxies may be deployed to cache results from one server, as a form of load balancing. Figure 14-2 shows how clients connect through a reverse proxy.

Figure 14-2: Connecting through a reverse proxy

Clients connect to Jaguar through a reverse proxy as follows:

The client connects to the reverse proxy, and sends each IIOP packet tunnelled inside an HTTP or HTTPS packet. The destination server address is encoded in the HTTP packet header as:
```
GET /host/port/HIOP/1.0/...
```
Where host is the target Jaguar server host name, and port is the target Jaguar server port number.
The reverse proxy uses its URL mapping configuration (shown as a database in the figure) to determine the destination server address.
The reverse proxy opens a connection to the destination server, or reuses an existing connection, and forwards the request to the server, then forwards the response to the client.

Reverse-proxy configuration

For use with Jaguar, you must configure your reverse proxy server's URL mapping table to recognize the Jaguar server addresses embedded in the HTTP requests sent by the client runtime. For each Jaguar server that clients may connect to through the server, configure a mapping for the following URL prefix:

GET /host/port/HIOP/1.0/

Where host is the target Jaguar listener host name, and port is the target Jaguar listener port number. For each Jaguar server that you deploy behind the reverse proxy, add a mapping for each IIOP, IIOPS, and Message Service listener address. If you deploy a cluster of Jaguar servers behind a reverse proxy, add mappings for each server in the cluster.

Properties that affect reverse proxy use

To connect through a reverse-proxy server, you can set the properties in Table 14-3. You must set these properties in addition to any properties that you would set to connect directly to the Jaguar server.

Table 14-3: Properties that affect reverse proxy use
CORBA property	EJB property	To indicate
com.sybase.CORBA. ProxyHost	com.sybase.ejb. ProxyHost	Specifies the machine name or the IP address of the reverse-proxy server.
com.sybase.CORBA. ProxyPort	com.sybase.ejb. ProxyPort	Specifies the port number of the reverse-proxy server, typically 80 for HTTP-tunnelled connections or 443 for SSL (HTTPS-tunnelled) connections.
com.sybase.CORBA. http	com.sybase.ejb. http	Set this property to true if the reverse-proxy server requires HTTP-tunneled connections. If you do not set this property, connections still go through, but only after the client ORB first tries to open an IIOP connection. Setting the property eliminates the overhead that is incurred by trying plain IIOP each time a connection is made.
com.sybase.CORBA. forceSSL	com.sybase.ejb. forceSSL	In Java applets, set this property to true if the connection to the reverse proxy must use SSL (HTTPS) tunnelling, but the connection from the proxy to the Jaguar server does not use SSL tunnelling.
com.sybase.CORBA. qop	com.sybase.ejb. qop	In Java applications that connect to a proxy using SSL (HTTPS) tunnelling, set the QOP to a security level that matches the level supported by the reverse-proxy server. For instructions on setting this property, see "SSL properties". If the connection to the proxy server requires SSL, but the connection from the proxy does not, do not set the QOP; instead, set the com.sybase.CORBA.forceSSL property to true. Do not set QOP in Java applets that use SSL. Instead, code the applet to connect to a listener that supports the required security level. See "Using SSL in Java applets" for more information.
com.sybase.CORBA. autoProxy	com.sybase.ejb. autoProxy	In Java applets, set this property to true to enable connections to a reverse-proxy server. You must also configure your applet to download through the reverse-proxy server itself. The default is false. This property is ignored if the client is not a Java applet, or has not initialized the Java ORB with the ORB.init method that takes an Applet parameter. When automatic proxy is enabled, the ORB uses the applet's download address as the reverse-proxy server address. If the port number is 443, SSL (HTTPS tunnelling) is used; otherwise, HTTP tunnelling is used.