Monday, June 21, 2010

Creating a java keystore using VeriSign as a certificate authority

Here is a step by step run through of creating a java ssl keystore using VeriSign as your certificate authority. I recently ran through this with a client so I figured I'd share since this has little to no correct documentation.

PREREQUISITE: You will need a jdk installed for you operating system. Also, I assume that you have added the $JAVA_HOME/bin folder to your $PATH environment variable. If you have not done so, you will need to run the commands I give from within the $JAVA_HOME/bin directory. You should see an executable named keytool.exe in this folder that is used throughout this tutorial.

First things first, we need to create a keystore, which in turn will create you private encryption key that will be used in the authentication process with clients. I like to think of a keystore as somewhat of a secure zip file. A keystore can contain many certificates which are distinguished by unique name identifiers (just like a java.util.HashMap in the Java world). The following command will create a 2048 bit RSA private key which is pretty standard today.

keytool -genkey -keyalg RSA -keysize 2048 –keystore –alias my_cert my-keystore.keystore 

Next, keytool will ask you for a password for your newly created keystore. Specify whatever password you like. Along with your password, you will be asked a series of questions.

NOTE: For the "What is your first and last name?" question, enter the full domain name. When I say full domain name, I mean whatever a user will type into the address bar in their browser when they go to your site. For example, if we were creating this keystore for google.com. You would specify www.google.com for this question.

At this point you now have a keystore named my-keystore.keystore. The next step is to create what is known as a certificate signing request. This request is what VeriSign will ask for to generate your public key (signing your certificate). The following command will generate your CSR

keytool –certreq –keyalg RSA –alias my_cert –file certreq.csr –keystore my-keystore.keystore

NOTE: It is important to use the same –alias and –keystore as used in command 1)

Now send your CSR to verisign per their instructions (they will send you instructions after you purchase your certificate). Verisign will then respond with your certificate. We will need to import the certificate they generate for you as well as the Intermediate Certificate from verisign.

At the time of authoring this guide the intermediate CA can be found here http://www.verisign.com/support/verisign-intermediate-ca/secure-site-intermediate/index.html . Copy the encrypted text to a file named intermediate.cer (make sure you do not add extra spaces) Next import intermediate.cer into your keystore

keytool –import –trustcacerts –alias intermediatechain –file intermediate.cer –keystore my_keystore.keystore

Next we want to import the certificate supplied from Verisign (what you bought). This is your public key. I assume for the below command that you saved your certificate in a file named server.cer.

keytool –import trustcacerts –alias my_cert –keystore my_keystore.keystore –file server.cer

NOTE: You must give this the same alias as used for your private key in command 1). Namely, this is ‘my_cert’ in this example.

At this point your keystore is properly configured and now you must configuration JBOSS to use it. Copy my_keystore.keystore to JBOSS_HOME\server\default\conf .

Next open the file JBOSS_HOME\server\default\deploy\jbossweb.sar\server.xml .

You should see some lines that look like below... You may need to uncomment these lines in the xml file if they are commented out.



Change the keystorePass to be whatever you password you gave your keystore when we created it in command 1)

Congratulations, you have configured your VeriSign purchased certificate to work with JBoss.