TLS Support

(A.k.a. SSL.) The instructions in this document are liable to change at any time. In particular, we will be changing the method to supply the server-side certificate password.

Requirements

Encrypting your JDBC connection

At this time, only 1-way, server-cert encryption is tested.

CLIENT-SIDE

Just use one of the following protocol prefixes.

At this time, the latter will only work for clients running with Java 1.4.

If the server you wish to connect to is using a certificate approved by your default trust keystores, then there is nothing else to do. If not, then you need to tell Java to "trust" the server cert.

First, you need to obtain the cert (only the "public" part of it). Since this cert is passed to all clients, you could obtain it by writing a java client that dumps it to file, or perhaps by using openssl s_client. Since in most cases, if you want to trust a non-commercial cert, you probably have access to the server keystore, I'll show an example of how to get what you need from the server-side JKS keystore.

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

What you need is the file server.cer. Now, you need to add this cert to one of the system trust keystores or to a keystore of your own. See the Customizing Stores section in JSSERefGuide.html to see where your system trust keystores are. You can put private keystores anywhere you want to. The following command will add the cert to an existing keystore, or create a new keystore if "client.store" doesn't exist.

keytool -import -trustcacerts -keystore trust.store -alias new_alias -file server.cer

Unless your OS can't stop other people from writing to your files, you probably do not want to set a password on the trust keystore.

If you added the cert to a system trust store, then you are finished. Otherwise, you will need to set the sytem property javax.net.ssl.trustStore every time that you run your client program. For example

java -cp /path/to/hsqldb.jar -Djavax.net.ssl.trustStore=/home/blaine/trust.store org.hsqldb.util.DatabaseManager

N.b. The hostname in your database URL must match the Common Name of the server's certificate exactly. That means that if a site certificate is admc.com, you can not use jdbc:hsqldb:hsqls://localhost or jdbc:hsqldb:hsqls://www.admc.com:1100 to connect to it.

If you want more details on anything, see JSSERefGuide.html on Sun's site, or in the subdirectory docs/guide/security/jsse of your Java SE docs.

SERVER-SIDE

Get yourself a JKS keystore containing a private key. Then set the system property javax.net.ssl.keyStore to the path to that file, and javax.net.ssl.keyStorePassword to the password of the keystore (and to the private key-- they have to be the same). Example

java -Djavax.net.ssl.keyStorePassword=secret -Djavax.net.ssl.keyStore=/usr/hsqldb/db/db3/server.store -cp /path/to/hsqldb.jar org.hsqldb.Server -port 9005 -database /usr/hsqldb/db/db3/db3

Note that specifying a password on the command-line is definitely not secure. It's really only appropriate when untrusted users do not have any access to your computer. Before long, we will have a more secure way to give the password.

JSSE

If you are running Java 4.x, then you are all set. Java 1.x users, you are on your own (Sun does not provide a JSSE that will work with 1.x). Java 2.x and 3.x users continue...

Go to http://java.sun.com/products/jsse/index-103.html. If you agree to the terms and meet the requirements, download the domestic or global JSSE software. All you from the software is the three jar files. If you have a JDK installation, then move the 3 jar files into the directory $JAVA_HOME/jre/lib/ext. If you have a JRE installation, then move the 3 jar files into the directory $JAVA_HOME/lib/ext.

Pretty painless.

Making a Private-key Keystore

There are two main ways to do this. Either you can use a certificate signed by a certificate authority, or you can make your own. One thing that you need to know in both cases is, the Common Name of the cert has to be the exact hostname that JDBC clients will use in their database URL.

CA-SIGNED CERT

I'm not going to tell you how to get a CA-signed SSL certificate. That is well documented at many other places.

Assuming that you have a standard pem-style private key certificate, here's how you can use openssl and the program DERImport to get it into a JKS keystore.

Because I have spent a lot of time on this document already, I am just giving you an example.

openssl pkcs8 -topk8 -outform DER -in Xpvk.pem -inform PEM -out Xpvk.pk8 -nocrypt
openssl x509 -in Xcert.pem -out Xcert.der -outform DER
java DERImport new.keystore NEWALIAS Xpvk.pk8 Xcert.der

You need the program DERImport.class of course. Do some internet searches to find DERImport.java or DERImport.class and download it.

If DERImport has become difficult to obtain, I can write a program to do the same thing-- just let me know.

NON-CA-SIGNED CERT

Run man keytool or see the Creating a Keystore section of JSSERefGuide.html.

Author

Written by blaine.simpson@admc.com (a.k.a. unsaved at http://sourceforge.net).
Document revision $Revision: 1.6 $.
Last updated $Date: 2003/08/21 14:53:08 $.