Configuring the Server for HTTPS
Modify a Tomcat server configuration file to enable an HTTPS connector and use a server-side certificate
by Jim Clune
Posted September 10, 2003
Editor's Note: This is the second of a three-part discussion on using HTTPS to implement security for Web services. The first installment, "HTTPS for Implementing Web Services Security" (Java Pro Online, September 3, 2003), began the discussion with a look at the reasons for implementing and deploying a Web service with transport-layer security, instead of message-layer security, by layering HTTP over SSL. It concluded by setting up the example of a financial institution's Web services that demonstrated deploying SOAP services over HTTPS. Here, author Jim Clune continues that discussion by turning to server-side configuration for deploying the service over HTTPS.
Deploying the service over HTTPS requires only minor modifications to the server configuration. Our example assumes you are using a server-side certificate without a client-side certificate, which is the common case in practice.
First, you need to configure Tomcat with an HTTPS connector. The SSL Config HOWTO in the Tomcat documentation provides all the related details, but I'll explain the key points and highlight some potential pitfalls. One such pitfall is that if you are using JDK 1.4 or later, JSSE is built into your SDK, but Tomcat still requires JSSE_HOME to be set.
To generate a certificate to be used by the HTTPS connector, you can use Java's keytool. Keytool generates self-signed certificates as well as Certificate Signing Requests, which are sent to a Certificate Authority. Keytool also provides utilities for managing key entries and trusted certificate entries in keystores. When you are using keytool to generate self-signed certificates, use the host name (including domain name) of the server as the common name for the certificate. An example of generating the certificate is:
keytool -genkey -alias tomcat
-keyalg RSA -keystore
server.keystore -dname
"cn=holstein.parasoft.com, ou=
Development, o=ParaSoft, c=US"
You can avoid the cryptic abbreviations by omitting the -dname flag, and keytool will prompt you for inputs. However, take heed when the interactive version prompts you with the question "What is your first and last name?" What it really means is "Enter the common name for your certificate" (this should be the host name of the target server, such as holstein.parasoft.com). It is important to ensure that the certificate's common name matches the server' s host name; the client's host name verifier will check the host name with respect to the name on the certificate, and will generally treat mismatches as untrusted certificates.
Pay special attention to which keystore your server is using. By default, Java uses the .keystore file in the user's home directory (as specified by the user.home Java system property). If you install Tomcat as an NT Service, keep in mind that the service runs as a system process (instead of a user process) by default, so it will be utilizing a different default keystore.
The Tomcat server configuration file needs to be modified to enable an HTTPS connector, which involves commenting out the default non-SSL connector and uncommenting the SSL connector:
<!-- Define a SSL Coyote
HTTP/1.1 Connector on port
8443 -->
<Connector className=
"org.apache.coyote." +
"tomcat4.CoyoteConnector"
port="8443" minProcessors=
"5" maxProcessors="75"
enableLookups="true"
acceptCount="10" debug="0"
scheme="https" secure="true"
useURIValidationHack=
"false">
<Factory className=
"org.apache.coyote." +
"tomcat4." +
"CoyoteServerSocketFactory"
clientAuth="false"
protocol="TLS" />
</Connector>
You can modify these parameters as needed. For example, you may want to switch the port to 443, which is the default port for HTTPS. It's a good idea to maintain the HTTP port for testing and debugging, but if you don't want it open on your production system, don't forget to later comment out the non-SSL connector.
WSDL Popularity
The next change involves your WSDL. If your WSDL is a static page, you will need to change the end point of the WSDL to reflect the HTTPS deployment. If you have the server dynamically generate your WSDL document based on your deployed services, the automatically generated WSDL document will always agree with your transport-layer deployment. In fact, this is one of the reasons why dynamically generated WSDL documents are becoming increasingly popular. It is surprisingly easy to make WSDL documents that do not match their services, and so anything that can be done to reduce the potential for error here is a clear win.
You can test your changes by viewing the WSDL document in a browser again, this time substituting "https" for "http" in the URL. If you have just created a self-signed certificate with keytool, your browser will not trust the certificate (and rightly so). In Internet Explorer, you will probably get a rather verbose "Security Alert" message, which indicates that there is a problem with the security certificate and provides options to proceed, abort, or view the certificate. I recommend that you view the certificate to confirm it is the one you generated, and then select "Install Certificate." If you can then view the WSDL document, you are ready to propagate your changes to the client.
In the final installment of this discussion, we'll look at generating a compatible client based on the HTTPS version of the WSDL.
About the Author
Jim Clune is a development manager for ParaSoft who supervises the development of error prevention and error detection tools for C, C++, and Web development. He began his career at ParaSoft in 1997 as a quality consultant and was quickly promoted to software engineer where he had a hands-on influence on the development of ParaSoft's products. He holds a BS in engineering from Harvey Mudd College and an MS in applied computer science and technology with an emphasis in technical programming from Azusa Pacific University. Clune is well versed in Windows, UNIX (including Linux), and Mac systems. He specializes in C/C++, Visual Basic AML, and PLC ladder logic languages.
Back to top
|