Two-way SSL connection with Tomcat and OC4J

Hey, hungry for security knowledge children, how are you doin’ these days ?

Today I’ll show something really helpful. I guess someday you will have deal with the secure connection with some of the servlet containers. I can assure you, it’s not that scary, but simple and interesting, though. Anyway, let’s start:

First of all, let’s give a light on the types of SSL authentication:

• One-way SSL authentication

• One-way SSL authentication enables the application operating as SSL client to verify the identity of the application operating as the SSL server.

• Two-way SSL authentication

• In the two-way SSL authentication, the SSL client application verifies the identity of the SSL server application and then the SSL server application verifies the identity of the SSL client application.

It’s easy, isn’t it ?

Okay, now (when you know the types of SSL authentication) I can show you how to configure a two-way SSL authentication with Tomcat and OC4J:

To do so, you should edit some stuff in the configuration dirs of these servlet containers. If you’re using OC4J with JDeveloper10, you should open < JDeveloper-installation-dir >/jdev/system10.1.2.0.0.1811/oc4j-config. Otherwise, if you’re using a standalone OC4J server, you will have to find the oc4j-config folder in its installation dir. I guess I won’t be a problem for you. As for Tomcat, the important dir is < Tomcat-installation-dir >/conf.

Now, you have to edit some of the configuration xmls.

• server.xml (OC4J)

• Find the row with a similar statement:

• <web-site default=”true” path=”./default-web-site.xml” />

and replace it with this one:

<web-site path=”./secure-web-site.xml” default=”true” />

…after your work with the server.xml is completed.

Actually, if you list the oc4j-config dir, propably you’ll notice that there is no such file, named ‘secure-web-site.xml’. If there is such, open it for editing. Otherwise, create one.

secure-web-site.xml should contain these few lines:

<!DOCTYPE web-site PUBLIC "Oracle9iAS XML Web-site" "https://xmlns.oracle.com/ias/dtds/web-site.dtd">

<web-site secure="true" port="8443" protocol="https">

<default-web-app application="default" name="defaultWebApp"/>

<access-log path="./log/default-web-access.log"/>

<ssl-config keystore="./keystore" keystore-password="123456" needs-client-auth="true"/>

</web-site>

 Note there is tag, named <ssl-config … />:

It contains several things: where is the keystore of the server certificates, the password for the keystore and and attribute (needs-client-auth), which represent whether or not the server application will require SSL authentication from the clients. In your case (don’t forget we’re establishing two-way SSL connection), you should give it the value of ‘true’, which means that your server will require client certificates when there is an attempt to reach an application at port 8443. Be careful where you’re placing the ‘keystore’ file, also.

• server.xml (Tomcat)

• Open the server.xml of Tomcat and create another connector..:

• <Connector

•    port=”8443″ maxThreads=”200″

•    scheme=”https” secure=”true” SSLEnabled=”true”

•    keystoreFile=”./keystore” keystorePass=”123456″

•    clientAuth=”false” sslProtocol=”TLS”/>

• …and you’re done!

• It very similar to the configuration of the OC4J application server, I think. And it is !

No matter we’re giving a route to a ‘keystore’ file, currenly we don’t have any. So , let’s make one!

How’s that done ? Open a terminal … (there is such thing in Windows, too, so don’t panic!). After you open a terminal, set the current directory to the config dir of the servlet container.

After that, type the following:

keytool -geykey -alias server -keyalg RSA -keystore keystore -validity 60

If an error occurs, check out if you have configured a JAVA_HOME environment variable and you haven’t, configure such and add it to the PATH variable.

But if everything is just fine, the keytool (which is part of JDK, you should know that) will ask you for a password (which is ‘123456’, as stated in the secure-web-site.xml file). Then, you will be asked a several questions. The first one is the most important: What is your first and last name ? Don’t be misled and don’t type your names. You should type the domain name or the IP address of the server – actually, you should type the name, by which your server will be accessed by the clients (localhost, ip-address, www.something.com, etc.). For instance, I wrote my IP address, ’cause when the clients wish to access my server, they should type this IP address in their browsers (and they should be in my local network, which is other theme of discussion).

How you will answer the other questions is not that important. You can type anything or type nothing, if you wish.

After you’re done with the questions, a file named keystore should have appeared in the config directory of your servlet container. It’s good to know that this file has a JKS file format and cannot be displayed by a simple text editor. But, it content is very simple, though. It’s full of key-value pairs, where the keys are some unique names (strings) for the trusted certificates and the values are the MD5 signatures of the trusted certificates. Currently, your keystore contains only one key-value pair, denoting the certificate with which the server will identificate itself to the client applications.

Let’s export this certificate to a single file:

keytool -export -alias server -file server.cer -keystore keystore

Now, a file named server.cer should have appeared. You will need it later, so don’t do anything with it now.

It’s time to make a client keystore now:

keytool -genkey -alias client -keyalg RSA -storetype PKCS12 -keystore client.p12

As you may guess, a file named client.p12 has appeared. Cool, isn’t it ?

Now, analogously, you should export the certificate in a single file:

keytool -export -alias client -keystore client.p12 -storetype PKCS12 -rfc -file client.cer

…and then you have to import the exported file in the truststore (keystore) of the server:

keytool -import -alias client -keystore keystore -file client.cer

So, what have you done till now ? Your server has a keystore with two entries – the one for the certificate with which it will authenticate itself, and the other – the certificate with which client will authenticate themselves to the server. Any other certificates will be ingored (since they don’t exist in the truststore), at this time.

Now, let configure your browser. Firefox, actually.

There is no way I can guess the version of Firefox you’re using, but the thing is you have to find where in the options of the browser are the certificates configured.

Find where you can import your own certificates and import the client.p12 file you made earlier.

After that, your browser has to start trusting your server, which means you have to import the server.cer to the browser trusted servers (which can be done in the options menu again).

You’re almost done. Start the servlet container and the type in Firefox the address you have stated as first and last name (in the keytool questionnaire, as you can remember) and don’t forget to point the port (in this case – 8443).

If everything is fine, you should accept the server certificate after which a propmt will appear, asking you to choose from a list of certificates in your browser, which the server trusts. After choosing the recently imported client certificate in the browser, and clicking “OK”, the application should be opened in a two-way security connection.

It’s possible some errors like certificate_unknown_error to occur, which means that you haven’t configured your browsed to trust the server properly.

I hope the tutorial was useful to you. If you did it well and successfully opened you application in https, you have successfully made another step in the security mastering. 🙂

K.