Configuring SSL

When you configure SSL (secure socket layer) for tc Server, you can use one of the following frameworks:

The following snippet of a sample server.xml file builds on the simple out-of-the-box configuration file by adding SSL capabilities to tc Server so that users can make a secure connection to deployed applications using HTTPS. You add SSL to tc Server by adding a <Connector> child XML element of the <Service> element, alongside the existing connector that configures the non-SSL-enabled HTTP port. This new connector is configured for a different TCP/IP port than the regular non-SSL port; users who specify the SSL port enable SSL handshake, encryption, and decryption during their connection.

See the CATALINA_BASE/conf/samples/server-with-ssl.xml file for an actual product sample, where CATALINA_BASE refers to the tc Server instance directory.

See Description of the SSL Connector for detailed information about this new <Connector> element. This XML snippet uses the SSL framework provided by JSSE; for an example of a connector that uses APR, see Using an APR Connector to Configure SSL.

<Connector
        executor="tomcatThreadPool"
        port="8443"
        protocol="HTTP/1.1"
        connectionTimeout="20000"
        redirectPort="8443"
        acceptCount="100"
        maxKeepAliveRequests="15"
        keystoreFile="${catalina.base}/conf/tcserver.keystore"
        keystorePass="changeme"
        keyAlias="tcserver"
        SSLEnabled="true"
        scheme="https"
        secure="true"/>

Description of the SSL Connector

In the preceding snippet of server.xml that describes a new SSL-enabled <Connector> that uses the JSSE libraries included in the JDK:

For complete documentation about configuring SSL for tc Server servers, see SSL Configuration HOW-TO.

For general documentation about the tc Server server.xml file and all the possible XML elements you can include, see Apache Tomcat Configuration Reference.

Using an APR Connector to Configure SSL

When you use an APR connector to specify a secure tc Server port, tc Server automatically uses the OpenSSL framework which means that you will be using an SSL engine native to your platform rather than the one included in JSSE.

Before configuring the connector, you must first add the APR listener to your server.xml file using the <Listener> element:

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />

The preceding element initializes the native SSL engine, then enables the use of this engine in the connector using the SSLEnabled attribute, as shown in the following sample <Connector>:

<Connector
           executor="tomcatThreadPool"
           port="8443"
           protocol="org.apache.coyote.http11.Http11AprProtocol"
           connectionTimeout="20000"
           redirectPort="8443"
           acceptCount="100"
           maxKeepAliveRequests="15"
           SSLCertificateFile="${catalina.base}/conf/tcserver.crt"
           SSLCertificateKeyFile="${catalina.base}/conf/tcserver.key"
           SSLPassword="changeme"
           SSLEnabled="true"
           scheme="https"
           secure="true"/>

This connector configuration is similar to the one that uses the JSSE SSL libraries, as described in Description of the SSL Connector, but with the following differences, mostly having to do with the configuration of OpenSSL:

See Apache Portable Runtime (APR) based Native library for Tomcatfor additional information about APR and how to configure an APR HTTPS connector.

Creating a Simple Keystore File

When you configure SSL for tc Server, you must provide a keystore that contains certificates and public keys. The certificate identifies the company and verifies the public key. Clients that connect to tc Server use the public key to encrypt and decrypt data transferred over the wire.

Your keystore can use self-signed certificates which, although they do not guarantee they are authentic, can be used by both the clients and server to encrypt and decrypt data. You can use the keytool JDK tool to create a keystore that contains self-signed certificates, as shown below. If you actually require a certificate that is truly authentic and verified, then you must purchase one from a well-known Certificate Authority such as VeriSign. You can then use the keytool tool to import the certificate into your keystore.

To use the keytool tool to create a keystore that contains self-signed certificates, run the following command:

prompt> $JAVA_HOME/bin/keytool -genkey -alias alias -keyalg RSA -keystore keystore 

Be sure that the value of the -alias option matches the value of the keyAlias attribute of the secure Connector you configured in the server.xml file, as described in the preceding section. Similarly, the value of the -keystore option should match the name keystoreFile attribute. For example:

prompt> $JAVA_HOME/bin/keytool -genkey -alias tcserver -keyalg RSA -keystore /apache/tomcat6/conf/tcserver.keystore 

In the example, CATALINA_BASE is assumed to be /apache/tomcat6.

The tool will ask first ask you for a keystore password; be sure this matches the keystorePass attribute of the <Connector> element that configures the secure port, as described in the preceding section. The tool then asks for information about your company; enter as appropriate. Finally, the tool asks for the password for the keystore alias; you should set this to the save value as the keystore password.

See SSL Configuration HOW-TO for complete documentation about creating keystores, in particular how to import a fully authentic certificate into an existing keystore.