This recipe shows you how to install your company's SSL certificate in Omada Controller 2.7.0 for Linux (community version)

 

Except for the file's ownership/permissions and probably the PKCS12 format for the keystore, this recipe also applies to v2.6.1 and the official TP-Link versions 2.4.8 + 2.5.3.

 

Prerequisites

To install your X509 certificate, you need your certificate (file mycert.crt in this recipe), the private key (mycert.key), the intermediate CA cert if any  (intermediate-CAcert.crt), the path to root certificates on your system (/etc/ssl/certs on most Linux systems), the keytool utility from the Java Runtime Environment and openssl.

 

Installing the certificate in a Java keystore

keytool is the Java utility to manage certificates in a keystore. To my knowledge, it is still not possible to import a X509 certificate and its private key into the keystore directly. You can generate a CSR, create a key, import signed certs and so on using keytool, but not import an existing X509 cert/key pair if the key is not already in the keystore. However, you can import cert/key pairs in PKCS12 format. Since PKCS12 is the preferred format for the Java keystore, we can convert the X509 certificate into PKCS12 format using openssl. This will do the trick and let you import a cert/key pair into the keystore using keytool.

 

Note: the proprietary JKS format is deprecated - if you choose this format instead of PKCS12, you will receive a warning from keytool telling you to better convert the proprietary format into PKCS12 format.

 

Let's go:

 

First, set an alias to the keytool utility to save typing if it is not installed already in a directory searched by your shell for commands. My JRE resides in /opt/jvm/jre1.8.0_181, so the command to create an alias for keytool is:

 

  # alias keytool='/opt/jvm/jre1.8.0_181/bin/keytool' 

 

Next, convert the X509 certificate and the private key into PKCS12 format (full dialog shown here, do not enter the shell prompts # and >):

 

  # openssl pkcs12 -export -in mycert.crt -inkey mycert.key -out mycert.p12 \
  >                -CAfile intermediate-CAcert.crt -CApath /etc/ssl/certs \

  >                -caname root -name eap -chain

  Enter Export Password: eapc

  Verifying - Enter Export Password: eapc

 

This will create a file mycert.p12 in PKCS12 format. Most options are obvious. Option name is a name for your cert, which will be used by keytool later as an alias for this cert the Omada Controller probably use to look it up. So, use eap for the name. Option chain will include the full certificate chain (root cert, intermediate cert and your cert) in the PKCS12 file. The password to be entered is needed to prevent keytool from throwing an exception if importing later, it can be anything you like (e.g. eapc).

 

Now import the PKCS12 file into the Java keystore. Use your own keystore, don't add it to TP-Link's self-signed cert already present in /opt/tplink/EAPController/keystore/eap.keystore!

 

You can use any file name for the new keystore, I use mycert.jks for the recipe (again full dialog shown, do not enter shell prompts # and >):

 

  # keytool -importkeystore -storetype PKCS12 -destkeystore mycert.jks \

  >         -destkeypass k3L7pQ90x -deststorepass k3L7pQ90x \        ☜ do not use this password, choose yor own!
  >         -srcstoretype PKCS12 -srckeystore mycert.p12 -srcstorepass eapc
  Importing keystore mycert.p12 to mycert.jks...
  Entry for alias eap successfully imported.
  Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

 

  # rm mycert.p12

 

Option destkeystore names the file for the keystore in PKCS12 format. destkeypass and deststorepass are new passwords we will use for ensuring integrity of the keystore. srcstorepass is the password you did assign to the source file with openssl above. Don't forget to remove the temporary file mycert.p12.

 

Checking the certificate

If you want to check the certificate in the keystore, do so using the command:

 

  # keytool -list -v -keystore mycert.jks

 

There should be one certificate with alias eap.

 

Installing the keystore file

Before installing we correct file ownership/permissions of the new keystore and place it into the directoy where Omada Controller's files reside:

 

  # chown root.eapc mycert.jks

  # chmod 640 mycert.jks

  # mv mycert.jks /opt/tplink/EAPController/keystore/

 

Now edit file /opt/tplink/EAPController/properties/jetty.properties and change the file name and the password (set with keytool) for the keystore by changing following properties:

 

  ssl.key.store.password=k3L7pQ90x              ☜ do not use this password, choose your own!
  ssl.manager.password=k3L7pQ90x
  ssl.trust.store.password=k3L7pQ90x
  key.store.path=/keystore/mycert.jks
  trust.store.path=/keystore/mycert.jks

 

Restart Omada Controller to activate the new certificate.

 

Bonus tip: Hardening Omada Controller's keystore for enhanced security

The password in the property file is stored in clear text. To avoid unauthorized access, change file permissions like shown here:

 

  # cd /opt/tplink/EAPController

  # ls -ld keystore keystore/*

  drwxr-x--- 2 root eapc   57 Jul 28 17:29 keystore
  -rw-r----- 1 root eapc  985 Jul 26 01:05 keystore/eap.cer
  -rw-r----- 1 root eapc 2333 Jul 26 01:05 keystore/eap.keystore
  -rw-r----- 1 root eapc 4214 Jul 28 17:29 keystore/mycert.jks
  #

 

That's all. Enjoy!