JBoss Tomcat X509 – SSL Installation

Like the majority of server systems you will install your SSL certificate on the same server or keystore  where your Certificate Signing Request (CSR) was created. Your private key will always be left on and inside the  server system and keystore where the CSR was originally created.

Your SSL certificate will not work without original keystore file. We will assume that this is the original system. JBoss is a very customization environment below are generalized instructions, you will have to adapt these instructions to your own environment.

If you lose your keystore file or your password to access it. your SSL Certificate will no longer match and you will need to replace the certificate.

In order to install your X509 SSL certificate and its CA intermediate  into your keystore JBoss Tomcat system perform the following steps.

Step 1: Picking up your SSL Certificate & its Intermediate CA certificate:

1. If you had the option of server type during enrollment and selected Other you will receive a x509/.cer/.crt/.pem version of your certificate within the email. Alternately you can access your Certificate User Portal by the supplied link in the email to pick up the x509 version of your certificate.
2. Copy the SSL certificate and make sure to copy the —–BEGIN CERTIFICATE—– and —–END CERTIFICATE—– header and footer Ensure there are no white spaces, extra line breaks or additional characters.
3. Use a plain text editor such as Notepad, paste the content of the certificate and save it with extension .cer
4. If your intermediate CA certificate for your product is not in the body of the email you can access your Intermediate CA also in a link within that email. Copy and paste the contents of your Intermediate CA into its own Notepad file and save it with a .cer extension also.
   Note: Some CAs may require two intermediates for best compatibility. These two are to be copied within their own corresponding .cer files and installed one at a time in a repeated process for intermediate installation.

Step 2: Installing your SSL certificate and its CA Intermediate:
It is recommended that you have your Keystore, SSL certificate and Keytool.exe in the same folder or you will need to specify the full file path when running the following commands. you may want to make a copy of your Keystore in case their are issues with Installation.
Note: You will import these files into the same keystore used for CSR creation:

1. Import the Intermediate certificate (You will specify your own alias) Example: intermediate1 and intermediate2 depending on how many intermediates you have.
   

   keytool -import -alias intermediate1 -trustcacerts -file intermediate_file_name.cer  -keystore your_keystorename.Jks
   

   Note: If when you are attempting to import the x509 Intermediate CA you receive Error: “Failed to establish chain from reply” perform the advanced troubleshooting steps located in “Troubleshooting (Advanced) : Tomcat x509 – “Failed to establish chain from reply”

2. Import the SSL certificate (Use the same alias name based on when you created the keystore for CSR creation)
   

   keytool -import -alias your_Privatekey_Alias -trustcacerts -file your_SSLCertificate.cer  -keystore your_keystorename.Jks

Step 3: Confirm contents of the keystore:

1. At the command prompt, enter:
   
   keytool -list -v -keystore  your_keystore_filename
   
2. Viewing the contents of the keystore.
   
   
   The end entity SSL certificate is imported into the alias with the “Entry Type” of PrivateKeyEntry or KeyEntry.  If not, import the certificate into the Private Key alias.
   NOTE: The Certificate chain length: tells you the keystore was successful in establishing the certificate chain, and your keystore is ready for use.
   

Step 4: Configuring the JBoss Server:
JBoss Tomcat  keeps its configuration information in a server.xml file, which ensures JBoss is reading the correct keystore file and keystore password.This file also allows server administrators to set the port for secure connections.

If the server.xml file is not configured, or if it is pointing to the wrong keystore, then the server may present the incorrect certificate to the client browser.
Note: JBoss can be a custom environment. The name of your server.xml file could be something different. You should see some sort of connector within a .xml file under JBoss in the example below. This is what needs to be configured. If you are unable to figure or discover this SSL Connecter you may have to contact JBoss Support.

1. On the Jboss Tomcat server search and open the Tomcat server.xml file.
2. Open the server.xml config file using a text editor (ie. JAKARTA_HOME/conf/server.xml)
   Search for the secure element in your config file (try searching for SSL Connector).
3. Your keystore file name and path is listed under KeystoreFile, and its Password is under keystorePass.
4. By default it should look either one of the following A or B:

   • A: Standard Tomcat Systems server.xml using .jks keystores..

     

     1. If your Server.xml file looks like the above then perform the following conversion using Keytool on the Tomcat system.
        Note: below the naming conversions are generalized. your names will differ.

        keytool -importkeystore -srckeystore mypfxfile.pfx -srcstoretype pkcs12 -destkeystore newjkskeystore.jks -deststoretype JK

     2. After this conversion you will have a new .jks keystore that can be used to specify to the keystore file path and directory.
     3. Make sure to specify the correct “keystoreFile” directive to the new keystore and the “keystorePass” directive is referencing the correct keystore password.
        Note: These directives are case-sensitive! Make sure the letters “F” and “P” in “keystoreFile” and “keystorePass” are in uppercase.
        Note: If your keystore contains more than one private key alias, please add the “keyAlias” directive to reference the correct private key alias name. Usually only seen in some standard Tomcat systems that use .jks keystores.
        
        For Example:
        keystoreFile=”insert path to the keystore here”
        keystorePass=”insert keystore password here”
        keyAlias=”insert private key alias here”/>

   • B: Tomcat Systems server.xml able to use .pfx keystores.

     1. If your Server.xml file looks like the blow example then no need for a conversion your version of tomcat has the capability of using .pfx files.
        
     2. After you have figured out what type of keystore your server.xml file requires you are then ready to make the server.xml file point to your .pfx keystore.
     3. Make sure to specify the correct “keystoreFile” directive to the new keystore and the “keystorePass” directive is referencing the correct keystore password.
        Note: These directives are case-sensitive! Make sure the letters “F” and “P” in “keystoreFile” and “keystorePass” are in uppercase.
        
        For Example:
        keystoreFile=”insert path to the keystore here”
        keystorePass=”insert keystore password here”
        
5. After you have updated your server.xml file…
6. Save the changes.
7. Stop and start Tomcat.
   

Your SSL/TLS certificate is now installed and configured for its website.

If you are unable to use these instructions for your server, Acmetek recommends that you contact either the vendor of your software or the organization that supports it.

JBoss Support:
For more information, please refer to JBoss Support