Settting up and Administering the EntireX Broker SSL Agent

The EntireX Broker SSL Agent is a gateway to the broker whenever direct SSL/TLS communication with the broker is not possible. Under UNIX, use the delivered script /opt/softwareag/EntireX/bin/sslbrokeragent.bsh to start the agent. This document covers the following topics:


Common Scenarios

The most common scenarios for using the Broker SSL Agent are where direct SSL communication to the Broker is not possible or it is not required by the network architecture.

Although in most cases the Broker SSL Agent will be used from a Broker application written in Java, the Broker SSL Agent can also be used from any component or application configured with SSL. See Using SSL/TLS with EntireX Components.

Using the Broker SSL Agent

Class Name and Parameters

The Broker SSL Agent is a standalone Java application. The class name is com.softwareag.entirex.ba.SSLBrokerAgent.

Specify the following parameters in the order given in this table when the Broker SSL Agent listens on an SSL port:

Parameter Explanation
1. Trace Option Valid values: ON or OFF. Default: OFF.
A dump of the buffers is written to standard output for diagnostic purposes.
2. Port Number The port number the Broker TCP Agent uses for incoming requests from Broker applications. Specify this port number as part of the broker ID in the broker application.
3. SSL Parameters SSL parameters when the Broker SSL Agent runs as an SSL server. SSL requires a (server) certificate with a private key. Specify with key_store=filename the file name of a Java keystore that contains the private key.
SSL client authentication can be requested with the parameter verify_client=yes. In this case, specify with trust_store=filename the file name of a Java keystore containing the list of trusted certificate authorities that issued the client's certificate. The complete list of parameters could be
key_store=keystore&verify_client=yes&trust_store=castore.
Examples:
key_store=ExxJavaAppCert.jks trust_store=ExxCACert.jks.

See also SSL/TLS Parameters for Broker as SSL Server (One-way SSL).

4. Password The password which protects the private key. If the value -prompt is specified the password is read from standard input.
5. Broker Address The Broker SSL Agent sends all requests to this Broker using any legal Broker ID defined with URL-style Broker ID. The Broker SSL Agent will use SSL communication if the SSL protocol is used (the address starts with ssl://).
6. Bind Address The address of the network interface on which the Broker SSL Agent will listen for connection requests. The default is that the Broker Agent will listen on any attached interface adapter of the system. The bind address is the local IP address or host name to bind to.

Starting the Broker SSL Agent

Under UNIX, the EntireX distribution kit comes with a shell script to start the Broker SSL Agent. Change the port number, the Broker address and the SSL parameters in script /<Install_Dir>/EntireX/bin/sslbrokeragent.bsh.

Activating Tracing for the Broker SSL Agent

Set the parameter Trace Option to "ON". See Class Name and Parameters.

Architecture of the Broker SSL Agent

The architecture of the Broker SSL Agent is shown in the following picture: