Configure Tomcat for HTTPS (HTTP Secure)

Configuring and Installing Optional Components › Configuration Tasks for Optional Base Components › How to Install and Configure CA OPS/MVS RESTful Web Services › Configure Tomcat for HTTPS (HTTP Secure)

Configure Tomcat for HTTPS (HTTP Secure)

You can optionally configure your Tomcat server to use HTTPS instead of HTTP for user access. Because HTTPS includes SSL encryption, this option alleviates concerns about exposing the data in clear text on the network.

Apache Tomcat is an Open-source third-party product. Apache provides documentation to help you configure SSL for Tomcat with the Apache Tomcat SSL Configuration HOW-TO. You can use the Apache Tomcat HTTP Connector Reference to look up the definitions of the configuration properties that the HOW-TO document utilizes. You can also find other web tutorials that describe the configuration. Locate and follow the steps that are appropriate for the version of Apache Tomcat that your CA OPS/MVS release installed. There are three methods that you can use for your keystore file.

Method 1: Use an existing trusted certificate

Follow this step:

Use the keytool program to create the keystores, truststores, and certificates to achieve your desired security configuration.
Note: For more information about trusted certificates, see the Apache Tomcat 7.0 on the Web (Apache Tomcat 7.0 SSL Configuration HOW-TO).

Method 2: Create and use your own self-signed certificate
Follow these steps:

Select the appropriate method to create a keystore that contains a self-signed certificate:
Execute the sample scripts that are provided in the {CCS_installation_dir}/OPS/distrib directory.
For example:
- Execute makeks script from USS command line (TSO OMVS).
  How to use OMVS (enter the following commands under TSO or ISPF):
```
OMVS
cd {CCS_installation_dir}/OPS/distrib
makeks
```
- Execute the listks script to verify that you created .keystore successfully.
- (Optional) Execute "ls -la" to view that .keystore file.
Copy file .keystore file from {CCS_installation_dir}/OPS/distrib to your {CCS_installation_dir}/OPS/tomcat/conf.
Save the full path to the .keystore file under {CCS_installation_dir}/OPS/tomcat/conf. You have to specify this path later on the keystoreFile keyword that server.xml specifies.
Note: The JCL job [hlq].OPS.CCLXCNTL(OPWBSVMK) lets you execute the makeks and listks scripts in a batch environment. You must customize this JCL before it is submitted at your site.

Method 3: Complete the following steps to generate a keystore containing a self-signed certificate manually
Follow these steps:

Enter the following command from the USS command line (OMVS):

cd {CCS_installation_dir}/OPS/distrib
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore .keystore

A series of prompts appears:

Specify a password, press Enter, and answer the following questions:

Remember the password that you specify here.
We recommend that you use the z/OS hostname where Tomcat runs for the CN value (common name), so that if you are prompted to accept the certificate, it is clear which server sent the prompt.

A keystore is created in your keystore directory with one self-signed certificate inside. The actual filename is .keystore.

For example:

Enter keystore password: tomcat 
Re-enter new password: tomcat
What is your first and last name? 
  [Unknown]:  localhost
What is the name of your organizational unit? 
  [Unknown]:  CA
What is the name of your organization? 
  [Unknown]:  CA 
What is the name of your City or Locality? 
  [Unknown]:  Pittsburgh 
What is the name of your State or Province? 
  [Unknown]:  PA
What is the two-letter country code for this unit? 
  [Unknown]:  US 
Is CN=localhost, OU=CA, O=CA, L=Pittsburgh, ST=PA, C=US correct?

After you use one of the three methods, continue with the following steps and complete the Tomcat configuration:

(Optional) Enter the following command from the USS command line (OMVS) and verify the contents of your keystore:

cd {CCS_installation_dir}/OPS/distrib

$JAVA_HOME/bin/keytool -list -keystore .keystore

The results appear like the following example:

Enter keystore password:
Keystore type: jks
Keystore provider: IBMJCE
Your keystore contains 1 entry

