4.4 Configuring SSL

4.4 Configuring SSL
Prev	4. Configuring a tc Runtime Instance Manually	Next

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

The SSL framework provided by Java SE Security (JSSE), which is included in the JDK and available to you by default.
OpenSSL, which is what tc Runtime uses when you use the Apache Portable Runtime (APR) library. APR libraries provide a predictable and consistent interface to underlying platform-specific implementations. Use of APR provides superior scalability, performance, and better integration with native server technologies. The APR libraries are usually installed by default on Unix versions of tc Runtime; you must download the libraries for other platforms.

tc Server includes templates that make it simple to configure a tc Runtime instance with SSL when you create the instance. Choose one of the SSL templates—apr-ssl, bio-ssl, or nio-ssl—based on the type of I/O you want to use. You can also use the jmx-ssl template to configure SSL for the JMX connector. See "Creating a Runtime Instance with a Template" in Getting Started with tc Server for help using the templates.

The following snippet of a sample server.xml file is equivalent to using the bio-ssl template to create an instance. It builds on the simple out-of-the-box configuration file by adding SSL capabilities to tc Runtime so that users can make a secure connection to deployed applications over HTTPS. Add SSL to tc Runtime by adding a <Connector> child XML element to 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 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

The preceding snippet of server.xml describes a new SSL-enabled <Connector> that uses the JSSE libraries included in the JDK. The attribute values in the example function as follows:

executor, protocol, connectionTimeout, maxKeepAliveRequests, acceptCount. Same attributes as those of the basic HTTP connector. Although this connector is used for HTTPS connections, you still set protocol to HTTP/1.1; other attributes specify an SSL-enabled connection.
port. The TCP/IP port that users specify as the secure connection port is 8443. Set the value of the redirectPort attribute of your non-SSL connectors to this value to ensure that users who require a secure connection are redirected to the secure port, even if they initially start at the non-secure port.
SSLEnabled. Specifies that SSL is enabled for this connector.
secure. If set to true, ensures that a call to request.isSecure() from the connecting client always returns true. Default is false.
scheme. If set to https, ensures that a call to request.getScheme() from the connecting client returns https when clients use this connector. The default value of this attribute is http.
keystoreFile. Name of the file that contains the server's private key and public certificate used in the SSL handshake, encryption, and decryption. You use an alias and password to access this information. In the example, this file is called tcserver.keystore and is located in the same directory as the standard tc Runtime configuration files: CATALINA_BASE/conf.
See Creating a Simple Keystore File for information about creating they keystore file.
keyAlias and keystorePass. Alias and password to access the keystore specified by the keystoreFile attribute. In the example, the alias is tcserver and the password is changeme.

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

For general documentation about the tc Runtime 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 Runtime port, tc Runtime uses the OpenSSL framework, meaning that you will be using an SSL engine native to your platform rather than the one included in JSSE. Use the apr-ssl template with tcruntime-instance script to create a tc Runtime instance configured to use OpenSSL. This section describes configuration changes that are made for you when you use the apr-ssl template.

Before configuring the connector, add the APR listener to your server.xml file in the <Listener> element:

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

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

<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:

The value of the protocol attribute is org.apache.coyote.http11.Http11AprProtocol, rather than HTTP/1.1, to indicate that the connector is using the APR libraries.
The SSLCertificateFile attribute specifies the name of the file that contains the server certificate. The format is PEM-encoded. In the example, this file is called tcserver.crt, and is located in the conf directory under the CATALINA_BASE directory in which your tc Runtime instance is installed.
The SSLCertificateKeyFile attribute specifies the name of the file that contains the server private key. The format is PEM-encoded. In the example, the file is called tcserver.keyand is located in the same directory as the certificate file.
The SSLPassword attribute specifies the password for the encrypted private key in the file pointed to by the SSLCertificateKeyFile attribute.
The preceding attributes are used instead of the keystoreFile, keystorePass, and keyAlias attributes of the JSSE secure connector.

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

Creating a Simple Keystore File For Both SSL and OpenSSL

Configuring SSL or OpenSSL for tc Runtime requires a keystore that contains certificates and public keys. The certificate identifies the company or organization and verifies the public key. Clients that connect to tc Runtime use the public key to encrypt and decrypt data transferred over the wire.

Warning: The tc Server installation includes sample keystores, key files, and certificates. Note that they are provided only to aid testing and debugging; they are not for production use. You must replace them with your own generated keystores and certificates before moving to a production system.

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

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

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

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 value of the 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.

A message asks for a keystore password; this password must match the keystorePass attribute of the <Connector> element that configures the secure port, as described in the preceding section. After prompts for information about your company, a message requests the password for the keystore alias; set this to the same value as the keystore password.

Prev	Up	Next
4.3 Setting Up a High-Concurrency JDBC Datasource	Home	4.5 Using the Apache Portable Runtime (APR)