email article printer friendly

Configuring the Client for HTTPS
See how to employ the WSDL2Java tool to generate a compatible client that is configured for a Web service's transport-layer security
by Jim Clune

Posted September 17, 2003

The easiest way to build a compatible client is to generate it based on the HTTPS version of the WSDL. In Axis, you can do this with the WSDL2Java tool. However, when you provide this tool with the URL for the WSDL, the connection will initially fail because your newly created certificate is not a trusted certificate for WSDL2Java. Consequently, you need to tend to keystores again before you regenerate client code.

I highly recommend using two completely separate keystores for the client and the server, even if you are initially testing your client on the very machine where the service is deployed. This strategy allows you to have one keystore contain the key entry for your generated certificate and another keystore contain the trusted certificate entry for that same certificate. Export the certificate from your server keystore to a file, and import this file into a new keystore as a trusted certificate. At this point, you are ready to specify your new keystore for your client code generation:

java -Djavax.net.ssl.trustStore=
  c:\client.keystore org.apache.
  axis.wsdl.WSDL2Java 
  https://holstein.parasoft.
  com:8443/axis/Account.jws?wsdl

If the keystore does not specify the certificate as trusted, then you can expect WSDL2Java to throw an exception such as javax.net.ssl.SSLHandshakeException. If you have already viewed your HTTPS WSDL in your browser, then you know that the problem is on the client side, and it is most likely related to the keystore.

After the client code is regenerated and ready to run, remember to specify the keystore for the client as well. You can use the same keystore you used for WSDL2Java, specifying it through the javax.net.ssl.trustStore Java property. When your client accesses the service, there are several ways that it can access the same server through different host names. For example, from my machine, I can access my local server as holstein.parasoft.com, holstein, localhost, and 127.0.0.1. Although these hosts are equivalent from an HTTP standpoint, they are not equivalent for HTTPS because the client-side host name verifier checks the certificate's common name against the host name from the URL. If these names don't match, the client will treat the certificate as untrusted unless an alternative host name verifier is installed.

Deploying Web services with transport-layer security is conceptually straightforward, but attention to the details is critical for success. When you need to use security with Web services, be sure to allow sufficient time to debug any configuration complications that arise in both servers and clients.

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.