Let me start at the end. What you need for SSL in Java is a keystore containing your private key information and a trust store containing the certificates you trust. When you access a secure site with a browser and the certificate authority (CA) that signed the site's certificate is unknown to the browser you get a prompt whether you trust this certificate or not. The trust store is the equivalent of you accepting a new certificate in a web browser. This is only needed in cases where you signed the certificate yourself.
The rest of this article assumes the file that represents the keystore is named keystore.jks and the file that represents trust store is named cacerts. The default format of the keystore is the proprietary Java KeyStore format, hence the .jks suffix. Java KeyStores are created with the keytool which is shipped with every Java 6 SDK.
Note: If you don't specify a file for the keystore, a file is created for you in your home directory (in Linux it's ~/.keystore). In this case you don't need to set up anything special in your Java program because this keystore is automatically searched for in case you try to establish a secure connection. I deliberately use my own file because it's a little bit more flexible—especially in development environments. There also exists a global trust store. You can find it under <jdk-install>/jre/lib/security/cacerts. I don't recommend to tamper with this file for development purposes. At the very least backup this file before you modify it.
Anyway, how do we create these two stores?
At first I assume you have a signed client certificate in e.g. PEM format. This means the content of the certificate will look something like this:
-------- BEGIN CERTIFICATE ----------
// lots of base64
-------- END CERTIFICATE ------------
-------- BEGIN RSA PRIVATE KEY ------
// lots of base64
-------- END RSA PRIVATE KEY --------
I'll refer to this file with the name client-cert.pem.
I think it doesn't really matter if the file has another format because you can convert many of these formats to PEM with one of the OpenSSL utilities. We're going to need these tools anyway.
The first approach I used does NOT work:
keytool -importcert -keystore keystore.jks -file client-cert.pem
The resulting file contains no information about the private key. Somehow only the certificate gets imported or something. You can easily verify this by issuing the following command:
keytool -list -v -keystore keystore.jks
This lists the entry type
trustedCertEntry. What we need is PrivateKeyEntry.To be honest I don't really understand this behaviour and it took me hours to realize that this step was the reason SSL didn't work for me.
At first we have to create a certificate in PKCS#12 format. With OpenSSL we can achieve this like that:
openssl pkcs12 -export -in client-cert.pem -out client-cert.p12
You get a prompt to enter a password. It is possible to leave this empty and theoretically you could do that because this file is only an intermediate file for your Java KeyStore. Don't leave the password empty! keytool doesn't like empty passwords so you definitely have to provide one. Just use password or something.
Now you get a new file client-cert.p12. Next we can create the keystore:
keytool -importkeystore -srckeystore client-cert.p12 -srcstoretype PKCS12 -destkeystore keystore.jks
You get prompted for the password for the PKCS#12 certificate (this is the point where an empty password is fatal) and another one for your new keystore. It is not possible to enter a password with less than six characters. If you check with the above used -list command you can see that this time the entry type is correct.
If you use a self signed certificate you need to create an appropriate trust store. I refer to this blog post. I used the program InstallCert with a few modifications (basically I changed some file paths because I wanted my very own trust store as I mentioned before). I hope this provides no difficulties.
Now we want to use these two files in our Java program. This is quite easy to accomplish. There are four properties we need:
javax.net.ssl.keyStore and javax.net.ssl.trustStore for the file locations of our key and trust store respectively. The passwords to the files are provided with javax.net.ssl.keyStorePassword and javax.net.ssl.trustStorePassword.You set these properties either before you start the JVM like this:
java -Djavax.net.ssl.keyStore=/path/to/keystore.jks -Djavax.net.ssl.keyStorePassword=password etc.
or in your code like this:
System.setProperty("javax.net.ssl.keyStore", "/path/to/keystore.jks");
System.setProperty("javax.net.ssl.keyStorePassword", "password");
// etc.
Well, I hope this helps someone. This took me quite some time to figure out.
