SSL Configuration using Java Keystore

SSL Configuration

LogicalDOC embeds the Tomcat application server and it can be configured to support the encrypted protocol HTTPS. This is useful when you want to expose the program on the Internet. Basically you only have to follows the steps described in the Apache how-to at SSL Configuration HOW-TO

What follows is a re-visioned extract from that how-to

Prepare the certificate Keystore

To install and configure SSL support on Tomcat, you need a keystore that is a file containing one or more certificates Tomcat currently operates on JKS 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.

Each entry in a keystore is identified by an alias string. To import an existing certificate into a JKS keystore, please read the documentation (in your JDK documentation package) about keytool.

To create a new keystore from scratch, containing a single self-signed Certificate, execute the following from a terminal command line:

Windows:

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

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, in the home directory of the user under which you run it, named ".keystore". 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. For example:

Windows:

   %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
     -keystore <LDOC_HOME>\conf\keystore

Unix:

   $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
     -keystore <LDOC_HOME>/conf/keystore

replace <LDOC_HOME> with the installation path of LogicalDOC

After executing this command, you will first be prompted for the keystore password. The default password used by 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, such as company, contact name, and so on. 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. (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.

Edit the Tomcat configuration file

The final step is to configure your secure socket in the $CATALINA_BASE/conf/server.xml file, where $CATALINA_BASE represents the base directory for the Tomcat 6 instance. An example <Connector> element for an SSL connector is included in the default server.xml file installed with Tomcat. It will look something like this:

   <-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
   <Connector 
              port="8443" minSpareThreads="5" maxSpareThreads="75"
              enableLookups="true" disableUploadTimeout="true" 
              acceptCount="100"  maxThreads="200"
              scheme="https" secure="true" SSLEnabled="true"
              keystoreFile="${user.home}/.keystore" keystorePass="changeit"
              clientAuth="false" sslProtocol="TLS"/>

You will note that the Connector element itself is commented out by default, so you will need to remove the comment tags around it. Then, you can customize the specified attributes as necessary.

The port attribute (default value is 8443) is the TCP/IP port number on which Tomcat will listen for secure connections. You can change this to any port number you wish.

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 2.4 Specification.

After completing these configuration changes, you must restart Tomcat as you normally do, and you should be in business. You should be able to access LogicalDOC via SSL. For example, try:

   https://localhost:8443

and you should see the usual login page.

Importing a certificate

Please note that each certificate issuer is different and the procedure to install their certificates in Tomcat may be differ.

It is responsibility fo your certificate issuer to provide you with a tutorial on installing the certificate in Tomcat. So refer to your certificate issuer for getting help.

For your convenience, here below is a list of How-Tos from different issuers:

In general, if you have your Certificate you can import it into you local keystore. First of all you have to import a so called Chain Certificate or Root Certificate into your keystore. After that you can proceed with importing your Certificate.

Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.

 For Entrust commercial certificates go to: http://www.entrust.net
 For Verisign commercial certificates go to: http://www.verisign.com/support/install/intermediate.html
 For Thawte go to: http://www.thawte.com/certs/trustmap.html
 For GoDaddy go to: https://www.godaddy.com/help/tomcat-generate-csrs-and-install-certificates-5239

Import the Chain Certificate into your keystore

         keytool -import -alias root -keystore <your_keystore_filename> \
         	-trustcacerts -file <filename_of_the_chain_certificate>

And finally import your new Certificate

         keytool -import -alias tomcat -keystore <your_keystore_filename> \
         	-file <your_certificate_filename>

SSL Configuration using Java Keystore

Contents