Configuring Applicare Server for HTTPS

Prepare the Certificate Keystore

Applicare operates on JKS-, PKCS11-, or PKCS12-format keystores. The JKS format is Java's standard "Java KeyStore" format and is the format created by the keytool command-line utility. This tool is included in the JDK. The PKCS12 format is an Internet standard, and it can be manipulated via OpenSSL and Microsoft's Key-Manager (among other tools).

Each entry in a keystore is identified by an alias string. While many keystore implementations treat aliases in a case-insensitive manner, case-sensitive implementations are available. The PKCS11 specification, for example, requires that aliases are case-sensitive. To avoid issues related to the case-sensitivity of aliases, it is not recommended to use aliases that differ only in case.

To import an existing certificate into a JKS keystore, please read the keytool documentation in your JDK documentation package. Note that OpenSSL often adds readable comments before the key, but keytool does not support that. So if your certificate has comments before the key data, remove them before importing the certificate with keytool.

To import an existing certificate signed by your own CA into a PKCS12 keystore using OpenSSL, execute a command like this:

openssl pkcs12 -export -in mycert.crt -inkey mykey.key
                        -out mycert.p12 -name tomcat -CAfile myCA.crt
                        -caname root -chain

For more advanced cases, consult the OpenSSL documentation.

To create a new JKS keystore from scratch, containing a single self-signed certificate, execute one of the following from a terminal command line.

For Windows:

"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA

For Unix:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

(The RSA algorithm should be preferred as a secure algorithm, and this also ensures general compatibility with other servers and components.)

This command will create a new file name .keystore in the home directory of the user under which you run it. To specify a different location or filename, add the -keystore parameter, followed by the complete pathname to your keystore file, to the keytool command shown above. You will also need to reflect this new location in the server.xml configuration file, as described later. See the below examples.

For Windows:

"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA
  -keystore \path\to\my\keystore

For Unix:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
  -keystore /path/to/my/keystore

After executing this command, you will first be prompted for the keystore password. The default password used by Applicare Tomcat is changeit (all lower-case), although you can specify a custom password if you like. You will also need to specify the custom password in the server.xml configuration file, as described later.

Next, you will be prompted for general information about this certificate. This information will be displayed to users who attempt to access a secure page in your application, so make sure that the information provided here matches what they will expect.

Finally, you will be prompted for the key password, which is the password specifically for this certificate (as opposed to any other certificates stored in the same keystore file). You MUST use the same password here as was used for the keystore password itself. This is a restriction of the Tomcat implementation. (Currently, the keytool prompt will tell you that pressing the ENTER key does this for you automatically.)

If everything was successful, you now have a keystore file with a certificate that can be used by your server.

Please note: your private key password and keystore password should be the same. Otherwise,, as documented in Bugzilla issue 38217, you will get an error along the lines of the following:

java.io.IOException: Cannot recover key

Edit the Applicare Tomcat Configuration File

To define a Java (JSSE) connector, use the following:

<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector
           protocol="org.apache.coyote.http11.Http11Protocol"
           port="8443" maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
           clientAuth="false" sslProtocol="TLS"/>

The port attribute is the TCP/IP port number on which Applicare Tomcat will listen for secure connections. You can change this to any port number you wish (such as to the default port for HTTPS communications, which is 443). However, special setup (outside the scope of this document) is necessary to run Applicare Tomcat on port numbers lower than 1024 on many operating systems.

If you change the port number here, you should also change the value specified for the redirectPort attribute on the non-SSL connector. This allows Tomcat to automatically redirect users who attempt to access a page with a security constraint specifying that SSL is required, as required by the Servlet Specification.

Edit the Applicare.props File

Next we need to update applicare.serverPort value to 8443 (or any port # used by SSL) and applicare.serverSSL value to true, in Applicare.props file in the {ARCTURUS_HOME} directory. The same changes need to be done for the Applicare.props file in the existing agent's {ARCTURUS_HOME} directory also. You should copy Applicare.props from the Applicare server to the agent. Without this configuration the agents cannot talk to the Applicare server with a non-SSL port that may be configured earlier and pull the Applicare.props as they normally do.

If you don't have the applicare.serverSSL parameter in property file, please add it.

After completing these configuration changes, restart the Applicare Server/Tomcat as you normally do. You should be able to access the Applicare console via SSL at the URL below:

https://localhost:8443/applicare