airControl - How to Install SSL Certificate for the airControl Server

Overview


This article describes the process of installing an SSL certificate for airControl.

Table of Contents


  1. Introduction
  2. Steps
  3. Related Articles

Introduction


Back to Top

This article assumes the user already has a trusted cetificate as .pfx/.p12 file. If user has the certificate in another format, like .crt for example, it is necessary to convert it to .pfx (find a tutorial of how to do so here). Take note of the password for the certificate; it will be used when generating the key store. A java keytool application that comes with Java JDK will be needed.


Steps


Back to Top

info_i_25x25.png In the instructions below, you will see bolded text found between these symbols: < >. They are placeholders you must substitute with the corresponding information of your own system. Replace the complete bolded text, including the symbols (< >). 

1. Create a new aircontrol.keystore file. 

Use the following commands to create a new aircontrol.keystore file.

<JDK installation directory>/bin/keytool -importkeystore -deststorepass '<my_keystore_password>' -destkeypass '<destination_key_password>' -destkeystore aircontrol.keystore -srckeystore <trusted_cetificate_file.p12> -srcstoretype PKCS12 -srcstorepass '<p12_file_password>' -alias <aircontrol> 
  • deststorepass: is the password for your generated key store. Later we will obfuscate it and add it to the airControl web server configuration.
  • destkeypass: is the password for the key that will be stored in keystore. Make sure to save this password for future reference.
  • srcstorepass: is the password of you existing trusted certificate file.
  • alias: is the -name attribute value you used when converting to .pfx/.p12 format.
warning_25x25.png Tip: Remember to use strong passwords for both my_keystore_password and destination_key_password.

2. Override existing keystore file with the one you just created.

After the aircontrol.keystore file is generated, override the existing keystore file in <airControl installation directory>/web/etc with new one.

3. Update airControl web server to use new keystore. 

The next step will be to update the airControl web server (Jetty) configuration in order to use the new keystore.

3.1 Obfuscate my_keystore_password using the following command:

java -cp <airControl installation directory>/lib/jetty-all-<version>.jar org.eclipse.jetty.util.security.Password 'my_keystore_password'

Note: jetty-all-<version>.jar should be replaced by the actual jar file name located in lib directory (e.g. jetty-all-9.4.1.v20170120.jar). 

3.2 Replace OBF string

After you run the command in step 3.1, you will see the text output containing <OBF:xxxxxxxx> string. Go to <AirControl install dir>/web/etc directory and modify jetty-ssl.xml file, in the following way:

3.2.1 Replace OBF:xxxxxxxx with newly obfuscated in the following lines:
...
<Set name="KeyStorePassword"><Property name="jetty.keystore.password" default="OBF:xxxxxxx"/></Set>
...
<Set name="TrustStorePassword"><Property name="jetty.truststore.password" default="OBF:xxxxxxx"/></Set>

4. Restart server and test by logging in from a web browser.

warning_25x25.png Tip: Make sure you make a backup of <AirControl install dir>/web/etc after every successful setup, in case it's overwritten by mistake.

Related Articles


Back to Top

Back to Basics - How to Establish a Connection Using SSH