Installing a SSL Certificate

Introduction

This guide will show you how to install a genuine SSL certificate on the Ignition Gateway Webpage. This will allow you to enable SSL on the gateway without users seeing a security warning. You can enable SSL in Ignition without a genuine SSL certificate installed, but the web browser will display a warning saying that you shouldn't trust the website.

Installing a genuine SSL certificate will prevent this warning from showing. This guide assumes a 7.7+ version of Ignition is installed.

Important Note: Oracle changed how SSL validation works as of version 8 update 51. If your Ignition gateway is running on this version of Java or greater then you will need to upgrade Ignition to 7.7.5 or higher.

Creating and Installing a genuine SSL certificate

The following example assumes a Windows 7 operating system, but primarily uses the JDK and Ignition, so the commands could be converted to other operating systems. 

1) Install the Java Development Kit on the Ignition server

The Java Development Kit contains some tools you will need later. You can download the latest JDK here: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

This guide uses JDK version 8 update 45. Note that you can have multiple versions of Java Standard Edition and the JDK installed on the same computer simultaneously You do not need to uninstall any other versions of Java.

Before downloading, you will need to agree to the Oracle Binary Code License Agreement for Java SE. Next, select the installer that matches the bit architecture of your gateway; e.g., if you have a 64-bit version of Ignition running on Windows then you will need the Windows x64 installer

If you are uncertain as to what version of Ignition you have installed, you can check the Status tab on the Gateway Webpage

Next run the installer. Follow the prompts to finish the installation process. Take note of the directory where the JDK is installed.

2) Open a command prompt

You will need to open a command terminal as the administrator for the next several steps. Navigate to the directory where the JDK was installed. The exact directory will be different depending on which version you installed. The command should look similar to the following: cd C:\Program Files\Java\jdk1.8.0_45\bin

3) Create the keystore

a) A keystore is a repository for security certificates. Type the following:

keytool -genkey -alias tomcat -keyalg RSA -keysize 2048 -keystore C:\ssl.key

The above command will do the following:

• Generate a Java keystore named "ssl.key". While you could give the keystore a different name, Ignition assumes the keystore will be named "ssl.key", so this is the name you should use.

• The keystore will be located at the root directory on the C drive.

• The keystore will have an alias of "tomcat", or, you can give it some other alias.

b) You will be prompted to enter a password for the keystore. You must use 'ignition' without the quotes. This is the password the Ignition service will attempt to use when accessing the keystore, so you must use this exact password when generating the keystore. 

c) Next you will be asked a series of questions about your organization. Some of these questions require an explanation.

• “What is your first and last name?”

  • Do not enter your first and last name. The name provided here will be the recipient of the security certificates, and this is what will be displayed if anyone tries to view the gateway’s certificates. Instead, enter the domain or public IP address of your organization.

• “What is the name of your organizational unit?”

  • This should be a specific department in the organization; e.g, Finance, Development, Marketing, etc.

Once finished you will then be asked to review and confirm your choices by typing "yes". You will then be asked to enter a password. Use the same password you created in 3b by pressing the Return/Enter key.

The console should look like the following:

If you check the root directory of the C drive you'll find the newly created keystore:

4) Generate a Certificate Signing Request

Type the following into the command prompt:

keytool -certreq -alias tomcat -file C:\csr.txt -keystore C:\ssl.key

This will create a Certificate Signing Request named "csr.txt" at the root directory on the C drive. It will use the keystore given the alias "tomcat" which is located at the root directory on the C drive.

5) Purchase the SSL certificate

Next you need to purchase a genuine SSL certificate. The Certificate Authority (CA) will request your Certificate Signing Request (CSR) you created in step 4. Generally you will need to open the CSR in a text editor, and copy-paste the contents to a form on the CA's website.

If the CA asks what software generated the CSR choose Tomcat or Java.

Next you will need to wait for the CA to process your payment and review your CSR. The CA will email you the security certificates

6) Import the security certificates

Once you have your certificates, open a command prompt as the administrator, and navigate back to the JDK installation directory as we did in step 2. 

You will need to import three certificates into the keystore: a root certficate, an intermediary certificate, and your server's certificate. All three certificates must use the same hashing method.

"Which certificates do I import?" It is very common for a CA to send you a file containing more than 3 security certificates. The main difference between all the certificates is the hashing method each uses. The security certificates you import must share the same hashing method (i.e. SHA1, SHA2, etc.). The CA should have some documentation that specifies the exact hashing method of each certificate and what type of certificate it is. Once you've identified the certificates you need, import them into the keystore. The exact order you import them does not matter, but you will need a root, an intermediary, and your server’s certificate.

The command to import a security certificate into the keystore depends on the name of the certificate, but it should look something like the following:

keytool -import -trustcacerts -alias root -file C:\cert\AddTrustExternalCARoot.crt -keystore C:\ssl.key

The above command does the following:

• Imports the certificate named "AddTrustExternalCARoot.crt" from C:\cert into the keystore which is located at the root directory on the C drive

• The certificate is the root certificate, so we give it an alias of "root" to distinguish it from the other security certificates that will be in the keystore. This will make the certificate easier to identify should we need to remove it later.

Repeat the import process above for the other 2 certificates. The commands should look similar to the following:

Intermediate certificate

keytool -import -trustcacerts -alias inter -file C:\cert\SecureServerCA.crt -keystore C:\ssl.key

Your server's certificate

keytool -import -trustcacerts -alias tomcat -file C:\cert\domain.crt -keystore C:\ssl.key

7) Replace Ignition's default keystore

Next you need to replace the default keystore that ships with Ignition. The default location for this file for is \Inductive Automation\Ignition\webserver\ssl.key

Make a backup of the default keystore in case you need to revert back. Once you have made a backup replace the default keystore with your keystore.

You will then need to restart the Ignition Gateway.

8) Enable SSL on the gateway

Once the gateway restarts you can now enable SSL on the gateway. Under Gateway Setting in the Configure section of the gateway you'll find a property named "Use SSL". Set this to true, and click Save Changes.

You have successfully installed an SSL certificate on your gateway. If you navigate to the SSL port of your gateway you will no longer see a warning.

Troubleshooting

keytool error: java.io.FileNotFoundException: C:\ssl.key <Access is denied>

When attempting to generate the keystore you may see an error saying that access is denied.

This is because creating the keystore requires administrator privileges. Close the command prompt, re-open it as the administrator, and try the command again. You can open the command prompt by right click and selecting "Run as administrator". 

keytool error: java.lang.Exception: Failed to establish chain from reply

There are two common causes for this error:

• One of the security certificates in the keystore does not match the hashing method of the other two certificates; i.e., the root and intermediary certificates use SHA1, but your server's certificate uses SHA2

• One of the security certificates is missing from the keystore; i.e., the root certificate was imported twice on accident, and the intermediary certificate was never imported

In either case you will need remove the unnecessary security certificate, and import the missing certificate.

Important: Do not delete the keystore to resolve this. The security certificates the CA sent you are signed against the keystore that generated the CSR. If you delete the keystore then you will need to generate a new CSR and have the CA issue new security certificates.

There are some keytool commands that can help find the incorrect certificate and remove it:

Check which certificates are in the keystore (where "password" is the keystore's password):

keytool -list -v -keystore ssl.key -storepass password

Check a particular item in the keystore by alias (where "CertAlias" is the alias you gave to the security certificate when importing it to the keystore):

keytool -list -v -keystore ssl.key -storepass password -alias CertAlias

Delete a certificate from the keystore:

keytool -delete -alias CertAlias -keystore ssl.key -storepass password

For additional information on the above commands see Oracle’s keytool documentation: http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html