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.


Encrypting your JDBC connection

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


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 -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 "" doesn't exist.

keytool -import -trustcacerts -keystore -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 every time that you run your client program. For example

java -cp /path/to/hsqldb.jar 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, you can not use jdbc:hsqldb:hsqls://localhost or jdbc:hsqldb:hsqls:// 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.


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

java -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.


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 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.


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 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.


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


Written by (a.k.a. unsaved at
Document revision $Revision: 1.6 $.
Last updated $Date: 2003/08/21 14:53:08 $.