Alias name: tomcat
Creation date: Feb 3, 2014
Entry type: keyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=tomcat, OU=CA, O=CA, L=Pittsburgh, ST=PA, C=US
Issuer: CN=tomcat, OU=CA, O=CA, L=Pittsburgh, ST=PA, C=US
Serial number: 114822b8
Valid from: 2/3/14 8:15 AM until: 5/4/14 9:15 AM
...

Within the Tomcat server.xml configuration file, modify the Connector element which has port="8443".
This port is the TLS connector. Specify a keystore file and a keystore password.
1. Update the Apache Tomcat configuration parameters in the server.xml file as follows:
  - If you use the Tomcat that CA Common Services distributed, you can locate the server.xml configuration file under {CCS_installation_dir}/OPS/tomcat/conf.
  - If you use your own Tomcat server, you can locate the server.xml configuration file under {tomcat_home}/conf.
  - Understand that server.xml is an ASCII file. As such, you must use ISPF 3.17 to edit server.xml.
  A typical connector element for an SSL port appears like the following example:
```
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
	maxThreads="150" scheme="https" secure="true"
	clientAuth="false" sslProtocol="TLS" />
```
  Important! You must uncomment this connector element if it is commented. Comment blocks are defined in this file by a starting token of “
2. Add the keystoreFile and keystorePassword keywords as follows:
  Figure 1
```
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS"
    sslEnabledProtocols=”TLSv1.2,TLSv1.1,TLSv1″
    keystorePass="tomcat"
    keystoreFile="{CCS_installation_dir)/OPS/distrib/.keystore"
/>
```
  We also recommend that you disable SSLv3 in your Internet browser and on your web clients before connecting to CA OPS/MVS web services. Disabling SSLv3 on either client side or server side will mitigate the vulnerability to cyber-attack due to recent compromises with the SSLv3 protocol.
  
  Note: To avoid the potential for cyber-attack, we recommend that you disable SSLv3 in your Apache Tomcat web server. Specify the sslEnabledProtocols attribute (see Figure 1) with only the TLS protocols listed. This step avoids usage of the older SSL protocols. You can find documentation about the sslEnabledProtocols attribute in the JVM documentation under method SSLSocket.setEnabledProtocols(). See the Oracle JDK documentation for Java 7 or Java 8.
  
  If you want to use client certificate authentication, follow these basic steps:
  - Generate a self-signed server-certificate on the server (Tomcat host).
  - Download the server-certificate to the client.
  - Import the server-certificate to the Java-keystore of the client.
  - Generate a self-signed client-certificate on the client.
  - Upload it to the server.
  - Import the client-certificate to the Java-keystore of the Tomcat server.
  - Configure Tomcat to use this keystore.
  - If you want to ensure that the client connections are also authorized by certificate, set clientAuth="true" in server.xml.
  Note: For specific details about accomplishing these tasks, see the Apache Tomcat 7.0 SSL Configuration HOW-TO Java™ Secure Socket Extension (JSSE) Reference Guide.

Add the following lines before </web-app> at the end of the web.xml file that is located in {tomcat_dir}/conf:

<security-constraint>

<web-resource-collection>
	<web-resource-name>Tomcat</web-resource-name>
	<url-pattern>*.html</url-pattern>
</web-resource-collection>
<user-data-constraint>
	<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>

</security-constraint>

After you restart Tomcat, you now have access to your URIs over both a Secured connection and with an unencrypted connection.
- Test your secure connection by specifying URIs with the HTTPS network scheme and the 8443 port.
- For example, use this format: https://your-host:8443/opsmvs/web/tables (substituting your own hostname for your-host).
This test assumes that you retained the default TLS port number of 8443.
(Optional) After you tested your secured connection successfully, you can disable (comment out) the unencrypted Connector element, which has port 8080. This procedure prevents Tomcat from serving any requests over the unencrypted connection.