How to install an SSL Certificate into the SparkGateway
The SparkGateway use the Apache Tomcat web server and servlet container so installing SSL certificates is basically the
same process as installing an SSL certificate in Tomcat. However, there is no specific tools that handles all the steps
needed. So this article will explain in more detail how this can be done on a Windows Server 2003/2008.
1) Install the java SDK. The recommended version is jdk 1.6.0_27. You will need the Keytool.exe found in the bin folder.
2) Install OpenSSL. I used the version from http://code.google.com/p/openssl-for-windows/ because when I ran the 32bit
version from Sourceforge.net it crashed when I ran it on Windows Server 2008 64bit. The one from Google Code had a
64bit version which worked perfectly. Since the version from Google Code only contained three files I placed these files in
the bin folder of the Java SDK so that all the tools I needed were in the same folder.
3) Create a java keystore using Keytool.exe found in the Java bin folder. The keystore is simply the file where the SSL
certificate will be stored. Note: You must specify "RSA" as the algorithm because the default for Keytool is "DSA" but
most certificates now use "RSA". The default keystore type is "jks" which is what I used so I did not specify a keystore
type. If you wanted a "pkcs12" keystore you would have to specify this option. The normal file extension for a "jks" type
keystore is either "jks" or "keystore". I used "keystore".
keytool -genkey -alias myalias -keyalg RSA -keystore mystore.keystore -keysize 2048
myalias - should be the same name as you are using for your SSL Certificate. In my case I used www.ordersportal.com
since that was the website where I wanted to use the SSL certificate. You will need this alias in subsequent commands.
mystore.keystore is simply the name I want for the file where the certificates will be stored. You could also use the
extension "jks and you can include the full file path if needed.
You will be prompted for a keystore password and this password will be needed in the Sparkgateway and with most of the
following commands so be sure to remember it.
When creating the keystore a self signed certificate is also created so you will be prompted for:
1.
2.
3.
4.
5.
6.
7.
8.
What is you first and last name? Enter myalias (I used "www.ordersportal.com")
What is the name of your organizational unit. Enter what you like (I used "Online Sales").
What is your organization? Enter you business name (I used "dCipher Computing").
What is the name of your city or locality. Enter your city ( I used "Barrie").
What is your state or province? Enter your state of province (I used "Ontario").
What is the two letter country code for this unit? Enter your country code (I used "CA").
Then you will be prompted to confirm that all the entries are correct if so answer yes (y). If you answer
no (n) you will be able to make changes to these items.
Finally you will be prompted for another password but do not create one. This will make the default
password for the certificate the same as the keystore which is what you want for the Sparkgateway.
4) Create a CSR (Certificate Signing Request). This will create a file containing the information needed to have someone
issue you a SSL certificate. In my case I will use RapidSSL.
keytool -certreq -alias myalias -keyalg RSA -file mycertreq.csr -keystore mystore.keystore
mycertreq.csr - the file name where the CSR data will be stored. This is just a text file and can be opened with a test
editor.
5) Submit the mycertreq.csr to the signing authority supplying your certificate. The file is a text file and you usually just
copy and paste the contents into a web site for processing.
6) If your certificate comes in "pkcs12" this step may not be necessary. In my case I was sent a "pem" file containing the
certificate, private key, root and intermediate certificates. You need to import all these items into your keystore.
Unfortunately the Keytool does not allow you import the private key directly but there is a way around this problem. You
need to convert the private key and your certificate into a pkcs12 file which can them be imported into the keystore using
How to install an SSL Certificate into the SparkGateway
Keytool. To do this you need to put both the private key and your certificate into a "pem" text file. Simply paste them in
because both are just encoded text. I created a file called myalias.pem and just copied the required elements from the "pem"
file supplied to my. Be sure that you are copying and pasting the correct certificates. I used an online SSL Certificate
Viewer to ensure I was using the correct certificate. Once you have created this new "pem" file containg your private key
and certificate you can use the following command to convert the "pem" file into a pkcs12 file.
openssl pkcs12 -export -in myalias.pem -out myalias.p12 -name myalias
myalias.pem - The new "pem" file containing the private key and certificate
myalias.p12 - The new pkcs12 file containing my converted private key and certificate
You will be prompted for a password. I used the same password as I used in Step 3
8) I put both the root certificate and the intermediate certificate in their own "crt" files. I do not know for certain if this is
necessary but it was easier for me to import them into the key store using the following commands.
keytool -import -alias Root -trustcacerts -file myroot_ca.crt -keystore mystore.keystore -keyalg RSA
keytool -import -alias Intermediate -trustcacerts -file myintermediate_ca.crt -keystore mystore.keystore -keyalg RSA
9) Import the SSL Certificate and private key using the following command. You will be prompted for both the keystore
password and pkcs12 file password. You will also be asked if you want to overwrite the existing self signed certificate to
which you should say yes. This will replace the self signed certificate created in step 3 with the real SSL certificate of the
same name. Make sure you specify the destination store type as "JKS" which is the format we used when we created the
keystore.
keytool -importkeystore -srckeystore myalias.p12 -srcstoretype pkcs12 -destkeystore mystore.keystore -deststoretype
JKS
10) This step is optional but useful to see what is in your keystore.
keytool -list -v -keystore mystore.keystore > mykeystorelist.txt
mykeystorelist.txt - The text file containing information about certificates in the keystore
11) I put the keystore file in the Sparkgateway folder and adjusted the "Java Options" in the SparkGateway Manager as:
-Djavax.net.ssl.keyStore=mystore.keystore
-Djavax.net.ssl.keyStorePassword=mykeystorepwd
mykeystorepwd - This is the password you used in step 3
mystore.keystore - This is the fully qualified path to the keystore file.
Conclusion:
If you followed these steps you should have successfully created a keystore that will allow you to use an SSL certificate
with the SparkGateway. For simplicity I created a "cmd" file with all the commands that I can run when I need to create a
keystore.
openssl pkcs12 -export -in myalias.pem -out myalias.p12 -name myalias
keytool -genkey -alias myalias -keyalg RSA -keystore mystore.keystore -keysize 2048
keytool -certreq -alias myalias -keyalg RSA -file mycertreq.csr -keystore mystore.keystore
keytool -import -alias Root -trustcacerts -file myroot_ca.crt -keystore mystore.keystore" -keyalg RSA
keytool -import -alias Intermediate -trustcacerts -file myintermediate_ca.crt -keystore mystore.keystore" -keyalg RSA
keytool -importkeystore -srckeystore myalias.p12 -srcstoretype pkcs12 -destkeystore mystore.keystore -deststoretype JKS
keytool -list -v -keystore mystore.keystore > mykeystorelist.txt