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:
Clients that use the CAST web applications.
Web services deployed by CentraSite-enabled products.
The document contains the following sections:
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
Changing the Certificate Configuration for the CAST Components
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.
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:
CentraSite
Centrasite_authenticated (this web application is disabled by default for security reasons)
SOALinkSNMPEventsListener
UddiRegistry
BusinessUI
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":
javax.net.ssl.trustStore
javax.net.ssl.trustStorePassword
javax.net.ssl.trustStoreType
javax.net.ssl.keyStore
javax.net.ssl.keyStorePassword
javax.net.ssl.keyStoreType
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 CentraSite installation comes with self-signed certificates from Software AG. These are:
The keystore certificate. This is located at <CentraSiteInstallDir>/cast/files/certs/castcert.p12. It contains the client certificate and private client key.
The truststore certificate. This is located at <CentraSiteInstallDir>/cast/files/certs/casttrust.p12. This would normally contain the server certificate but actually contains the CA certificate and key.
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.
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:
To allow mixed HTTP/HTTPS communication between CAST and CRR
Use inoadmin to change the communication method setting as follows:
inoadmin setproperty CentraSite "communication method" "HTTP and HTTPS" restart
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".
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".
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".
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".
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".
Make the following changes in <RuntimeDir>/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".
In the CentraSite environment, Software AG Runtime can receive requests from clients such as:
User applications using an API to communicate with the registry repository.
Components of the Software AG Designer.
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 Tomcat can be found under links such as the following (version-specific for Tomcat 7.0):
The file com.softwareag.catalina.connector.https.pid-CentraSite.properties located in <SuiteInstallDir>/profiles/CTP/configuration/com.softwareag.platform.config.propsloader contains the properties that you need to set in order to configure Tomcat for secure communication with external clients. The properties in this file define the SSL keystore and SSL truststore that Software AG Runtime will use.
Refer also to the general cross-product instructions for setting Software AG Runtime properties for SSL communication at http://documentation.softwareag.com/webmethods/wmsuites/wmsuite9-6/Cross_Product/9-6_Working_with_Runtime.pdf, which describes how to configure HTTPS connectors to set up the SSL environment. Note that this cross-product document refers to the properties file generically as com.softwareag.catalina.connector.https.pid-<port_number>.properties.
CentraSite comes with a sample keystore that contains self-signed certificates which are located in <SuiteInstallDir>/profiles/CTP/configuration/tomcat/conf 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 Software AG Runtime properties file for SSL communication.
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". Software AG Runtime 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 Software AG Runtime properties
file).
If you want to use client authentication for 2-way SSL, you need to set clientAuth="true" in the Software AG Runtime properties file for SSL communication, and supply a truststore, which is a keystore containing the certificate chain and trust root for the client certificates for which you want to allow access.
In the properties file, you also need to provide the following properties:
truststoreFile: the name and path of the truststore file
truststorePass: the password for accessing the truststore
truststoreType: the type of the truststore
truststoreProvider: the provider of the truststore
For a full description of these properties, refer to the Tomcat SSL documentation at http://tomcat.apache.org/tomcat-7.0-doc/config/http.html.
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.
