Set up secure web service with Tomcat and Apache

Pascal Botte

pascalbotte.be
Basic of web service security by hand

Copyright © 2006 by BOTTE Pascal

Abstract

Configure Tomcat with SSL to use secure web services isn't so difficult. You can even sign yourself your certificate, follow me...

Document created: 2006/05/04


Table of Contents
1. SSL and https configuration for Tomcat
1.1. SSL on the server-side
1.2. About certificates
2. How to create your own CA (Certificate Authority) for Tomcat
2.1. Why a CA?
3. Create and sign your server certificate
3.1. Creation of the server certificate
3.2. Test your SSL connection
4. Client authentication
4.1. Client certificate creation and signing
4.2. Export client certificate as keychain in pkcs12/java keystore
5. Tomcat client authentication: server and browser configuration
5.1. Create and populate a trust-store for Tomcat
5.2. Import a pkcs12 client-certificate into your browser
SSL index

1. SSL and https configuration for Tomcat

We start here with the Tomcat configuration, following this article you should be able to start Tomcat using SSL, server authentication and connect with your web browser, using https, on the end point interface of a secure web service. The first step is to have Tomcat up and running on port 80 or 8080 with a web service configured for public http request. See my web service at my home page (not 24/24 on-line, sorry). Once this step is working you have few change to make on an usual JAX-RPC SOAP client to consume this web service using https.

1.1. SSL on the server-side

The first think to do is to configure a new connector in Tomcat, in fact an SSL [1] connector. An SSL connector will be used to listen for https request on a specific port on your server. In the example below you will find a template connector for Tomcat. You can copy/paste and adapt in your server configuration file or use your Tomcat Administration interface to generate an https connector.

Example 1. SSL Tomcat connector

Begin with a stop of your Tomcat web server and make a copy of your server.xml configuration file. Only after that you can edit and change your server configuration file. Add the following connector just below the other(s) already there. I assume here you have a web server like Apache or IIS configured on port 80. And your Tomcat server is listening on port 8080 for http request. The following connector will be configured on port 8443 using secure HTTPS method. Alternatively, if you have only Tomcat already listening on port 80 for classic http you can configure the SSL connector on port 443 for the secure connection.

<Connector className="org.apache.coyote.tomcat5.CoyoteConnector" acceptCount="10" bufferSize="2048" clientAuth="false" 
  compression="off" connectionLinger="-1" connectionTimeout="60000" connectionUploadTimeout="300000" debug="0" 
  disableUploadTimeout="false" enableLookups="true" keepAlive="true" 
  keystoreFile="your_path_to/server.jks" keystorePass="your_keystore_password" maxKeepAliveRequests="100" 
  maxProcessors="20" minProcessors="5" port="8443" protocol="HTTP/1.1" 
  protocolHandlerClassName="org.apache.coyote.http11.Http11Protocol" proxyPort="0" redirectPort="-1" 
  scheme="https" secure="true" serverSocketTimeout="0" sslProtocol="TLS" tcpNoDelay="true" 
  tomcatAuthentication="true" xpoweredBy="false">
    <Factory className="org.apache.coyote.tomcat5.CoyoteServerSocketFactory" clientAuth="false" 
      keystoreFile="your_path_to/server.jks" keystorePass="your_password" keystoreType="JKS" 
      protocol="TLS" randomFile="/root/random.pem" rootFile="/root/root.pem"/>
</Connector>

In order to be able to start our Tomcat web server, we need to create some file and password to use server authentication:

server.jks

This file will hold our server certificate (private and public key) used on the server-side to encrypt a message with the private key and let the client decrypt this message with the public key.

Keystore password

The password allowing the server to access the private and public key stored in server.jks.

Next section we will describe a way to create a server certificate for use with Tomcat. I will cover the server-authentication case first. So only the server need to have a private key (kept secret on the server) and a public key (sent to the client) allowing the client to decrypt the received message. The client will need to trust the public key received by comparing it with a trust-store (a keystore file on the client-side) containing only the public key commonly called: certificate.

1.2. About certificates

We need now to create a server-certificate. We can do that easily using the keytool tool shipped with the java sdk. But we have first to understand how certificate and authentication work under SSL.

Usually, once you have created, with keytool, your keystore containing private and public key, you need to generate a certificate signing request. This "csr" will be sent to a Certificate Authority (CA). This CA will digitally sign your csr and sent it back to you. At this point, you have to import your signed certificate into your keystore and your server can start to use it.

The purpouse to have your certificate signed by a CA is very simple: only the CA are registered in the browsers. And therefore all the certificates signed by an officially CA will be automatically trusted by browsers. And because of that your SOAP client need a trust-store containing either the server-certificate (signed or not), or if it is signed (by a CA) only the CA certificate (the public key of the CA).

Notes

[1]

SSL: secure socket layer

  Next ->
  How to create your own CA (Certificate Authority) for Tomcat