Setting Up Keystores for a Client and a Service

There has been many queries about setting up the keys and certificates properly for services and clients when securing Web services. By default Rampart/WSS4J supports using Java and PKCS12 keystores, to extract keys and certificates to be used by services and clients.This tutorial explains how to create key pairs for a client and a service, create keys for a certificate authority (CA), sign public key certificates of the client and the service using CA private key and import the certificates into the client at service keystores.

We will use openssl suite and Java keytool utility that is available with the JDK to create the keystores.

Step 1 : Creating Certificate Authority Keys

A certificate authority is an entity trusted by all parties participating in a secure communication. This entity will certify the trusted party's public keys by signing them. Since the certificate authority is a trusted one it will accept the public key certificates signed by that particular CA as trusted. First we will be creating a new self signed key pair for the certificate authority. We will use openssl to create this key pair. IMPORTANT: Download the following three files and copy them to the directory that will be used to create the keys. index.txt openssl.cnf serial Try the following from the same directory that you saved the above files in:

$ openssl req -x509 -newkey rsa:1024 -keyout cakey.pem -out cacert.pem -config openssl.cnf

Now you will be asked a set of questions in creating the key pair as shown below:

Generating a 1024 bit RSA private key
...++++++
..............++++++
writing new private key to 'CAKey.pem'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank. For some fields 
there will be a default value,If you enter '.', the field will be left blank.
-----

Country Name (2 letter code) [AU]:LK
State or Province Name (full name) [Some-State]:Western
Locality Name (eg, city) []:Colombo
Organization Name (eg, company) [Internet Widgits Pty Ltd]:WSO2
Organizational Unit Name (eg, section) []:Axis2
Common Name (eg, YOUR name) []:Ruchith Fernando
Email Address []:ruchith@axis2.com

The result of the above will be two files:

• cakey.pem
• cacert.pem

The cakey.pem file contains the encrypted private key and the cacert.pem file contains the publik key certificate signed using the private key (Figure 1).

Figure 1: CA's private key and the self signed certificate

Step 2 : Client and Service Keys

Now lets create the two sets of keys for the service and the client using the 'keytool' that comes with the JDK. Lets use the 'keytool -genkey' to create a keypair and store it in a keystore using the following command:

$ keytool -genkey -alias client -keyalg RSA -keystore client.jks

Once again you will be asked a series of questions as shown below:

Enter keystore password:  changeme
What is your first and last name?
  [Unknown]:  Client
What is the name of your organizational unit?
  [Unknown]:  Axis2
What is the name of your organization?
  [Unknown]:  WSO2
What is the name of your City or Locality?
  [Unknown]:  Colombo
What is the name of your State or Province?
  [Unknown]:  Western
What is the two-letter country code for this unit?
  [Unknown]:  LK
Is CN=Client, OU=Axis2, O=WSO2, L=Colombo, ST=Western, C=LK correct?
  [no]:  yes

Enter key password for 
        (RETURN if same as keystore password):

The created keys are stored in the client.jks file (Figure 2) which is a Java keystore under the alias client.

Figure 2: Contents of a keystore with a single key entry To verify this fact we can list the contents of the keystore as shown below.

$ keytool -list -v -keystore client.jks -storepass changeme

Keystore type: jks
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: client
Creation date: Apr 12, 2006
Entry type: keyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Client, OU=Axis2, O=WSO2, L=Colombo, ST=Western, C=LK
Issuer: CN=Client, OU=Axis2, O=WSO2, L=Colombo, ST=Western, C=LK
Serial number: 443d2226
Valid from: Wed Apr 12 21:52:06 LKT 2006 until: Tue Jul 11 21:52:06 LKT 2006
Certificate fingerprints:
         MD5:  EB:25:BA:E1:A9:7F:FB:41:2D:B9:B4:75:D4:47:88:D8
         SHA1: F2:6F:93:3F:51:FA:CC:48:AE:E1:BE:20:04:C7:0E:90:C4:2C:D2:DB


*******************************************
*******************************************

