There are basically four steps:
- Confirm whether you already have a keystore or will initially test with a self-signed certificate.
- Create a keystore (skip this step if you already have a keystore)
- Modify the Tomcat configuration document, server.xml.
- 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).
1. 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 that can be used on the Tomcat server.
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.
- 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.
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"
c. The keytool program will prompt for the following parameters to complete the generation of the keystore:
- 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.
- 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.
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.
- 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
- 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 -->
keystoreFile=”C:\tomcat.jks” ketstorePass=”tomcat” keyAlias=”tomcat”
- 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.
4. Restart Tomcat
The most comprehensive, and readable document on this topic, is actually from the Apache Tomcat website: http://tomcat.apache.org/tomcat-8.5-doc/ssl-howto.html.
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.