Configuring user programs

This chapter shows how to configure the user programs (clients and servers) to use firewalls and GateKeeper. The settings are configured through the client and server properties. See “Appendix GateKeeper properties” for information on how to set the properties.

Using objects behind firewalls

You may need to configure both programming and runtime environments so that objects can work behind firewalls. Configuring firewall policies for a specific Portable Object Adapter (POA) must be done programmatically. Setting the same firewall policies globally for all POAs, however, can be accomplished using a single property setting and does not require source code modifications.

Programming a single POA

To allow a server to traverse a firewall when you want to configure firewall policies for a specific POA, you must specify a firewall policy on the POA where the server is activated. In particular, the following code must be added to the server. (The following examples use the Bank example as a basis.)

To configure a single POA programmatically:

1	Create the firewall policy:

Java

org.omg.CORBA.Any fw_policy_value = orb.create_any();
com.inprise.vbroker.firewall.FirewallPolicyValueHelper.insert(
fw_policy_value, com.inprise.vbroker.firewall.EXPORT.value);
org.omg.CORBA.Policy firewall_policy = orb.create_policy(
com.inprise.vbroker.firewall.FIREWALL_POLICY_TYPE.value, fw_policy_value);
org.omg.CORBA.Policy[] policies = {
firewall_policy,
rootPOA.create_lifespan_policy(LifespanPolicyValue.PERSISTENT)
};

C++

CORBA::PolicyList policies;
policies.length(2);
policies[(CORBA::ULong)0] = rootPOA->create_lifespan_policy
(PortableServer::PERSISTENT);
CORBA::Any policy_value;
policy_value <<= Firewall::EXPORT;
CORBA::Policy_ptr fpolicy= orb->create_policy
(Firewall::FIREWALL_POLICY_TYPE, policy_value);
policies[(CORBA::ULong)1] = fpolicy;

2	Apply the policy to the POA on which the server will be activated:

Java

POA bankPOA = rootPOA.create_POA(”bank_agent_poa”, rootPOA.the_POAManager(),
policies);

C++

PortableServer::POA_var bankPOA = rootPOA->create_POA(”bank_agent_poa”,
poa_manager, policies);

Only the root POA takes the default policy, so it can be used to activate any server that must be accessed behind a firewall. You must also create another POA to activate the Account server. Since the Account server should not be bound by clients directly, you should create the POA as a transient POA:

Java

policies = new org.omg.CORBA.Policy[] {
firewall_policy,
rootPOA.create_lifespan_policy(LifespanPolicyValue.TRANSIENT)
};

POA accountPOA = rootPOA.create_POA(
”account_agent_poa”, rootPOA.the_POAManager(), policies);

C++

policies.length(2);
policies[(CORBA::ULong)0] = rootPOA->create_lifespan_policy
(PortableServer::TRANSIENT);
policies[(CORBA::ULong)1] = fpolicy;
PortableServer::POA_var accountPOA = rootPOA->create_POA(”account_agent_poa”,
poa_manager, policies);

Configuring the firewall policy for all POAs associated with a server

The following property lets you set the firewall policy for all POAs associated with a server:

-Dvbroker.orb.exportFirewallPath=true

If you specify the exportFirewallPath property, you do not need to add a firewall policy when creating a POA and therefore, you do not have to modify the source code.

Loading a firewall package at runtime

The clients and servers working with GateKeeper must load the firewall package and its properties at runtime when either a server or a client first initializes the ORB. This is when the following method is invoked.

Java

org.omg.CORBA.ORB.init(String[] args,java.util.Properties property);

C++

CORBA::ORB_ptr CORBA::ORB_init(int& argc, char *const *argv);

Java

The following property causes the firewall package to be loaded into the VisiBroker for Java ORB. This property is necessary for both the Java client and Java server in order to use a firewall and GateKeeper:

vbroker.orb.dynamicLibs=com.inprise.vbroker.firewall.Init

C++

The following property loads the required firewall library:

vbroker.orb.enableFirewall=true

This property defaults to false. Setting it to true is necessary for both the C++ client and C++ server when using a firewall with GateKeeper.

Configuring client properties

The method in which a client communicates with a server can be restricted. In particular, using policies and properties, you can specify whether:

•	Clients use a GateKeeper as a proxy for the real server

•	Clients communicate to servers through IIOP/SSL

•	Java: Clients communicate to servers through the HTTP-tunneled or HTTPS-tunneled channel

VisiBroker for Java supports an extension for IIOP that is tunneled through the HTTP protocol, called HIOP. In this mode, the ORB is able to tunnel only one request at a time. So if there are concurrent threads in the client making simultaneous requests, the ORB serializes those requests. Thus the requests coming into the server are also serialized. The number of simultaneous requests seen in the server will match the number of ORBs on the client, when client(s) use HTTP tunneling. This is a limitation of using HTTP tunneling on the client.

•	Messages pass between client and server connections through a GateKeeper entirely unexamined by the GateKeeper (called pass-through mode)

•	Clients choose the preferred transport from those available

The following sections show the various policies and their property settings for the clients. You can also use different combinations of these policies to determine how you want your client to communicate with the servers.