Similar to the way we created the client's keys we can create the service's keys using the following command:

$ keytool -genkey -alias service -keyalg RSA -keystore service.jks

Note that we will be using 'changeme' (without quotes) as the password of both keys and keystores.

Step 3 : Producing Signed X509 Certificates

We can create signed X509 (version 3) certificates using openssl using certificate requests. First we have to create the certificate requests using the generated keys for the client and the service.

$ keytool -certreq -keystore client.jks -storepass changeme -alias client -file client.cert.req
$ keytool -certreq -keystore service.jks -storepass changeme -alias service -file service.cert.req

The above command will create the client.cert.req and service.cert.req files which we will use in the next step to produce X509 certificates signed by the private key of the CA using 'openssl ca' command.

$ openssl ca -config openssl.cnf -out client.pem -infiles client.cert.req
$ openssl ca -config openssl.cnf -out service.pem -infiles service.cert.req

It should be noted that the CA's configuration (openssl.cnf) file is configured to point to the cakey.pem file as the private key to use. The output produced in the client.pem and service.pem files are plain text. To import these signed certificates into the keystores we will have to convert them into the binary (DER) format using 'openssl x509' command.

$ openssl x509 -outform DER -in client.pem -out client.cert
$ openssl x509 -outform DER -in service.pem -out service.cert

Also we will have to convert the CA's certificate to the binary form to be imported to both keystores.

$ openssl x509 -outform DER -in cacert.pem -out cacert.cert

Step 4 : Importing the certificates

First we must import the CA's self signed certificate to both client and service keystores. Lets use the alias 'ca' to identify the CA's certificate.

$ keytool -import -file cacert.cert -keystore service.jks -storepass changeme -alias ca
$ keytool -import -file cacert.cert -keystore client.jks -storepass changeme -alias ca

The 'keytool' will display the information in the certificate and will ask for confirmation to import.

Owner: CN=Ruchith Fernando, OU=Axis2, O=WSO2, L=Colombo, ST=Western, C=LK
Issuer: CN=Ruchith Fernando, OU=Axis2, O=WSO2, L=Colombo, ST=Western, C=LK
Serial number: c2889b1153b983b6
Valid from: Wed Apr 12 23:10:23 LKT 2006 until: Fri May 12 23:10:23 LKT 2006
Certificate fingerprints:
         MD5:  0C:D8:14:DA:B2:32:3A:DA:F3:9B:2F:C8:B8:4E:C8:A0
         SHA1: 20:77:05:EA:50:E6:64:EE:81:05:57:EE:8B:E4:C8:7C:76:98:C0:06
Trust this certificate? [no]:  yes

When we type in 'yes' and confirm the import, the CA's certificate will be imported as a trusted certificate entry.

Certificate was added to keystore

Now we will import the signed certificates to the keystores.

$ keytool -import -file client.cert -keystore client.jks -storepass changeme -alias client
$ keytool -import -file service.cert -keystore service.jks -storepass changeme -alias service

Since the certificate being imported matches the certificate of the given alias and is signed by the trusted CA cert (which is now in the keystore) the keytool will simply import the signed certificate and respond with the following.

Certificate reply was installed in keystore

Its important to note that we must have the CA's certificate imported first before importing the other certificates. If not, when we try to import a certificate the keytool will give the following error:

keytool error: java.lang.Exception: Failed to establish chain from reply

In order to allow secure communication between the client and the service we have to make sure that each party has the other's public key with them. Now lets import the client.cert into the service's keystore and the service.cert into the client's keystore.

$ keytool -import -file client.cert -keystore service.jks -storepass changeme -alias client
$ keytool -import -file service.cert -keystore client.jks -storepass changeme -alias service

Once again since certificates added are signed by a trusted certificate it will be simply imported to the keystore and the keytool will confirm that with the following output.

Certificate was added to keystore

Now we have two keystores for the client and the service including their key pairs and the certificates of the other party and the certificate authority.

Author

Ruchith Fernando, Senior Software Engineer, WSO2 Inc. ruchith @ wso2