Communicating with SSL-enabled Oracle Endeca components

The Deployment Template supports enabling SSL to communicate securely with the EAC Central Server and with the CAS Server for version 3.0.x and later. (Secure communication between the Deployment Template and the CAS Server is not supported in CAS 2.2.x.)

For details about enabling SSL in the EAC Central Server or Agent, refer to the Oracle Endeca Security Guide. For details about enabling SSL in CAS, refer to the CAS Developer's Guide.

To use the template with an SSL-enabled Central Server:

Update runcommand.bat/.sh to load your SSL keystore and truststore.

Note: To enable secure communication, you must have already followed the documentation to create a Java keystore and truststore, containing your generated certificates. Upload a copy of these certificates to the server on which your Deployment Template scripts will run. Edit the runcommand file to specify the locations of these files.

On Windows, edit runcommand.bat to add the following lines:

...

set JAVA_ARGS=%JAVA_ARGS% "-Djava.util.logging.config.file=%~dp0..\config\script\logging.properties"

if exist [\path\to\truststore] (
  set TRUSTSTORE=[\path\to\truststore]
) else (
  echo WARNING: Cannot find truststore at [path\to\truststore]. Secure EAC communication may fail.
)

if exist [\path\to\keystore] (
  set KEYSTORE=[\path\to\keystore]
) else (
  echo WARNING: Cannot find keystore at [\path\to\keystore]. Secure EAC communication may fail.
)

set JAVA_ARGS=%JAVA_ARGS% "-Djavax.net.ssl.trustStore=%TRUSTSTORE%" "-Djavax.net.ssl.trustStoreType=JKS" "-Djavax.net.ssl.trustStorePassword=[truststore password]"

set JAVA_ARGS=%JAVA_ARGS% "-Djavax.net.ssl.keyStore=%KEYSTORE%" "-Djavax.net.ssl.keyStoreType=JKS" "-Djavax.net.ssl.keyStorePassword=[keystore password]"

set CONTROLLER_ARGS=--app-config AppConfig.xml

...

Note that the final two new lines (beginning with "set JAVA_ARGS" are wrapped to fit the page size of this document, but each of those two lines should have no line breaks. Also note that you need to fill in the locations and passwords of your keystore and truststore files in the locations indicated by the placeholders in italics.

On UNIX, edit runcommand.sh as follows:

...

JAVA_ARGS="${JAVA_ARGS} -Djava.util.logging.config.file=${WORKING_DIR}/../config/script/logging.properties"

if [ -f "[/path/to/truststore]" ] ; then 
  if [ -f "[/path/to/keystore]" ] ; then 
    TRUSTSTORE=[/path/to/truststore]
    KEYSTORE=[/path/to/keystore]
    JAVA_ARGS="${JAVA_ARGS} -Djavax.net.ssl.trustStore=${TRUSTSTORE}"
    JAVA_ARGS="${JAVA_ARGS} -Djavax.net.ssl.trustStoreType=JKS"
    JAVA_ARGS="${JAVA_ARGS} -Djavax.net.ssl.trustStorePassword=[truststore password]"
    JAVA_ARGS="${JAVA_ARGS} -Djavax.net.ssl.keyStore=${KEYSTORE}"
    JAVA_ARGS="${JAVA_ARGS} -Djavax.net.ssl.keyStoreType=JKS"
    JAVA_ARGS="${JAVA_ARGS} -Djavax.net.ssl.keyStorePassword=[keystore password]"
  else
    echo "WARNING: Cannot find keystore at [/path/to/keystore]. Secure EAC communication may fail."
  fi
else
  echo "WARNING: Cannot find truststore at [/path/to/truststore]. Secure EAC communication may fail."
fi

CONTROLLER_ARGS="--app-config AppConfig.xml"

...

In the app element of the AppConfig.xml document, update the sslEnabled attribute to true. The sslEnabled attribute is a application-wide setting that applies to the EAC and to CAS (if used in your application).
Specify the SSL-enabled port for the EAC.
The Endeca HTTP Service uses a separate port to communicate securely. For example, the default non-SSL connector is on port 8888 and the default SSL connector listens on port 8443. The SSL port should be specified in the eacPort attribute of the app element in the AppConfig.xml document.
If you are using CAS in your application, specify the SSL-enabled port for CAS.
The Endeca CAS Service uses a separate port to communicate securely. For example, the default non-SSL port is 8500 and the default SSL port is 8505. The SSL port should be specified in the value attribute of casPort.
Specify the non-SSL connector for hosts. Internally, the EAC Central Server always initiates communication with Agents by communicating with the non-SSL connector. When the Agent is SSL-enabled, the non-secure port redirects communication to the secure port. In both cases, the appropriate configuration is to specify the non-secure port for provisioned hosts.
Specify the non-SSL connector for Oracle Endeca Workbench.
In the ConfigManager component, the property webStudioPort should specify the non-secure connector for the Endeca Tools Service, as communication with Oracle Endeca Workbench configuration store always uses the unsecured channel.

The following excerpt from the AppConfig.xml document shows a sample configuration for an SSL-enabled application.

<!—
#########################################################################
# Global variables
#
-->
<app appName="MySslApp" eacHost="host-lt1" eacPort="8443" 
    dataPrefix="MySslApp" sslEnabled="true" lockManager="LockManager">
  <working-dir>C:\Endeca\Apps\MySslApp</working-dir>
  <log-dir>./logs</log-dir>
</app>

<!--    
########################################################################
# Servers/hosts
#
-->
<host id="ITLHost" hostName="myhost1.company.com" port="8888" />
<host id="MDEXHost" hostName="myhost2.company.com" port="8888" />

<!--
########################################################################
# Content Acquisition System Server
#

<custom-component id="CAS" host-id="CASHost" class="com.Oracle Endeca.eac.toolkit.component.cas.ContentAcquisitionServerComponent">
  <properties>
    <property name="casHost" value="localhost" />
    <property name="casPort" value="8505" />
  </properties>
</custom-component>

-->