Custom SSL for advanced JSSE developers: Setting up KeyStore and TrustStore files

Return to article

Setting up KeyStore and TrustStore files is fairly simple. Here we'll go through the process step by step, setting up the files for use in our example exercises. (In the following prompt examples, your responses are highlighted in blue.)

KeyStore setup

First, we'll create the client's KeyStore. We'll call the file clientKeys, and store in it a certificate for Alice. To do this, enter the following command on your command line:

keytool -genkey -alias alice -keystore clientKeys

You'll immediately be prompted for a password. In this case, "password" will do. keytool will then ask for the details of the certificate to be entered; for each prompt enter something like what is shown below:

What is your first and last name?
   [Unknown]:  Alice
What is the name of your organizational unit?
   [Unknown]:  developerWorks
What is the name of your organization?
   [Unknown]:  IBM
What is the name of your City or Locality?
   [Unknown]:  Winchester
What is the name of your State or Province?
   [Unknown]:  Hampshire
What is the two-letter country code for this unit?
   [Unknown]:  UK
Is <CN=Alice, OU=developerWorks, O=IBM, L=Winchester, 
ST=Hampshire, C=UK> correct?
   [no]:  yes

Of course, chances are that you don't work in Winchester, so you can choose different values for these prompts! The alias name (specified on the command line) should be alice, and the common name should be Alice. keytool will make the request:

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

Press Return to use the same password. JSSE usually relies on this property, although the article will teach you how to overcome this restriction.

We need a second certificate in our client KeyStore, so we'll now add a certificate for Alice's traditional buddy, Bob:

keytool -genkey -alias bob -keystore clientKeys
Enter keystore password:  password
What is your first and last name?
   [Unknown]:  Bob
(etc.)

If you want to have a peek at the KeyStore, enter:

keytool -list -v -keystore clientKeys

Confirm you have two certificates with the correct information.

Server setup

Next, we need to provide a KeyStore for the server. This will be a file called serverKeys, containing a single certificate. As before, enter the following:

keytool -genkey -alias server -keystore serverKeys
Enter keystore password:  password
What is your first and last name?
   [Unknown]:  Server
(etc.)

Again, confirm this has been set up properly by entering:

keytool -list -v -keystore serverKeys

TrustStore setup

Now, we'll create the TrustStores. These contain certificates explicitly trusted to the local SSL peer, so, for our client to work, we need to make alice and bob trusted by the server, and server trusted by the client. To do this, we must first extract the three certificates into individual files, as shown below:

keytool -export -alias alice -keystore clientKeys -file alice.cer
Enter keystore password: password
Certificate stored in file <alice.cer>

keytool -export -alias bob -keystore clientKeys -file bob.cer
Enter keystore password: password
Certificate stored in file <bob.cer>

keytool -export -alias server -keystore serverKeys -file server.cer
Enter keystore password: password
Certificate stored in file <server.cer>

This leaves three certificate files in the current directory. Next, we import these into appropriate truststore files. Import server.cer into a file called clientTrust, and the two client certificates into a file called serverTrust, as shown below:

keytool -import -alias server -keystore clientTrust -file server.cer
keytool -import -alias alice -keystore serverTrust -file alice.cer
keytool -import -alias bob -keystore serverTrust -file bob.cer

For each keytool -import command, you will first be asked to enter the password. The contents of the certificate will be displayed, and you should indicate that you wish to trust the certificate by entering the following:

Trust this certificate? [no]: yes

You should now have four files in your working directory: clientKeys, serverKeys, clientTrust, and serverTrust. You can use the -list option of keytool to check the contents of these files.

Return to article