Configuring Tomcat for SSL with Web Viewer 12.1

Products

• Output Management Web Viewer

Issue/Introduction

There are basically four steps:

1. Confirm whether you already have a keystore or will initially test with a self-signed certificate.
2. Create a keystore  (skip this step if  you already have a keystore)
3. Modify the Tomcat configuration document, server.xml.
4. Stop and start Tomcat

Tomcat currently operates only 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 (Java Development Kit) and also in the JRE (Java Runtime Environment).

Environment

Release:  Output Management Web Viewer 12.1
Component: WBVLUW

Resolution

Define the requirements

Find out what is required in terms of minimal security. Additionally, you need to know if your company already has trusted certificates they can be used on the Tomcat server.

• If all you want is encryption/decryption without authentication, then any user certificate will suffice.  (Note: The user will get a certificate error in the browser, which can be ignored.)  To remove the certificate error, you will need to get a trusted certificate.
• If you need to perform client authentication with SSL, then you must get your own trusted certificate from a Certificate Authority to authenticate Tomcat to the browser.  

Self-signed certificates are very useful for testing and they are easily created with Java's keytool program.  You can test with a self-signed certificate and then proceed with the trusted certificate.

 

2. Create a Self Signed Keystore (if you do not have one)

a. Verify that Java is in your path by typing java -version.   if the Java bin directory is not in your path, you need to explicitly specify the path for the keytool. For example, in Windows, type: "%JAVA_HOME%\bin\keytool", and in Unix or USS or Linux, enter: $JAVA_HOME/bin/keytool.  If you have only the JRE, type JRE_HOME instead of JAVA_HOME. 

 

b. Generate the keystore and user certificate:

keytool -genkey -alias tomcat -keyalg RSA -keysize 2048 -validity 365 -keystore "c:\tomcat.jks"

• genkey is the command to keytool telling it what operation to perform (generate a keypair)
• alias is followed by the alias entry of the keypair. The alias name is “tomcat” in this example. However, any alias name can be used, as long as it agrees with the Tomcat configuration in the next step.
• keyalg specifies to use the RSA algorithm for data encryption/decryption
• keysize specifies the length of the keys. 2048 bits (256 bytes) is recommended
• validity specifies when the certificate will expire from its creation date.  This is specified in days.
• -keystore specifies the name of the keystore file.

c. The keytool program will prompt for the following parameters to complete the generation of the keystore:

• Password                Password of the keystore           
• Common Name      The fully qualified domain name of your server. This must match exactly what you type in your web browser when starting Web Viewer.  You may use the IP address also.
• Organization           The legal name of your organization. This should not be abbreviated and should include suffixes such as Inc, Corp, or LLC.        
• Organizational Unit  The division of your organization handling the certificate.           
• City/Locality             The city where your organization is located.       
• State/County/Region The state or region where your organization is located. Do not abbreviate.     
• Country                    The two-letter ISO code for the country where your organization is located in.   Such as US.

  

3. Tomcat Configuration:

To configure Tomcat, you need to change one file. That file is named “server.xml”, and is located in the /conf directory, a directory directly under where Tomcat was installed.

• There are several “Connector”s defined in this file. You will see one that is used for regular HTTP, using port 8080. This should be commented out with
  <!-- 
  old connector
  -->
• Then uncomment the HTTPS connector using the JSSE NIO implementation. It is not recommended to use the APR implementation.
  
  <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
  <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
  port=”8443” maxThreads=200
  scheme=”https” secure=”true” SSLEnabled=”true”
  keystoreFile=”C:\tomcat.jks”  keytstorePass=”tomcat”
   clientAuth="false" sslProtocol="TLS"/>
   
•  Edit the parameters as needed including pointing to your keystore.  Port 8443 is the default SSL port, but you can use any port that is not already is use by another application on the Tomcat server.

The KeyAlias should be specified even in you have only one keypair. The keyAlias used to for the server certificate in the keystore. If not specified the first key read in the keystore will be used.

 

4.  Restart Tomcat

Additional Information

The most comprehensive, and readable document on this topic, is actually from the Apache Tomcat website: Apache Tomcat SSL How to


To create a certificate request to send to your Certificate Authority
keytool –keystore clientkeystore –certreq –alias client –keyalg rsa  –file client.csr

KeyStoreExplorer is a free graphical user interface that runs on Windows and is used to navigate throughout a keystore. It is written in Java and has basically the same capabilities as the command line program “keytool”. Use this tool to become familiar with keystores and to examine the contents of keys and certificates.

Also so this information from Digicert  Tomcat CSR & SSL installation