Specify always proxy on a client

The following property setting forces clients to use GateKeeper to proxy requests to servers.

Client's Properties:

vbroker.orb.alwaysProxy=true

The above property is optional. If you do not set it, the client uses the server's IOR to determine whether or not the object is hidden behind a server-side firewall and traverses the firewall accordingly. It is sometimes better to not set the above property, for example, when a client invokes both local objects inside the trusted network and remote objects hidden behind the firewall. Not setting the property enables the client to be more efficient by invoking the local objects directly without going through GateKeeper.

Client's Properties:

vbroker.orb.gatekeeper.ior=<IOR>

Clients can also specify the GateKeeper IOR using the above property. This method is helpful when a client is not able to locate GateKeeper through a Smart Agent.

Specify HTTP tunneling on a client

In VisiBroker for Java, the following property setting directs clients to communicate to servers in the HTTP-tunneled channel.

Client's Properties:

vbroker.orb.alwaysTunnel=true

The above setting causes the client applet or application to communicate to the GateKeeper through IIOP over HTTP and GateKeeper relays the request to the actual server object through IIOP. Replies from the server object to GateKeeper are communicated through IIOP. GateKeeper then forwards those replies to the client through IIOP over HTTP.

Applets should set vbroker.orb.alwaysTunnel if the client will be performing HTTP tunneling. Applet clients must set the property vbroker.orb.gatekeeper.ior to get the GateKeeper's IOR using URL naming or using a stringified IOR. In addition, the applet clients must not set the vbroker.locator.ior property.

Tunneling has certain limitations:

•

The HTTP protocol limits requests from being multiplexed on the same connection. The ORB is able to tunnel only one request at a time. So if there are concurrent threads in the client making simultaneous requests, the ORB serializes those requests. Thus, the requests coming into the server are also serialized.

The number of simultaneous requests seen in the server will match the number of ORBs on the client, when client(s) use HTTP tunneling. This is a limitation of using HTTP tunneling on the client.

The above setting causes the client applet or application to communicate to the GateKeeper through IIOP over HTTP and GateKeeper relays the request to the actual server object through IIOP. Replies from the server object to GateKeeper are communicated through IIOP. GateKeeper then forwards those replies to the client through IIOP over HTTP.

•	You cannot use callbacks with HTTP tunneling.

Caution

HTTP tunneling may not work consistently with various types of proxy servers because of differences that may exist in the implementation of HTTP proxy servers. See the VisiBroker GateKeeper FAQ included in your VisiBroker installation for more information. You can find this at:

<install_dir>\doc\faqs\VisiGateKeeperFAQ.html

Specify secure connections on a client

Client's Properties:

vbroker.orb.alwaysSecure=true

Clients talk to servers through IIOP/SSL or IIOP over HTTPS.

Client's Properties:

vbroker.orb.alwaysSecure=true
vbroker.orb.alwaysTunnel=true

Clients only talk to servers using IIOP over HTTPS.

Specify pass-through connections on a client

In this type of connection, GateKeeper does not terminate connections or interpret messages. This type of connection is useful when GateKeeper does not have SSL or the associated certificates to establish trust with the client. In such cases, the client and server negotiate their SSL connection without going through GateKeeper. Therefore, GateKeeper does not interpret messages passed between the client and the server.

Client's Properties:

vbroker.orb.proxyPassthru=true

GateKeeper's Properties:

vbroker.gatekeeper.enablePassthru=true

•

The vbroker.orb.proxyPassthru property sets the value of the ORB-level PROXY_MODE_POLICY property. If set to true, all objects using a proxy on the client will request pass-through connections. You can also set the PROXY_MODE_POLICY on specific objects so that only those particular objects request pass-through connections.

•	The vbroker.gatekeeper.enablePassthru property instructs GateKeeper to accept pass-through connections. This property is global to GateKeeper and affects GateKeeper's behavior only.

The vbroker.orb.proxyPassthru property tells the client to attempt to acquire pass-through connections from GateKeeper. GateKeeper, however, grants pass-through connections only if the vbroker.gatekeeper.enablePassthru property is set to true. See “Enabling pass-through connections” for other GateKeeper pass-through properties.

Disabling pass-through connections

If the vbroker.gatekeeper.enablePassthru property is set to false, GateKeeper does not allow pass-through connections to be established and clients can only obtain normal (non-pass-through) connections to the server. GateKeeper then examines the messages exchanged between the client and server for routing and binding purposes. The connection will fail if GateKeeper cannot provide an SSL authentication for an SSL message.

Specifying the client bid order

Client's Properties

The client's bid order specifies the relative importance for the various transports used to connect to the server. The transports that appear first will have higher precedence. The following property setting instructs the client to try the transport with the higher precedence first, whenever it is available, in the server's IOR. When a transport fails, the client will try the next available transport.

vbroker.orb.bidOrder=inprocess:liop:ssl:iiop:proxy:hiop:locator

In the above example, if the IOR contains both LIOP and IIOP profiles, the client will first try LIOP. Only if LIOP fails will it try IIOP.

Client's Properties

vbroker.orb.bids.critical=inprocess

