Enabling Secure Socket Layer (SSL) protocol for the Apache Tomcat web application server
To enable the Apache Tomcat web application server to support the Secure Socket Layer (SSL) protocol to configure a secure connection (HTTPS), you must obtain and load the appropriate SSL certificates.
Before you begin
Ensure that the %JAVA_HOME% ($JAVA_HOME on Linux) path and the Apache Tomcat JVM path are synchronized, such as shown below:
| Apache Tomcat JVM | Environment Variable |
|---|---|
| C:\Program Files\Java\jdk7\bin\server\jvm.dll | %JAVA_HOME% C:\Program Files\Java\jdk7\ |
| /usr/java/jdk7 | $JAVA_HOME /usr/java/jdk7 |
Ensure that the %PATH% ($PATH on Linux) environment variable setting contains the %JAVA_HOME%\bin ($JAVA_HOME/bin on Linux) path.
Procedure
- Generate a keystore file for use with Apache Tomcat:
- In a Command Prompt or Terminal window (run as administrator), cd to the JDK bin directory. For example C:\Program Files\Java\jdk7\bin (/usr/java/jdk7 on Linux).
- Generate a keystore file using the keytool -genkey command.
On Windows:
keytool -genkey -keystore C:\server_name.jks -alias server_name -keyalg RSA -keysize 2048 -validity 3650
On Linux:
keytool -genkey -keystore /usr/server_name.jks -alias server_name -keyalg RSA -keysize 2048 -validity 3650
While running this command, you specify a password for the keystore and provide organizational information about the Apache Tomcat site.Note: In some cases, the correct answers to some of the site information prompts in the keytool -genkey command might not be obvious. For example:- What is your first and last name?
-
Enter the fully-qualified name of the Apache Tomcat server computer (for example, wkstn012.domain.company.corp).
In a subsequent step, you will generate a web application certificate request based on the computer name specified in this response. The certificate works with the specific computer that is running the server application. You cannot specify a domain, expecting the certificate to work with multiple computers in that domain.
- What is the name of your State or Province?
- Enter the full name of your state or province. For example, enter Massachusetts. Do not enter an abbreviation like MA or Mass.
Note: The keystore file for this example is C:\server_name.jks (/usr/server_name.jks on Linux). You will use this file location and the keystore password in subsequent steps.Keep the Command Prompt or Terminal window open, as you will use it for subsequent steps in this process.
Note:By virtue of specifying
-alias server_nameas part of the command that generates your initial keystore, your keystore now has aprivateKeyEntrywhose alias name isserver_name, and it has the machine information you provided as part of itscertificate.At this point, it is essentially a "self-signed" certificate. In a later step you will import a real "machine cert," obtained from a valid Certificate Authority, into this keystore. That import command also specifies to use
Failure to use the same-alias server_name. That cert, issued by a trusted authority, will replace the self-signed cert in yourprivateKeyEntrywith a valid cert with an established and known "trust chain."-alias <value>in both commands will result in a keystore that has a self-signedprivateKeyEntryand a machine cert under a different alias—and that will not work when you try to implement SSL/SSO. - Obtain a certificate from a trusted Certificate Authority for your implementation of the Apache Tomcat application.
If you already have a certificate, either as a PFX (Personal Information Exchange) certificate or non-PFX, then you can skip this step and the next step.
You can create a server authentication certificate via IIS if your domain controller is configured with Certificate Services. The following web pages explain how to create and export the PFX certificate.- Generate a certificate request using the keytool -certreq command with the keystore you created in the previous step:
On Windows:
keytool -certreq -keystore c:\server_name.jks -keyalg RSA -alias server_name -file c:\certreq.csr -storepass *****
On Linux:
keytool -certreq -keystore /usr/server_name.jks -keyalg RSA -alias server_name -file /usr/certreq.csr -storepass *****
where ***** is the keystore password
- Submit the certificate request file c:\certreq.csr (/usr/certreq.csr on Linux) to a trusted Certificate Authority.
- Once the certificate has been issued, follow the steps provided by your certificate provider and save the certificate that you received back from the CA, either in
PKSC#7or inX.509format, according to their procedures.
Subsequent steps in this process assume that you have saved two files from the Certificate Authority to the locations on the Apache Tomcat server noted for each file.Note: If you were able to download the certificate in PFX format, then proceed to Step 4 and ignore Step 5.- CA certificate
- C:\CACert.cer (/usr/CAcert.cer on Linux) or C:\signedTomcatCert.p7b (/usr/signedTomcatCert.p7b on Linux).
Note: This is also called the "root certificate."
- Signed certificate for the associated Apache Tomcat server alias
- C:\signedTomcatCert.cer (/usr/signedTomcatCert.cer on Linux)
Note: This is sometimes called the "machine certificate."
- Generate a certificate request using the keytool -certreq command with the keystore you created in the previous step:
- Import the certificate files into the Tomcat keystore.
- Import the CA certificate file into the keystore:
On Windows:
keytool -import -keystore c:\server_name.jks -trustcacerts -alias CACert -file C:\CACert.cer -storepass *****
On Linux:
keytool -import -keystore /usr/server_name.jks -trustcacerts -alias CACert -file /usr/CACert.cer -storepass *****
Note: Note the value specified for the -alias argument (CACert in this example). You will search for that value when evaluating keystore information in subsequent steps. - Import the signed Apache Tomcat certificate file for the associated server alias into the Apache Tomcat keystore:
On Windows:
keytool -import -keystore c:\server_name.jks -trustcacerts -alias server_name -file c:\signedTomcatCert.cer -storepass *****
-or-
keytool -import -keystore c:\server_name.jks -trustcacerts -alias server_name -file c:\signedTomcatCert.p7b -storepass *****
On Linux:
keytool -import -keystore /usr/server_name.jks -trustcacerts -alias server_name -file /usr/signedTomcatCert.cer -storepass *****
-or-
keytool -import -keystore /usr/server_name.jks -trustcacerts -alias server_name -file /usr/signedTomcatCert.p7b -storepass *****
Note: Note the value specified for the -alias argument (server_name in this example). You will search for that value when evaluating keystore information in subsequent steps. - Verify that the keystore file contains the certificates for the application.
On Windows:
keytool -list -keystore c:\server_name.jks -v -storepass *****
On Linux:
keytool -list -keystore /usr/server_name.jks -v -storepass *****
Tip: Search for the -alias values you specified in previous steps when importing the CA and signed Apache Tomcat certificates (in this example: CACert and server_name).Your keystore will have only two entries: one for your CAcert (Entry type:trustedCertEntry) and one for your "machine cert" (Entry type:PrivateKeyEntry).
- Import the CA certificate file into the keystore:
- Import the root certificate information into the Java VM trusted certificates (cacerts) file.
- Import the root certificate (which you imported into the tomcat keystore in Step 3.a (above) into the Java VM trusted certificates ( cacerts) file:
On Windows:
keytool -import -keystore %JAVA_HOME%\jre\lib\security\cacerts -trustcacerts -alias CACert -file c:\CACert.cerOn Linux:
keytool -import -keystore $JAVA_HOME/jdk/lib/security/cacerts -trustcacerts -alias CACert -file /usr/CACert.cerNote: When running this command:- You will be prompted to enter a password for the cacerts keystore (which might be different from the password for the c:\server_name.jks (/usr/server_name.jks on Linux) keystore file you created previously).
The default password for the cacerts keystore when you install Java is changeit. If this keystore password has been changed, consult your system administrator.
- Answer Yes when prompted to trust this certificate.
- You will be prompted to enter a password for the cacerts keystore (which might be different from the password for the c:\server_name.jks (/usr/server_name.jks on Linux) keystore file you created previously).
- Verify that the Java cacerts keystore file contains the certificates for the application.
On Windows:
keytool -list -keystore %JAVA_HOME%\jre\lib\security\cacerts -v -storepass *****On Linux:
keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts -v -storepass *****You can then search the output for the -alias you specified in previous step when importing the root certificate (in this example: CACert).
Tip: The output of this command can be quite large, so you might want to redirect the output to a text file. For example, you could append "> cacerts_list.txt" to the preceding command to redirect the certificate listing output to a cacerts_list.txt file. You then could search that file for the certificate information.
- Import the root certificate (which you imported into the tomcat keystore in Step 3.a (above) into the Java VM trusted certificates ( cacerts) file:
- If you are planning to use a PFX certificate, export the private key and certificate from the JKS store.
On Windows:
keytool -importkeystore -srckeystore c:\server_name.jks -srcstoretype JKS -srcstorepass ****** -srcalias server_name -destkeystore c:\server_name.pfx -deststoretype PKCS12 -deststorepass ***** -destalias server_nameOn Linux:
keytool –importkeystore –srckeystore /usr/server_name.jks –srcstoretype JKS –srcstorepass ****** -srcalias server_name -destkeystore /usr/server_name.pfx –deststoretype PKCS12 –deststorepass ***** -destalias server_name
- Copy server_name.jks or server_name.pfx to the conf subdirectory underneath the Apache Tomcat installation.
Typically, this directory is located:
On Windows:
C:\Program Files\Apache Software Foundation\Tomcat 7.0\conf\
On Linux:
/usr/Apache Software Foundation/Tomcat 7.0/conf/
- Configure the Apache Tomcat web application server to point to the new keystore.
- Open the server.xml file, found underneath the conf subdirectory, in a text editor.
- Insert these
keystoreFileandkeystorePasslines where indicated:On Windows (non-PFX certificate)
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="C:\Program Files\Apache Software Foundation\Tomcat 7.0 \conf\server_name.jks" keystorePass="*****" clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="false" URIEncoding="UTF-8" connectionTimeout="72000000" compression="on" compressionMinSize="10" compressableMimeType="text/html,text/xml,application/xml, text/javascript,text/css,application/x-javascript" maxHttpHeaderSize="65536" />On Linux (non-PFX certificate)
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="/usr/Apache Software Foundation/Tomcat 7.0/conf/server_name.jks" keystorePass="*****" clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="false" URIEncoding="UTF-8" connectionTimeout="72000000" compression="on" compressionMinSize="10" compressableMimeType="text/html,text/xml,application/xml, text/javascript,text/css,application/x-javascript" maxHttpHeaderSize="65536" />On Windows (PFX certificate)
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="C:\Program Files\Apache Software Foundation\Tomcat 7.0 \conf\server_name.pfx" keystorePass="*****" keystoreType="PKCS12" clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="false" URIEncoding="UTF-8" connectionTimeout="72000000" compression="on" compressionMinSize="10" compressableMimeType="text/html,text/xml,application/x ml, text/javascript,text/css,application/x-javascript" maxHttpHeaderSize="65536" />On Linux (PFX certificate)
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="/usr/Apache Software Foundation/Tomcat 7.0 /conf/server_name.pfx" keystorePass="*****" keystoreType="PKCS12" clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="false" URIEncoding="UTF-8" connectionTimeout="72000000" compression="on" compressionMinSize="10" compressableMimeType="text/html,text/xml,application/x ml, text/javascript,text/css,application/x-javascript" maxHttpHeaderSize="65536" />where ***** is the keystore password
- Comment out the section shown below:
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />For example:<!-- <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" /> -->
- Verify that the configuration changes are correct by restarting the Apache Tomcat service. You should be able to open the Apache Tomcat default web location (https://server.company.com:8443/) in a browser to see the Apache Tomcat home page.
- Enabling localhost-only access to HTTP in Tomcat SSL environments
You can enable localhost-only access to HTTP in a Tomcat SSL environment. This is supported only for the Apache Tomcat third-party web application server; it is not supported for the web application server that is bundled with SDL LiveContent Reach.