Web21C SDK: do less achieve more

How to Configure Tomcat to Allow SSL Requests

IMPORTANT NOTE: This How-to refers to usage of JSSE, that comes included with jdk 1.5 and higher. If you have JDK below 1.4, you need to install Java Secure Socket Extensions (JSSE)
This How-to also uses tomcat as the default web application server

The description below uses the variable name $CATALINA_HOME to refer to the directory into which you have installed Tomcat 6, and is the base directory against which most relative paths are resolved. However, if you have configured Tomcat 6 for multiple instances by setting a CATALINA_BASE directory, you should use $CATALINA_BASE instead of $CATALINA_HOME for each of these references.

Configure

  • Find your .pfx/.pem file that was created when you registered your application with the web21c SDK, you will need this later.
  • Open server.xml in $CATALINA_HOME\conf folder. (Default path is: C:\Program Files\Apache Software Foundation\Tomcat 5.5\conf)
  • Uncomment the paragraph below this line 
    <!- - Define a SSL HTTP/1.1 Connector on port 8443 - ->.
(By removing <!- - and - -> tags below the line)
  • Add 3 new attributes to the Connector element:
    If you created a .pfx file add these keystoreType="PKCS12" keystoreFile="<Path to your .pfx file>" keystorePass="<application password>" 
    <Connector port="8443" minSpareThreads="5" maxSpareThreads="75"
    enableLookups="true" disableUploadTimeout="true"
    acceptCount="100"  maxThreads="200"
    scheme="https" secure="true" SSLEnabled="true"
    keystoreType="PKCS12" keystoreFile="D:/ExampleApplication_Sandbox.pfx" 
    keystorePass="xxxxx"
            clientAuth="false" sslProtocol="TLS"/>

    If you created a .pem file add these keystoreType="PKCS8" keystoreFile="<Path to your .pem file>" keystorePass="<application password>" 
    <Connector port="8443" minSpareThreads="5" maxSpareThreads="75
    enableLookups="true" disableUploadTimeout="true"
    acceptCount="100"  maxThreads="200"
    scheme="https" secure="true" SSLEnabled="true"
    keystoreType="PKCS8" keystoreFile="D:/ExampleApplication_Sandbox.pem" 
    keystorePass="xxxxx"
            clientAuth="false" sslProtocol="TLS"/>
  • Change port to 443 if you want to access a page from https:// without specifies port after hostname. 
    <Connector
    port="443" minSpareThreads="5" maxSpareThreads="75"
    enableLookups="true" disableUploadTimeout="true"
    acceptCount="100"  maxThreads="200"
    scheme="https" secure="true" SSLEnabled="true"
    keystoreType="PKCS12" keystoreFile="D:/ExampleApplication_Sandbox.pfx"
    keystorePass="xxxxx"
        clientAuth="false" sslProtocol="TLS"/>

Test

  • Open browser and navigate to the Apache Tomcat server with https:// prefix

browser https address
(click image to see full size)

  • There will be a pop-up window show about security alert, click Yes.

certificate alert dialog box
(click image to see full size)

  • When you see Apache Tomcat's default page, that's means you have successfully enabled SSL on the server. Congratulations.
  • Also, you will notice there is a key icon on the bottom right of your browser.

lock symbol in browser
(click image to see full size)

How should I configure server.xml (or other things) to use different certificates with different web apps?

If you want more than one cert, you need more than one port listening for HTTPS requests, each with the appropriate cert configured.

So for example if I have two applications (ExampleApplication_Sandbox, ExampleApplication_Production) each with their own certificate then I would need two entries in the server.xml file.

<Connector port="8443" minSpareThreads="5" maxSpareThreads="75"
        enableLookups="true" disableUploadTimeout="true"
        acceptCount="100"  maxThreads="200"
        scheme="https" secure="true" SSLEnabled="true"
        keystoreType="PKCS12" keystoreFile="D:/ExampleApplication_Sandbox.pfx" 
        keystorePass="xxxxx"
        clientAuth="false" sslProtocol="TLS"/>

<Connector port="8444" minSpareThreads="5" maxSpareThreads="75"
        enableLookups="true" disableUploadTimeout="true"
        acceptCount="100"  maxThreads="200"
        scheme="https" secure="true" SSLEnabled="true"
        keystoreType="PKCS12" keystoreFile="D:/ExampleApplication_Production.pfx" 
        keystorePass="xxxxx"
        clientAuth="false" sslProtocol="TLS"/>

So the endpoint for the two applications would be