Version 9.5 SP1
 —  Basic Operations  —

Configuring Secure Communication between CentraSite Components

This document gives information about how to set up secure communication between CentraSite components, on the basis of SSL.

If you change the default configuration, you might also need to modify other products based on CentraSite. Changing the CAST configuration can affect applications such as:

The document contains the following sections:


Secure Communication between the CRR and the CAST

The communication between the CRR and the CAST components takes place via 2-way SSL authentication. For this full client/server SSL communication, the client and server must accept each other's certificates. This means that the CAST and CRR stores need to have matching certificates for the communication to work.

The CAST components have access to an SSL context to establish an SSL (HTTPS) connection to the CRR. The SSL authentication establishes a trusted relationship between the CentraSite Server on the CAST and the CRR. Therefore no user re-authentication needs to be performed by the CRR.

The CentraSite installation comes with self-signed certificates from Software AG.

You can deactivate the SSL communication between the CRR and the CAST components, as described in the subsequent section Allowing HTTP Communication between CAST and CRR. However, Software AG strongly recommends you NOT to do this, because it opens a potential security risk.

You can configure aspects of the SSL setup, as described in the following sections.

Changing the Certificate Configuration for the Registry Repository

The CRR provides the following configurable properties:

Property name Purpose
SSL certificate file

Name of the file that contains the server certificate. The default is <CentraSiteInstallDir>/files/certs/crrcert.crt.

SSL key file Name of the file that contains the private server key. The default is <CentraSiteInstallDir>/files/certs/crr.key.
SSL password Password for accessing the SSL configuration files. The default is "cscert".
SSL CA file

Name of the file that contains the certificate authority (CA) truststore. The default is <CentraSiteInstallDir>/files/certs/cstrust.pem.

This file would normally contain the client certificate but actually contains the CA certificate and key.

SSL verify client Perform client authentication during handshake. Possibly values are "yes" and "no". The default is "yes".
SSL verify depth Depth of certificate chain used for client authentication. The default is 1.

The key and certificate files need to be in an OpenSSL readable format. The CA file needs to be in PEM format.

Note that in the default configuration, the same CA certificate is used for both client and server certificates.

The server parameters can be changed via the command line tool inoadmin.

The general syntax is

inoadmin setproperty CentraSite "<PropertyName>" "<PropertyValue>" norestart

For example:

inoadmin setproperty CentraSite "SSL certificate file" "C:/SoftwareAG/CentraSite/files/certs/custom_cacert.pem" norestart

Restart the CRR after changing the parameter settings.

Changing the Certificate Configuration for the CAST Components

The CAST web applications read the SSL configuration from their deployment descriptor, which is located at <CentraSiteInstallDir>/cast/cswebapps/<WebApplicationName>/WEB-INF/web.xml. For some of these web applications, you can change the SSL settings in the web.xml files. The web applications for which this applies are:

For the CentraSiteControl application, the SSL configuration is stored in <RuntimeWebAppsDir>/PluggableUI/CentraSiteControl/plugin.xml.

For the BusinessUI application, the SSL configuration is stored in <CentraSiteInstallDir>\cast\cswebapps\BusinessUI\system\conf\centrasite.xml.

The web.xml configuration files contain entries like the following. Modify the <param-value> values as desired, then restart the Software AG Runtime.

<init-param>
  <param-name>com.softwareag.centrasite.security.trustStore</param-name>
  <param-value>C:/SoftwareAG/CentraSite/cast/files/certs/casttrust.p12</param-value>
</init-param>
<init-param>
  <param-name>com.softwareag.centrasite.security.trustStorePassword</param-name>
  <param-value>cscert</param-value>
</init-param>
<init-param>
  <param-name>com.softwareag.centrasite.security.trustStoreType</param-name>
  <param-value>PKCS12</param-value>
</init-param>
<init-param>
  <param-name>com.softwareag.centrasite.security.keyStore</param-name>
  <param-value>C:/SoftwareAG/CentraSite/cast/files/certs/castcert.p12</param-value>
</init-param>
<init-param>
  <param-name>com.softwareag.centrasite.security.keyStorePassword</param-name>
  <param-value>cscert</param-value>
</init-param>
<init-param>
  <param-name>com.softwareag.centrasite.security.keyStoreType</param-name>
  <param-value>PKCS12</param-value>
</init-param>

The meaning of the properties corresponds to the system properties of the Java 2 platform package "javax.net.ssl":