The critical bid has the highest precedence no matter where it is specified in the bid order. If there are multiple critical bids, then their relative importance is determined by the bid order.

Specifying a client callback listener port (for VisiBroker 3.x style)

The following properties specify the listener port of the client for servers to establish VisiBroker 3.x style callback connection. The listener type is set to Callback-IIOP to differentiate it from a normal IIOP listener.

Client's Properties

vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<port>
vbroker.se.iiop_tp.scm.iiop_tp.listener.type=Callback-IIOP

Configuring server properties

Use server properties to construct the server's IOR that is used by clients to establish communication paths to the server.

Specifying the listener port of the server

The following sections describe the property settings used to specify a server's listener ports.

Random listener port

The following property has the default value of 0 (zero) which tells the system to pick a random port number when the server starts.

Server's Properties:

vbroker.se.iiop_tp.scm.iiop_tp.listener.port=0

Specific listener port

The following server property assigns the port on which the server will listen to IIOP messages from clients.

Server's Properties:

vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<port number>

Note

All clients on the same network can establish communication with a server using the port, as specified in the above example, directly. Messages sent by clients on different networks must be forwarded by the gateway or router. If a server allows connections by clients outside the subnet, the router or firewall should be configured to allow messages for the specified port. Conversely, if the server only allows connections from clients on the same subnet, the router or firewall should be configured to block messages for the specified port to prevent unauthorized access by foreign client objects.

Port translation (NAT)

If there is a port translation using Network Address Translation (NAT) from a fake port (also called the proxy port) to the server's real IIOP listener port, use the following property settings to publish the fake port in the server's IOR.

Server's Properties:

vbroker.se.iiop_tp.scm.iiop_tp.listener.port=<real_port>
vbroker.se.iiop_tp.scm.iiop_tp.listener.proxyPort=<fake_port>

The above settings tell the server to listen to the real port while clients send messages to the fake port. The default value of the proxyPort property is 0 (zero), which means no proxy port is used.

Note

A better method of specifying NAT is to use the TCP firewall properties described in the following section.

Disabling the IIOP port

Setting the following property will disable the server's IIOP listener port which forces the server to allow client requests on a specified port, such as a secured port like IIOP/SSL. The server will not allow IIOP messages on the published IIOP port.

Server's Properties:

vbroker.se.iiop_tp.scm.iiop_tp.listener.type=Disabled-IIOP

Specifying communication paths to the server

There may be multiple paths for a client's message to reach the server or different paths for messages originating from different clients to reach the same server. All these possible paths have to be configured in the server's properties so that the generated IOR has the information needed for clients to send messages to the server.

The following diagram illustrates two paths of firewall configurations and shows the communication paths to the server. Configuration X has a chain of two GateKeepers. Configuration Y has a single TCP firewall.

Figure 9

Communication paths to the server

To configure the server for the configurations shown in the diagram above, enter the following information in the server's properties file:

1	Declare all firewall paths:

vbroker.se.iiop_tp.firewallPaths=x,y

2	Identify the components for each path:

vbroker.firewall-path.x=a,b
vbroker.firewall-path.y=c

The following sections describe how to specify the firewall components.

Specify the component of a proxy server

The following example shows an IIOP proxy across a firewall.

Server's Property:

vbroker.firewall-path.x=a,b
vbroker.firewall.a.type=PROXY
vbroker.firewall.a.ior=http://www.inprise.com/GK/gatekeeper.ior
vbroker.firewall.b.type=PROXY
vbroker.firewall.b.ior=IOR:<GateKeeper's stringified ior>

The first property defines the firewall components found in the path named x. The second and fourth properties specify the types of the component named a and b, respectively. Both component types are defined as PROXY, which identifies GateKeeper as an IIOP proxy server to forward all IIOP requests. The third property defines the IOR of GateKeeper a using URL naming. The fifth property defines the IOR of GateKeeper b using a stringified IOR.

Specify the component of a TCP firewall with NAT

Clients' messages may have to cross one or more TCP firewalls in order to reach the server. The TCP firewall components have to be defined when NAT is performed in the TCP firewall. If the TCP firewall does not perform NAT, the component can be ignored.

The following example shows how to use a router or firewall to forward an IIOP message at the TCP level.

Server's Property:

vbroker.firewall-path.y=c
vbroker.firewall.c.type=TCP
vbroker.firewall.c.host=<fake_host>
vbroker.firewall.c.iiop_port=<IIOP fake port>
vbroker.firewall.c.ssl_port=<SSL fake port>
vbroker.firewall.c.hiop_port=<HTTP fake port>

The first property defines the firewall components found in the path named y. The second property defines the type of component named c as TCP, which provides a predefined port to forward all IIOP, SSL and IIOP over HTTP messages on a router or other network device. The third property defines the fake host of the server. The remaining last three properties define the fake port for the following message types: IIOP, SSL and HTTP.

The TCP firewall specified as component “c” in the above example is expected to perform host and port translation (NAT). The TCP firewall must be configured to translate the fake host to the server's real host and translate all the fake ports to the server's real listener ports.

Figure 10

TCP firewall with NAT