Setting Up Keystores for a Client and a Service
By Ruchith Fernando
- 29 Jun, 2006
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 :email@example.com
The result of the above will be two files:
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?
What is the name of your organizational unit?
What is the name of your organization?
What is the name of your City or Locality?
What is the name of your State or Province?
What is the two-letter country code for this unit?
Is CN=Client, OU=Axis2, O=WSO2, L=Colombo, ST=Western, C=LK correct?
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
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
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
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.
Ruchith Fernando, Senior Software Engineer, WSO2 Inc. ruchith @ wso2