SSL Certificate Installation

The SMP web console can also be accessed using HTTPS.  A Self-Signed certificate is bundled along with SMP which will be used for HTTPS. This self signed certificate will not be trusted by the user browsers. Thus, while connecting to SMP, you need to manually verify the certificate information and the hostname of SMP server carefully and should force the browser to accept the certificate.
To make the SMP server identify itself correctly to the web browser and the user:

• you need to obtain a new signed certificate from a CA for the SMP host or
• you can configure an existing certificate obtained from a CA with wild-card principal support for the SMP host

You can use OpenSSL or keytool (bundled with Java) to create your certificates, get them signed by a CA and use them with SMP. The choice of which tool to use is yours, based on what your security administrators say. Detailed instructions on using both the tools are provided here. If you already have a certificate signed by a CA, then we recommend using OpenSSL to create the keystore and configure it in SMP (steps 4 and 5 in the instructions below).

• Using OpenSSL
• Using Keytool
• Installing a wild card certificate

Using OpenSSL

OpenSSL is available bundled with most of the Linux distributions. If you have Windows and do not have OpenSSL installed, download it from http://www.slproweb.com/products/Win32OpenSSL.html . Make sure the 'bin' folder under the OpenSSL installation is included in the 'PATH' environment variable.

Step 1: The first step is to create the public-private key pair that will be used for the SSL handshake

• Open the command prompt
• Execute 'openssl genrsa -des3 -out <privatekey_filename>.key 1024'
• <privatekey_filename> is the filename you specify to store the private key
• This will prompt you to enter a pass-phrase for the private key. Enter 'smp' or a pass-phrase of your choice. (Though it is not documented, Tomcat has issues with passwords containing special characters, so use a password that has only alpha characters)
• This will create a file named <privatekey_filename>.key in the same folder

• Execute 'openssl req -new -key <privatekey_filename>.key -out <certreq_filename>.csr'
• <privatekey_filename>.key is the one used in the previous step
• <certreq_filename>.csr is the filename you specify to carry the certificate creation request to the CA (certificate authority)
• This will prompt you to enter a series of values that are part of the distinguished name (DN) of the server that will host SMP
• Enter values as applicable to you and importantly for the 'Common Name' supply the fully qualified name of the server hosting SMP (with which it will be accessed through the browsers)
• This will create a file name <certreq_filename>.csr in the same folder