For the CentraSiteControl application, the file plugin.xml contains entries of the form <extension ... id="..." value="...">. The id and value entries correspond to the param-name and param-value entries of the web.xml files.

For the BusinessUI application, the SSL settings are defined in the element <SSL> in the centrasite.xml file, using the same property naming conventions as in the web.xml files.

The CAST Stores

The CentraSite installation comes with self-signed certificates from Software AG. These are:

These files need to be in a Java readable format.

Note that in the default configuration, the same CA certificate is used for both client and server certificates.

Allowing HTTP Communication between CAST and CRR

It is possible to change the communication between CAST and CRR from full 2-way SSL (HTTPS) communication to mixed HTTP/HTTPS communication.

Warning:
Software AG strongly advises you to use 2-way SSL at all times for this communication. If you intend to use HTTP rather than HTTPS communication, please consider carefully that using HTTP communication raises a potential security risk.

Some internal communication between CAST and CRR must always use SSL, therefore you cannot switch off HTTPS altogether.

If you wish to use a mixed HTTP/HTTPS communication, proceed as follows:

Start of instruction setTo allow mixed HTTP/HTTPS communication between CAST and CRR

  1. Use inoadmin to change the communication method setting as follows:

    inoadmin setproperty CentraSite "communication method" "HTTP and HTTPS" restart
  2. Make the following change in <CentraSiteInstallDir>/cast/cswebapps/CentraSite/WEB-INF/web.xml:

    Change the value of com.softwareag.centrasite.sslusage from "yes" to "no".

  3. Make the following change in <CentraSiteInstallDir>/cast/cswebapps/CentraSite_authenticated/WEB-INF/web.xml.disabled:

    Change the value of com.softwareag.centrasite.sslusage from "yes" to "no".

  4. Make the following changes in <CentraSiteInstallDir>/cast/cswebapps/SOALinkSNMPEventsListener/WEB-INF/web.xml:

    Change the value of com.softwareag.centrasite.sslusage from "yes" to "no".

    Change the value of com.softwareag.centrasite.soalink.events.dbUrl to use "http" instead of "https".

  5. Make the following changes in <CentraSiteInstallDir>/cast/cswebapps/UddiRegistry/WEB-INF/web.xml:

    Change the value of com.softwareag.centrasite.sslusage from "yes" to "no".

    Change the value of com.centrasite.uddi.store.db to use "http" instead of "https".

  6. Make the following changes in <CentraSiteInstallDir>/cast/cswebapps/BusinessUI/system/conf/centrasite.xml:

    Change the url attribute of the CentraSite element to use "http" instead of "https".

    Change the value of the sslusage attribute of the SSL element from "yes" to "no".

  7. Make the following changes in <SuiteInstallDir>/profiles/CTP/workspace/webapps/PluggableUI/CentraSiteControl/plugin.xml:

    Change the value of com.softwareag.centrasite.sslusage from "yes" to "no".

    Change the value of crrUrl to use "http" instead of "https".

Top of page

Secure Communication between Tomcat and External Clients

Configuring Tomcat to communicate with Client Applications via SSL

In the CentraSite environment, Tomcat can receive requests from clients such as:

By default, only basic communication encryption without authentication is configured.

Please consult the Tomcat manuals for details on how to configure the SSL-based authentication – here we only provide the basics. General instructions on how to protect a Tomcat 5.5 can be found under http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html.

CentraSite comes with a sample keystore that contains self-signed certificates which are located in the conf directory of Tomcat and need be replaced if SSL-based authentication is to be used.

Please acquire and provide your own server certificate and define its location with the parameter keystoreFile (replace the default value) in the Tomcat properties file. See the section Changing the Tomcat Port Numbers for information about the properties file.

Note that the CN of the certificate needs to be identical to the URL the server is addressed under, without the "https://". For example, for a server reachable under https://MyWebServer:8443/, the CN needs to be "MyWebServer". Tomcat supports both Java keystores (keystoreType="JKS", which is the default), and PKCS#12 keystores (keystoreType="PKCS12"). Please set the keystore password accordingly (parameter keystorePass in the Tomcat properties file).

If you want to use client authentication, you need to set clientAuth="true" in the Tomcat properties file, and supply a truststore, which is a keystore containing the certificate chain and trust root for those client certificates for which you want to allow access.

Note on SSL port number

If a URL addresses a location using SSL, the URL must explicitly specify the port number of the location, even if the default port number for SSL (443) is to be used.

Top of page