Enabling SSL support in k42

What is SSL?

SSL, or Secure Sockets Layer, is a way of securing communications between client/server applications, as well as providing identification and authentication mechanisms for both client and server.

Introduction

Originally developed by Netscape, SSL has been universally accepted on the World Wide Web for authenticated and encrypted communication between clients and servers. It is used by virtually all on-line payment systems (including internet banking) and is considered secure. For a complete description of the SSL protocol and it's workings, please refer to the Netscape DevEdge Introduction to SSL.

SSL support in k42 is provided by the Java Secure Sockets Extension v1.0.2. JSSE is a set of Java packages that enable secure Internet communications. It implements a Java version of SSL protocols and includes functionality for data encryption, server authentication, message integrity, and optional client authentication.

SSL Modes

SSL has different modes of operation:

Secure Communications - all communications between client and server are encrypted.
Server Authentication - the server identifies itself to the client by presenting an X509 Certificate. The client can authenticate this certificate using a Certificate Authority. This gives the client proof of the server's identity.
Client Authentication - the server may request that the client authenticates themselves by presenting a certificate during the SSL handshake. This works in a similar way to server authentication.

How do I set it up?

Creating a Certificate

To use SSL you must first create a certificate for the server to present to clients. This allows the client to be sure of whom they are talking to. To set up a certificate, you have to create a keystore¹² to hold the certificate, then either:

Import a signed certificate from a certificate authority (such as Verisign or BT Trustwise).
Create a self-signed certificate.

For commercial applications you should use a certificate authority to sign your certificates for extra protection for your users. For this purposes of demonstration this document shows the creation of a self-signed certificate.

To set up a keystore, we will make use of the Java 2 SDK keytool utility. This may be found in the %JAVA_HOME%\bin directory of the Java 2 SDK. Once this is done, follow these instructions to set up a new keystore:

Open up a command prompt.

The following text shows the interaction that takes place using keytool. User input is shown in bold.

[c:\]keytool -genkey -keystore c:\keystore -alias K42Server
Enter keystore password:  mykeystore
What is your first and last name?
  [Unknown]:  My K42 Server
What is the name of your organizational unit?
  [Unknown]:  Research and Development
What is the name of your organization?
  [Unknown]:  Empolis UK Ltd.
What is the name of your City or Locality?
  [Unknown]:  Swindon
What is the name of your State or Province?
  [Unknown]:  Wiltshire
What is the two-letter country code for this unit?
  [Unknown]:  UK
Is <CN=My K42 Server, OU=Research and Development, O=Empolis UK Ltd., L=Swindon, ST=Wiltshire, C=UK> correct?
  [no]:  yes
Enter key password for <mykey>
        (RETURN if same as keystore password): keypassword

This has set up a new keystore file in the root of the C: drive which contains a single self-signed certificate and private key, known by the alias of K42Server. Make a note of the location of this file and close the command prompt.

Configuring the k42 Server

To do to configure k42, pass it the following properties using the property file for that application:

empolis.ssl.keystorepassphrase is the keystore passphrase that you used to encrypt the keystore. This is the only mandatory property for SSL support as a keystore must always have a password. In our example, this password was mykeystore.
empolis.ssl.keymanagerfactory is the key manager factory to use, which governs how keys and certificates are managed within the store. The default is almost always used, and is SunX509.
empolis.ssl.keystoretype is the format of the keystore. For keystores set up using keytool, this is JKS which is the default.
empolis.ssl.keystorefilename specifies the full filename of the keystore to use. This will default to %user.home%\.keystore where user.home is the Java system property.
empolis.ssl.protocol specifies the SSL protocol to use. This defaults to TLS (Transport Layer Security).
empolis.ssl.keypassphrase is the password that the key to be used has been protected with. In our example interaction with keytool, the password was set to keypassword. If not specified, then the keystore password will be used.

Note that you may not specify the alias of the certificate/key pair to use. This is a limitation in JSSE. In all cases, the default key is used, which may be set using the keytool utility. Where there is only one certificate key/pair in the keytool, it is automatically the default.

Setting up k42 Server Properties

Here is an example of k42 property file with SSL support enabled:

empolis.objectmanager=com.empolis.gdo.PSObjectMgr
empolis.storename=base.ps
empolis.logname=k42server.log
empolis.serverdispatcher=TopicMapServer

empolis.ssl.keystorepassphrase=mykeystore
empolis.ssl.keystorefilename=c:\\keystore
empolis.ssl.keypassphrase=keypassword

When you run k42 with such a configuration file, you should see the following output:

[c:\k42\bin]k42 run
0    [main] RMIService - Starting GDO application...
160  [main] ServerDispatcher - Initialising RMI Service
170  [main] ServerDispatcher -  Initialising SSL support
5568 [main] ServerDispatcher - SSL support initialized successfully
.
.

Running the Client

No changes need to be made to client code or property files to take advantage of SSL, this is because it is the server generates the client stub that should be used to communicate with the server. The only thing that the client must do is make sure that the JSSE jar files (included within k42) are on the classpath. These JAR files are: jsse.jar, jnet.jar and jcert.jar and may be found in %K42_HOME%/lib.

Untrusted Certificate Chain Errors

When the server is presenting a self-signed certificate, or a certificate signed by an authority unknown by the client, then the server must export its certificate and the client must import it as a trusted host. If this is not done, then the client will fail to connect to k42, saying that the server presented an

untrusted certificate
chain

The client stores its list trusted hosts in a keystore called cacerts in the %JAVA_HOME%/lib/security directory. If your %JAVA_HOME% variable points to a JDK, rather than a JRE, then this directory will be %JAVA_HOME%/jre/lib/security.

To export the server certificate and import it into the client cacerts file perform the following operations:

Export the server certificate:

keytool -export -keystore c:\keystore -storepass mykeystore -rfc -alias Andy -file andy.cer
Certificate stored in file <andy.cer>

Import the server certificate into the cacerts file:

keytool -import -keystore %JAVA_HOME%/lib/security/cacerts -storepass changeit -alias Andy -file andy.cer
Owner: CN=Andy Brodie, OU=Research and Development, O=Empolis UK, L=Swindon, ST=Wiltshire, C=UK
Issuer: CN=Andy Brodie, OU=Research and Development, O=Empolis UK, L=Swindon, ST=Wiltshire, C=UK
Serial number: 3ad58946
Valid from: Thu Apr 12 11:53:58 GMT+01:00 2001 until: Wed Jul 11 11:53:58 GMT+01:00 2001
Certificate fingerprints:
         MD5:  AC:7E:2C:F2:EA:EB:E3:0B:89:19:66:0D:0C:8F:FA:08
         SHA1: FB:CB:B1:C5:F1:64:76:E4:36:2E:31:32:2A:79:4D:B0:53:5F:A5:2E
Trust this certificate? [no]:  yes
Certificate was added to keystore

Verify that the certificate is there:

keytool -list -keystore %JAVA_HOME%/jre/lib/security/cacerts -storepass changeit -alias Andy
Andy, Thu Apr 12 13:13:31 GMT+01:00 2001, trustedCertEntry,
Certificate fingerprint (MD5): AC:7E:2C:F2:EA:EB:E3:0B:89:19:66:0D:0C:8F:FA:08

You are now able to run distributed k42 applications securely.

Footnotes

1. Note that the default encryption on a keystore is not secure against cracking utilities. For information on obtaining a secure keystore implementation, see the Java Cryptography Extension product.

2. a keystore is simply a file containing certificates and keys.