• Some of the prominent CAs are Verisign (http://verisign.com), Thawte (http://www.thawte.com), RapidSSL (http://www.rapidssl.com). Check their documentation / website for details on submitting CSRs and this will involve a cost to be paid to the CA
• This process usually takes a few days time and you will be returned your signed SSL certificate and the CA's root certificate as .cer files
  
• Save them both in the the same working folder where files from steps 1 and 2 are stored

• On a command prompt navigate to the same working folder
  
• Execute 'openssl pkcs12 -export -in <cert_file>.cer -inkey <privatekey_filename>.key -out <keystore_filename>.p12 -name smp -CAfile <root_cert_file>.cer -caname smp -chain'
• where
• cert_file.cer is the signed SSL certificate with the .cer extention
• privatekey_filename.key is the private key file with a .key extension
• keystore_filename.p12 name is the keystore that will be generated with a .p12 extension
• root_cert_file.cer is the CA's root certificate with a .cer extension
• When prompted for password, enter the same password which you used in step 1 for the private key. Note that this requirement is due to an inherent limitation in tomcat, where these two passwords have to be the same
• This will generate the keystore file <keystore_filename>.p12 on the same folder
  

• Copy this <keystore_filename>.p12 generated in the previous step to <SMP_Install_Folder>\conf folder
• In a command prompt, navigate to <SMP_Install_Folder>\conf folder
• Open the file server.xml and do the following changes
• Search for the entry 'keystoreFile', which will have the default value set to "conf/server.keystore". Change the value to "conf/<keystore_filename>.p12"
• Make sure the entry  for 'keystorePass' is set to "smp" or the password you specified in the previous step while creating the keystore
  
• Add a new entry keystoreType="PKCS12" next to the keystorePass entry
  
• Save the server.xml file
• Restart the SMP server and connect through the web browser. If you are able to view the SMP login console without any warning from the browser, you have successfully installed your SSL certificate in SMP!

Using Keytool

• Go to <SMP_Home>/jre/bin folder
• Execute the command "./keytool -genkey -alias smp -keyalg RSA -keypass <privatekey_password> -storepass <keystore_password> -validity <no_of days> -keystore <keystore_filename>"
  • <keystore_password> is the password to access the keystore, <privatekey_password> is the password to protect your private key. Note that due to an inherent limitation in tomcat, these two passwords have to be the same. (Though it is not documented, Tomcat has issues with passwords containing special characters, so use a password that has only alpha characters)
  • <no_of_days> is the validity of the key pair in number of days, from the day it was created
    
• The command will prompt you to enter details about you and your organization
• For the 'first and the last name' enter the FQDN of the server running SMP
• For other fields enter the relevant information
• <keystore_password> is the password to access the keystore, <privatekey_password> is the password to protect your private key and <no_of_days> is the validity of the key pair in number of days, from the day it was created
• This will create a keystore file named <keystore_filename> in the same folder, with the generated key pair

• Go to <SMP_Home>/jre/bin folder
• Execute the command "keytool -certreq -keyalg RSA -alias smp -keypass <privatekey_password> -storepass <keystore_password> -file <csr_filename> -keystore <keystore_filename>"
• Note that the <csr_filename> that you choose should have .csr extension. The <privatekey_password>, <keystore_password> and <keystore_filename> are the ones used in the last step
• This will create a CSR file named <csr_filename> in the same folder

• Some of the prominent CAs are Verisign (http://verisign.com), Thawte (http://www.thawte.com), RapidSSL (http://www.rapidssl.com). Check their documentation / website for details on submitting CSRs and this will involve a cost to be paid to the CA
• This process usually takes a few days time and you will be returned your signed SSL certificate and the CA's certificate as .cer files
  
• Save them both in the <SMP_Home>/jre/bin folder

• Import your SSL certificate into your keystore
• Go to <SMP_Home>/jre/bin folder
• Execute the command "keytool -import -alias smp -keypass <privatekey_password> -storepass <keystore_password> -keystore <keystore_filename> -trustcacerts -file <your_ssl_certificate>"
• <your_ssl_certificate> is the certificate you obtained from the CA, a .cer file saved in the previous step. The <privatekey_password>, <keystore_password> and <keystore_filename> are the ones used in the previous steps
• Now copy the <keystore_filename> to the <SMP_Home>/conf folder

• Go to <SMP_Home>/conf folder
• Open the file server.xml
• Search for the entry 'keystoreFile', which will have the default value set to "conf/server.keystore". Change the value to "conf/<keystore_filename>" where <keystore_filename> is the one used in the previous steps
• Also search for the entry 'keystorePass' (which will infact be next to keystoreFile), which will have the default value set to "xxaavteenn". Change the value to "<keystore_password>" where <keystore_password> is the one used in the previous steps
• Restart the SMP server and connect through the web browser. If you are able to view the SMP login console without any warning from the browser, you have successfully installed your SSL certificate in SMP!

Installing an existing wild card supported SSL certificate

• Go to <SMP_Home>/conf folder
• Open the file server.xml
• Search for the entry 'keystoreFile', which will have the default value set to "conf/server.keystore". Change the value to "conf/<keystore_filename>" where <keystore_filename> is the one belong to the existing wild-card certificate.
  
• Also search for the entry 'keystorePass' (which will in fact be next to keystoreFile), which will have the default value set to "xxaavteenn". Change the value to "<keystore_password>" where <keystore_password> is the one used to protected the existing wild-card certificate keystore.
• Restart the SMP server and connect through the web browserconsole. If you are able to view the SMP login console without any warning from the browser, you have successfully installed your SSL certificate in SMP!