Gatekeeper Guide : Configuring GateKeeper and internetworking devices

Configuring GateKeeper and internetworking devices
This section describes how to configure GateKeeper and internetworking devices to allow communications between client objects and server objects across networks, starting with a explanation of where GateKeeper can be deployed.
Where to deploy GateKeeper
This section describes some basic principles used to identify the correct location of where to deploy GateKeeper.
Gather the following information:
Find a connecting path between the client and server; the path may cross multiple networks. To enable the client to contact the server, there must be a connecting path. Otherwise, the client cannot communicate with the server.
Client and server on the same network
When the client and server are located on the same network, the client can always contact the server directly. GateKeeper, however, may still be required in some circumstances; as in the two cases shown in the following examples. If GateKeeper is required, deploy GateKeeper on any host in the same network.
Case 1: Restricted client transport type
Transport types that a client can use to connect to a server can be restricted using the client side properties. GateKeeper is required when:
See “Configuring client properties” for details.
Case 2: Java sandbox security
Java sandbox security prevents unsigned Java applets from communicating with server objects located on servers other than the ones running on the host from which the applets were downloaded. In this case, GateKeeper is required as a gateway between the client and server to overcome the restriction of Java sandbox security.
Client and server on adjacent networks
When the client and server networks are adjacent to each other, the two networks are connected using an internetworking device such as a gateway or router. In some cases, a firewall may exist in either network or both networks. To simplify the description, we will consider the firewall as part of the internetworking device. The internetworking device is responsible for forwarding and routing the messages between the two networks. It can also block certain messages from crossing the networks; this is the role of a firewall. The transport types that a client uses to connect to a server can be restricted using the client's property.
GateKeeper is required when
See “Configuring client properties” for details.
Case 1: Java sandbox security
Java sandbox security prevents unsigned Java applets from communicating with server objects located on servers other than the ones running on the host from which the applets were downloaded. In this case, GateKeeper is required as a gateway between the client and server to overcome the restriction of Java sandbox security.
The following figure shows the client and server on adjacent networks.
Figure 1
Case 2: Restricted client transport type
For a client's message to reach the server, the internetworking device must forward the message from the client network to the server network. To find an appropriate location to deploy GateKeeper, determine the type of messages that the internetworking device can forward from the client network to the server network.
Deployment locations
The following cases illustrate all the possible locations to deploy GateKeeper for adjacent client and server networks.
Case 1: No GateKeeper required
GateKeeper is not required when the gateway can forward all client messages from the client network to the server network.
The following diagram shows a client which sends a message of type A to the server, which listens to type A messages. The gateway forwards the message (type A) to the server network. The server then receives the message (type A). Common examples of type A messages are IIOP and IIOP/SSL.
Figure 2
Case 2: GateKeeper in a server network
The following diagram shows a server that listens to messages of type S. The gateway blocks messages of type S but can forward messages of type A from the client network to the server network. If the client sends a message of type S to the server, it will be blocked by the gateway. Instead, the client has to send messages of type A so that the gateway can forward the message to the server network. GateKeeper is required in the server network to act as a proxy. The client communicates with GateKeeper using type A message and GateKeeper in turn communicates with the server using type S message. An example of type A and S is HTTP and IIOP, respectively. An example for this scenario is HTTP Tunneling mode, where IIOP packets are not allowed, but HTTP packets are allowed by the Gateway/Firewall.
Figure 3
Case 3: GateKeeper in a client network
The server listens to messages of type A but the client can only use transport type C to communicate with the server. The gateway blocks messages of type C but forwards messages of type A. A GateKeeper is needed in the client network. Client communicates with GateKeeper using transport type C and GateKeeper communicates with the server using transport type A. The gateway forwards the type A message from the GateKeeper to the server network. An example of transport type C and transport type A is HTTP and IIOP, respectively.
Figure 4
Case 4: GateKeeper in both networks
The gateway blocks both the messages (type C) sent by clients and the messages (type S) that the server can listen to. The gateway can forward another type of message (type A). Therefore, GateKeeper is required in both client and server networks. The client communicates with GK1 using message type C. GK1 communicates with GK2 using message type A, which can be forwarded by the GK2 which in turn communicates with the server using message type S. An example of message type C is HTTP, message type A is SSL and message type S is IIOP.
Figure 5
Case 5: GateKeeper in internetworking device (dual-homed)
Installing GateKeeper on a dual-homed host works in a similar way to deploying GateKeeper on the server network (case 2). The difference is that GateKeeper always listens to the exterior network for client messages. If a client located in the interior network needs to bind to a server using the same GateKeeper, the message must first be forwarded to the exterior network before it can reach the GateKeeper listener. Examples of type A and type S messages are HTTP and IIOP, respectively.
Figure 6
Multiple networks between client and server
In a more complex environment, multiple networks exist between the client and the server networks. Each pair of adjacent networks is connected using an internetworking device.
Figure 7
For illustration purposes, the client network will be numbered as N0. The network adjacent to the client network will be numbered as N1, the next adjacent network as N2 and so on until the server network. The server network will be numbered as Nn in the following discussions. Replace n with the actual number depending to the network configuration. Also, the internetworking device between network Nn-1 and Nn is numbered as GWn.
Clients can use different transport types to communicate with servers. Examples of transport types are IIOP, IIOP/SSL, HTTP and HTTPS. For each valid transport type, locate the furthest network that the client message can reach. The client located in network N0 sends a message to network N0. GW1 may or may not forward the message to network N1. The message can reach network N1 if GW1 can forward the message from N0 to N1. Subsequently, GW2 may or may not forward the message to network N2. Traverse the networks starting from the client network, then moving towards the server network. Mark the last network that the message can reach as Nc. In other words, GWc+1 cannot forward the message to the network Nc+1.
A server has one or more listener ports. Each port listens to one type of messages from clients. As an example, a server with an IIOP listener port and an SSL listener port will use the IIOP port to listen to IIOP messages and the SSL port to listen to IIOP over SSL messages. For each listener port, find the furthest network from the server to which a client message can reach the server. Mark the furthest network as Ns. In other words, a client located in network Ns is able to send a message to the server.
If callback for VisiBroker 3.x style is required, an additional condition is required for Nc and Ns. The callback message from the server (from network Nn) must be able to reach the network Ns. When GateKeeper is used, the client must be able to set up a callback communication channel to network Nc.
Case 1: Server can receive messages from the client network, s=0
Assume the server listens to transport type L. Messages of transport type L from the client network can reach the server network and subsequently the server.
If the client can send messages using transport type L, then GateKeeper is not required because client messages of type L can be forwarded to the server network. For example, the server listens to IIOP and the client can send IIOP messages. The client's IIOP messages can be forwarded to the server without being blocked by any firewalls, gateways or routers.
If the client cannot send messages using transport type L, deploy GateKeeper on a network within N0 and Nc to proxy client messages of other transport types (M) to transport type L. For example, the server listens to IIOP and the client can only communicate using IIOP over HTTP.
Case 2: Client messages can reach the server network, c = n
Client messages of a particular transport type (M) can reach the server network. GateKeeper is not required if the client transport type is one of the server listening transport types. For example, the client sends IIOP messages and the server also listens to IIOP.
If the server does not listen to the client's message transport type, GateKeeper is required in any network within Ns and Nn. GateKeeper acts as a proxy to relay client messages of type M to one of the server listener types (L). For example, M (client message transport type) is IIOP over HTTP and L (server listener type) is IIOP.
Case 3: Overlapping of reachable networks by client and to server, c >= s
When c >= s, the client transport type (M) and the server listener type (L) must be different. Deploy GateKeeper in any network between Ns and Nc inclusive. In this case, GateKeeper acts as a proxy to relay client messages of type M to the server listener port of type L. As an example, the client's IIOP over HTTP messages can reach the networks up to Nc. IIOP messages sent from any network between Ns and Nn can reach the server. Deploying GateKeeper in between Ns and Nc will help bind the client's IIOP over HTTP messages to the server's IIOP listener port.
Case 4: No overlapping of reachable networks by client and to server, c < s
Check if GateKeeper chaining is possible or not. See “Chaining of GateKeepers” for details of GateKeeper chaining. GateKeeper chaining is possible only when there is another transport type (K) available for the two GateKeepers to communicate successfully from Nc to Ns. Deploy one GateKeeper on network (Nc) and another GateKeeper on network Ns. After which, chain them together. For example, client sends IIOP over HTTP messages, the server listens to IIOP messages and both GateKeeper instances can use SSL to communicate with each other. The client connects to GateKeeper 1 using HTTP, GateKeeper 1 communicates with GateKeeper 2 using SSL, and GateKeeper 2 communicates with the server using IIOP.
If chaining is not possible, there is no suitable network to deploy GateKeeper. The internetworking devices connecting networks Nc and Ns must be reconfigured so that the appropriate type of messages can be forwarded from Nc to Ns. After which, locate the new Nc and Ns, and refer to the previous cases accordingly.
Configuring a multi-homed host
A multi-homed host or router connects two or more physical networks. It has multiple network interfaces; also known as Network Interface Cards (NIC). Each NIC connects to one network. The multi-homed host allows communication between the connected networks. The following diagram shows a network configuration with two multi-homed hosts (Gateway A and Gateway B).
Figure 8
To enable a multi-homed host to route data packets from one network to another correctly, IP-forwarding must be enabled and its routing table must be configured correctly. Similarly, the routing tables on the hosts must be configured correctly.
Assuming a client located on Host 1 is trying to communicate with a server located on Host 3, the client on Host 1 will first send the message to Host 3 on Network 2. Gateway A will accept the message on NIC 2 and route it to Network 3 using NIC 3. Gateway B will then accept the message on NIC 4 and route it to Network 4 using NIC 5. The message will then reach the server object on Host 3. This communication can happen only if IP-forwarding is enabled and all the routing tables are configured correctly.
Enable IP-forwarding
The multi-homed host must enable IP-forwarding to forward data packets from one network to another. If IP-forwarding is disabled, the multi-homed host cannot forward or route data packets from one network to another.
Routing table
One entry of the routing table is used for one destination host or network. Every entry must contain information about the:
The following tables show examples of routing tables for the sample network configuration.
A routing table in the multi-homed host stores the routing information about which NIC to forward data packets to. The gateway information is used to contact the next gateway in the route. (Refer to the routing table for Gateway A in the example described above.) Using NIC 3, Gateway A has to contact Gateway B to route packets to Network 4.
Hosts also have their own routing table. The gateway information is essential for the host to contact the correct gateway which can route the packet correctly. (Refer to the routing table for Host 2). Host 2 needs to contact Gateway A to reach Network 1 and Network 2. But, Network 2 has to contact Gateway B in order to reach Network 4.
Use the following methods to verify if the routing table is configured correctly:
Configuring the firewall
A firewall is a network device that performs filtering of data packets. A firewall inspects every data packet it receives and then either forwards the packet or drops it depending on the firewall's security policy.
Case 1: Restricted client transport type
The following figure shows an example of firewall packet filtering.
The firewall's security policy usually inspects the message type, message source, and message destination to perform filtering. Firewalls are capable of applying packet-filter rules based on the type of service (example: stream-oriented or datagram-packets) and the underlying protocol type (example: IP, ICMP, TCP, UDP). Suppose that the firewall identifies the communication path as a TCP packet stream, then the firewall can apply the packet-filtering rule defined in the security policy to decide if the packet should be allowed or dropped. The TCP packet streams can carry different kinds of data or payloads (example: HTTP, IIOP, FTP, SSL, etc). In general, each stream is assigned a unique port number, and it carries only one class or type of message. For example, IIOP messages can be carried on TCP Port 683 packet stream. Similarly, HTTP messages can be carried on TCP Port 80. The firewall may allow TCP Port 80, but may not allow TCP Port 683 depending on the packet-filtering rules. Using special techniques, a TCP packet stream can carry more than one type of messages. GateKeeper uses a special technique, called HTTP Tunnelling, to embed IIOP messages within HTTP messages to be carried over TCP packet streams.
When a firewall exists in the communication path between the client and server, the firewall may either forward or drop the data packets sent from the client to the server. For a successful communication between the client and server, the firewall must forward the client's messages to the server. The server can be a user application, GateKeeper, or other VisiBroker service providers such as the Smart Agent and the Naming Service. Configure the firewall to forward client's messages sent to the server's listener port.
Using Network Address Translation (NAT)
A multi-home host, router, and firewall can also perform NAT in addition to their specialized functions. NAT can translate the source host address, source port number, destination host address, and destination port number found in every network packet.
On the client side, the firewall usually translates the source host address. This method is commonly used to share a limited number of internet IP addresses.
On the server side, the firewall may translate the destination host address and/or the destination port number. This hides the real destination host address from external parties. It provides the flexibility to change the destination host address without notifying all external parties that must access the server. This flexibility holds true for the port number as well.
GateKeeper supports only static NAT, it does not support dynamic NAT. In static NAT, the translation is based on a predefined mapping table in which every address and port is always translated to a fixed value. In dynamic NAT, some rules can be set to translate addresses and ports to a range of values where the exact translated address of the network packet cannot be pre-determined because it can be any address within a given range.
See “Configuring server properties” for details on how to configure server objects to use TCP firewall with NAT. Be sure that the NAT translation mappings are added into the NAT device for successful communication between client and server objects.
With NAT, the routing tables for all the gateways involved must be configured to account for any fake network addresses in use. If not, the data packets having fake destination addresses will not be routed correctly. In addition, firewalls must be configured to forward messages to any fake destination host addresses and fake ports used in NAT. If firewalls block the fake address or fake port, a packet will not reach its destination.
Configuring GateKeeper
The following sections describe how to configure GateKeeper.
Listener ports are the most common parameters that must be configured. Different firewalls usually do not open the same range of ports for communications. GateKeeper has many services and some of them must be enabled before they can be used.
Listener ports
The following properties specify GateKeeper's exterior IIOP and HTTP listener port numbers. These are the ports on which GateKeeper listens to client requests.
If GateKeeper is deployed behind a firewall, external clients can only contact GateKeeper if the firewall allows forwarding of IIOP or IIOP over HTTP messages through ports 683 and 8088, respectively. If the firewall can only allow other port numbers because of security restrictions, the GateKeeper listener ports must be configured to use the authorized ports on the firewall.
Administrative service
GateKeeper's administrative service provides the ability for you to use the VisiBroker Console to manage and configure GateKeeper. The administrative service allows dynamic configurations of GateKeeper while GateKeeper is active. The following properties specify the administrative service port numbers; 0 and 9091 are the default values for IIOP port and HTTP port, respectively. The value 0 tells GateKeeper to pick a port at random when it starts.
Enabling callbacks (VisiBroker 3.x style)
The callback feature (VisiBroker 3.x style) has been replaced with bi-directional support in VisiBroker versions 4.x and later. For GateKeeper to support clients that still use VisiBroker 3.x callbacks, the following properties settings are required:
After setting the above properties, GateKeeper activates its interior server engine to receive callback messages from the server. The listener can be configured using the in-iiop and in-ssl SCMs. In addition, a callback listener is activated for a client to establish an additional communication channel for callback messages. See “VisiBroker 3.x style callback” for details on specifying the listener port and additional related information. Be sure the selected ports are reachable from the client and the server by ensuring that these ports are not blocked by any firewalls.
Enabling pass-through connections
The following property enables pass-through connections in GateKeeper.
If the client requests a pass-through connection, GateKeeper will not examine any messages that pass between the server and client. When the above property is set to false, GateKeeper binds the client to the server using normal (non-pass-through) connections even when the client requests a pass-through connection. In this case, GateKeeper examines the exchanged messages for routing and binding purposes.
The following properties are provided to help configure pass-through connections in GateKeeper:
See “Support for pass-through connections” for more information about the above properties.
The pass-through feature heavily taxes the resources of GateKeeper. If you choose to use this feature, be sure to configure GateKeeper with sufficient memory and increased sockets.
Enabling the location service
GateKeeper provides a location service for clients, such as applets, that are unable to communicate directly with the Smart Agent (osagent) because of Java sandbox security or existing firewalls. The location service lets the clients “bind” to the server through GateKeeper.
Specifying the Smart Agent (osagent)
GateKeeper uses the Smart Agent to locate server objects. GateKeeper can automatically locate the Smart Agent if one is located on the same network. When there is no Smart Agent running on the same network where GateKeeper is running, the location of the Smart Agent must be specified explicitly. You can also specify additional Smart Agents running on other networks.
The first property specifies the host IP address of the Smart Agent. The second property specifies the file that defines a list of hosts running Smart Agents. The third property specifies the OSAGENT_PORT. The default value for the first two properties is null, which tells GateKeeper to contact the Smart Agent running on the same network.
See “Using the Smart Agent” in the VisiBroker Developer's Guide for more details about Smart Agent settings and other methods of setting Smart Agent parameters.
Specifying the Object Activation Daemon (OAD)
The OAD service enables GateKeeper to automatically start servers to which it needs to bind. In such cases, the server is registered with the OAD service, but is accessible only through GateKeeper (when an Applet invokes a server, for example). To use the OAD service, GateKeeper must load the OAD IOR. The following property tells GateKeeper where to locate the OAD IOR.
vbroker.oad.iorFile=<OAD IOR>
See Using the Object Activation Daemon in the VisiBroker Developer's Guide for more information about OAD.
Configuring GateKeeper server engines
GateKeeper contains a few default server engines. Each server engine contains at least one server connection manager (SCM).
See “Exterior server engine”, “Interior server engine” and “Administration” for the full list of properties for the above SCMs.
Security services
Start GateKeeper with the following properties to enable IIOP/SSL and IIOP over HTTPS:,ex-hiop,ex-ssl,ex-hiops
The property enables the required security packages into the VisiBroker ORB of the GateKeeper.
The property loads the additional HIOPS package, which allows IIOP messages over HTTPS; it is loaded separately.
The,ex-hiop,ex-ssl,ex-hiops property adds the SCM ex-ssl and ex-hiops into the exterior server engine.
The unused SCM can be removed from the SCM list so that only required SCMs are started. However, scm ex-iiop and in-iiop cannot be removed from the list when they initially exist.
To make sure all communication is encrypted, you can disable the nonsecure listener ports such as IIOP and HTTP as follows:
The IIOP/SSL and HTTPS listeners can be configured using the SCM properties prefixed with and For a comprehensive list of these SCM properties, see “Appendix GateKeeper properties”.
SSL transport identity and trustpoint
For SSL, transport identity is optional as SSL negotiation still can make use of a Diffie Helman key agreement algorithm without someone's public key.
However, without transport identity clients configured with peerAuthenticationMode require and require_and_trust will not connect. Additionally, as an SSL server, if GateKeeper itself does not have a client transport identity, it may not require client transport identities.
Installing SSL identity using wallet properties
The simplest way of installing certificates in GateKeeper is by using the following wallet properties:<path_to_identities><username><password><path_to_trustpoints>
Installing SSL identity on GateKeeper using certificate login
Apart from using simple wallet and trustpoints property sets, SSL identity can be installed on the GateKeeper during startup by means of credential acquisitions (login). In the acquisition, the user must answer questions about files and directories, where the certificates, private key and trusted root certificates are stored. The password to decrypt the private key will definitely be asked.
The files and directories asked in the login conversation vary based on the type of certificate storage. The default storage is determined by JDK security settings in the following file:
Out of the JDK box, jks is set as java keystore (jks):
# Default keystore type.
For PKCS#12 storage, the above can be changed to string pkcs12. This storage format is only a single file, which contains certificates, trusted certificates and a private key. Consult the JDK keytool manual for details.
For certificate login, the following needs to be explicitly set on GateKeeper:<realm list>
In the realm list, among other realms, there needs to be Certificate#CLIENT and/or Certificate#SERVER and/or Certificate#ALL.
Certificate#CLIENT is an SSL identity that is used for outgoing SSL connections,
Certificate#SERVER is for incoming SSL connections,
Certificate#ALL can be used for both.
One extreme example is when in the <realm list> there appears all three realms. In this case, three different sets of SSL identities will be acquired from the user during GateKeeper startup.
When opening an outgoing SSL connection:
Certificate#CLIENT is used first.
If no identity is set in Certificate#CLIENT, then Certificate#ALL will be used.
If there is also none set in Certificate#ALL, the outgoing SSL connection will have no identity.
Similar priority also applies to incoming (server) SSL connection.
The identity that is set using a simple wallet property set will always go into Certificate#ALL.
Setting peerAuthenticationMode
Use the peerAuthenticationMode policy as usual. Set the property as follows:
Applet and Java webstart
The Java programming language is a powerful tool for the development of programs that are deployed and run on the fly from one central location. This becomes a very powerful feature when combined with CORBA, more specifically with VisiBroker for Java.
Clients code can be downloaded on the fly and installed from a website as either a Java applet or a Java webstart application utilizing Java Network Launching Protocol (JNLP).
VisiBroker settings on a typical applet client
If the client is an applet, the following additional property settings are required:
<applet archive=vbjorb.jar,vbsec.jar,lm.jar,sanct6.jar,
sanctuary.jar,code="ClientApplet.class" width="200"
<param name="" value="false">
<param name="vbroker.orb.dynamicLibs"
The licensing jars lm.jar, sanct6.jar, and sanctuary.jar are needed only when the applet code creates persistent POAs.
When VisiSecure functionality is involved, vbsec.jar is needed in the applet's archive list. The applet parameter that enables it is also needed. Optionally, when HIOPS functionality is involved, it needs to be loaded separately using dynamicLibs as above.
VisiBroker application deployed as a Java webstart
A Java webstart application can run without a web browser because it has its own launcher, which can be launched directly from a command shell on UNIX or by double-clicking on Windows. This launcher is the default mime handler for application/x-java-jnlp-file which is associated automatically when installing JDK/JRE on Windows and by any other means on UNIX. Therefore, clicking a link on a web page that results in any http response with that mime will launch the installed Java webstart launcher for processing the content of that reply. The content is actually an XML containing information about where to locate the required jars and other information pertaining to running the application. For example, the required java security permissions.
For a typical VisiBroker application deployed as a java webstart, see the gatekeeper bank_jws example.