Considerations for Enterprise Server Command Line Utilities with SSL-enabled Servers

Starting with release 5.0, there are stricter checks of connections to SSL-enabled Enterprise Server regions.

Enterprise Server utilizes TCP communications among its components for various purposes. These include administration functions such as retrieving and updating region configuration information, and application functions such as invoking Web services and submitting JCL jobs.

It is possible to configure these communication channels to use SSL (also called TLS) to encrypt and protect data, and to verify the identity of the server.

In earlier versions of Enterprise Server, the identity of the remote component was not always verified correctly. In particular, client programs did not always check to ensure that the certificate sent by the server contained a name which matched the hostname of the system they wished to connect to. Starting with release 5.0, this check is now performed which significantly improves security.

As a result of this change some command line utilities might require additional or different command line parameters in order to work properly with an SSL-enabled Enterprise Server region. In typical configurations, the stricter checking of server identity fails when using the default options. More specifically:

Like other TCP/IP servers, Enterprise Server components are typically configured to use certificates that identify the machine they run on using either a simple hostname or a fully-qualified domain name. A fully-qualified domain name (FQDN) is a hostname plus a domain name - for example, myhost.mycorp.com.
By default, Enterprise Server components try to connect to one another using "localhost" as the hostname, or in some cases using the IP address "127.0.0.1".
If a component tries to make an SSL connection to a server using "localhost" as the destination name, but receives a certificate which gives the machine's actual hostname instead, it will reject the certificate as not matching the desired location.

Example - SSL-enabled MFDS

Consider the following command line:

casstart -rREGION -uUSERID -pPASSWD

When run on a system with an SSL-enabled Micro Focus Directory Server (MFDS), this command usually results in a region startup which is unable to read its configuration from MFDS, or update the status information there. This is because the region processes reject the certificate presented by MFDS.

In such cases, the region usually starts anyway by reading its configuration from the MFDS repository files directly. However, startup warnings are logged in the log files, and MFDS shows the region as stopped.

To avoid this failure, use one of the following approaches:

Replace your existing server certificates with ones that include the name "localhost" and the IP address "127.0.0.1" as well as the actual hostname of the system. A certificate can contain multiple hostnames and IP addresses using what is known as Subject Alternative Name extensions. Consult your Certificate Authority administrators for more information.
Pass the correct hostname, myhost, when using casstart to connect to MFDS using the -m command line option:
```
casstart -rREGION -uUSERID -pPASSWD -mmyhost.mycorp.com
```
The argument to use with the -m options is the name of the server as it appears in the server's certificate.

Example - utilities that use SSL-enabled connections

The same applies to utilities which can optionally be configured to use an SSL-enabled connection. With cassub, for example, you could use a command line similar to:

cassub -stcpssl:localhost:9003 -jsomejob.jcl

However, the certificate configured for the Enterprise Server listener on port 9003 might specify a name of myhost and not "localhost". In this case, you need to use the host name that matches the name in the certificate in the -s option:

cassub -stcpssl:myhost:9003 -jsomejob.jcl