Set up HTTPS on ctrlX CORE

Introduction

An HTTPS connection is important to keep the traffic between the ctrlX CORE and your device encrypted and secure. This how-to shows how you can enable HTTPS for your ctrlX CORE. I separated this how-to in two parts: In the first part I'll show you how you can create your own certificate authority and add its root certificate to your devices. In the second part you'll learn how to create your own custom web server certificate that is signed by your certificate authority and uploaded to your CORE.

Prerequisites

• Any Linux machine with access to the command line and openssl installed

  • If you use Windows, you can download and install WSL (Windows Subsystem for Linux) (https://learn.microsoft.com/en-us/windows/wsl/install, https://ubuntu.com/desktop/wsl)

• ctrlX CORE

Preparation

Execute all the command line steps in this tutorial in the Linux command line.

Some parameters in the commands I used can be changed to your liking. Remember to use your own names/values consistently if you choose to change them.

Start with creating a new directory (mkdir ~/certs) where you can store your files and change into that directory (cd ~/certs ). Store all the files you create throughout this tutorial in this folder. Also all commands have to be executed from within this folder. Of course you can choose another name for it, but in this how-to I'll stick to ~/certs.

Does your company already maintain a private PKI (Public Key Infrastructure)? Then you can skip to PART 2. If this is not the case, these are the steps to create your own certificate authority:

PART 1: Become a certificate authority

INFO: These steps are the bare minimum to create a certificate authority. If you want to create one for a larger production environment, you might want to create additional config files and divide the files and tasks between different people (see https://checkmk.com/blog/how-become-your-own-certificate-authority for a starting point).

https://checkmk.com/blog/how-become-your-own-certificate-authority

1) Create private key

First create a private key (myCA.key will be the file name in this example):

openssl genrsa -aes256 -out myCA.key 4096

Next you'll get prompted to type in a PEM passphrase. Choose a safe passphrase. Press enter and then confirm your passphrase by typing it a second time. You've just created the private key for your CA (certificate authority) inside the ~/certs directory.

!!! KEEP YOUR PASSPHRASE AND THE PRIVATE KEY FILE SECURE!!!

2) Create root certificate

In this step you generate a root certificate with the following command:

openssl req -x509 -new -key myCA.key -sha256 -days 3653 -out myCA.pem

The number behind the -days flag (in this example 3653) is the number of days the certificate is valid. You should choose a high number because after expiration you need to redistribute a new root certificate to all devices in you network (repeat step 3). myCA.pem will be the root certificate's file name.

You'll get prompted for the passphrase of your private key. Type it in and press enter. Then you'll get a bunch of questions. This information is visible when inspecting the certificate, but unless a user is specifically looking for it they don't get to see it. Most of the fields are not mandatory and you can skip them/use a default value with enter. The common name is mandatory and you should keep note of it, because in a later step (PART 2, step 2) you can't choose it again.

Text of command prompt:

Enter pass phrase for myCA.key:
You are about to be asked to enter information that will be incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank.
For some fields there will be a default value,
If you enter '.', the field will be left blank.

-----

Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Bavaria
Locality Name (eg, city) []:Lohr am Main
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Bosch Rexroth AG
Organizational Unit Name (eg, section) []:DCEM-SLC6
Common Name (e.g. server FQDN or YOUR name) []:Rexroth
Email Address []:[email protected]


You've just created your CA's root certificate (myCA.pem).

3) Distribute your root certificate

Now you need to add the new root certificate to the devices you want to access the ctrlX CORE from. The steps can differ depending on the browser and operating system you use. The following steps describe the process for the most common browsers and operating systems:

a. Android (human machine interface)

First you have to get the certificate onto your Android device. An easy way to do this is to upload the root certificate (myCA.pem) to your ctrlX CORE:

Go to Settings > Certificates and Keys > Web Server and click on the arrow in the top right:

Then select your root certificate file and use the category "CA certificate":

Now visit your CORE's web interface on the Android device, go to the same menu and download the certificate (three dots on the right, Download):

The following steps are valid for Android 10. Other Android versions might have a slightly different work flow. Within Android go to Settings > Network and Internet > Wi-Fi > Wi-Fi preferences > Advanced > Install Certificates. Select the root certificate you've downloaded in the previous step. Give your root certificate a name (e.g. your common name), select "VPN and apps" in the "Credential use" field and press OK.

Now your certificate should be visible in Settings > Security > Encryption and credentials > Trusted credentials under the user tab.

New Android devices come with a browser that automatically uses root certificates added from users. On older Android devices however, you need to enable this manually:

Open your Chromium browser, type "chrome://flags" in the address bar, press enter and search for the flag "allow-user-certificates". Set this flag to true and restart your browser.

b. Linux

If you want to access your CORE from Firefox or Chromium on Linux then you'll have to add the root certificate directly to the browsers, since both use their own certificate store on Linux. They don't use the underlying systems' certificate store. To learn how to add the certificate to Firefox/Chromium under Linux, take a look at d. Firefox/Chromium.

If you want to use an application that directly accesses the Linux certificate store, search for "your distribution (e.g. Ubuntu) + how to add custom ca certificate".

c. Windows

In Windows the browsers usually use Windows' system certificate store. Either way you should go to your browser's settings page and search for "Certificate". If Windows' certificate store is used, it should clearly say so in the corresponding setting. Windows needs the root certificate in the .crt format. To convert your .pem file to a .crt file go back to your Linux machine and type the following in the command line:

openssl x509 -outform der -in myCA.pem -out myCA.crt

Then use this tutorial to add myCA.crt to Windows' certificate store.

d. Firefox/Chromium

• To add your certificate to Firefox use this tutorial. The certificate you want to add is myCA.pem. You want to use this certificate to only identify websites, so tick the corresponding box in step 11 of the tutorial.

• If you want to distribute your CA certificate on multiple Firefox browsers in an enterprise scope, use this help from Mozilla.

• For Chromium based browsers use this tutorial. The certificate you want to add is myCA.pem.

Now you've installed your root certificate on all of your devices. Let's start with signing your CORE's web server certificate:

PART 2: Create custom web server certificate

1) Log in

First you have to log in to your CORE (ignore the warning(s) about missing certificates this time)

2) Create a certificate signing request

To do this, go to Settings > Certificates & Keys > Web server and change to the Keys tab. Click on the three little dots next to the webserver_custom_key.pem entry. Choose "Generate certificate signing request".

Then fill out the fields. Only the "Common name or fully qualified domain name" field is mandatory. You can use any input but it is common practice to use the domain name or IP address you'll be using to access your CORE. IMPORTANT: Don't use the same common name as the root certificate's common name!

Fun Fact: The use of the common name field was deprecated in the year 2000 in RFC2818 and thus isn't used to identify the site's domain name/IP address anymore. Firefox dropped common name support in 2022 in version 101. Use the SubjectAltName instead for defining IP addresses and domain names (see step 5).

After that click on "Create". A dialog with all created certificate signing requests will open. If this is not the case you can open this dialog with the "Show certificate signing requests" button right under "Generate certificate signing request" (see picture above). Download your newly created signing request by clicking on the "Download pem" icon:

3) Sign your certificate signing request

In this step you sign the certificate signing request that you created and downloaded in step 2. If you want to use your corporation's private CA, send your signing request file (webserver_custom_key_csr.pem) to the responsible person including the domain name(s) and/or IP address(es) you use to access the CORE. To do it yourself copy the webserver_custom_key_csr.pem file to your ~/certs folder and type the following command in your Linux command line:

openssl x509 -req -in webserver_custom_key_csr.pem -CA myCA.pem -CAkey myCA.key -out webserver_custom_cert.pem -days 5000 -sha256 -extfile <(printf "subjectAltName=IP:192.168.88.253,IP:192.168.1.1,DNS:ctrlx.local")

You should change the IP address, domain names, etc. Separate them by a comma and prefix them with "IP:" or "DNS:" like in the example. You can leave some out or add some, but there has to be at least one entry.

The number behind the -days flag specifies how long the web server certificate is valid. Once it expires, you need to repeat PART 2 renew it. You don't need to repeat PART 1 in this case.

The file name for the exported certificate has to be webserver_custom_cert.pem. You can also give it a different name for now and change it later in the ctrlX web interface.

4) Delete old certificate

On your CORE go to Settings > Certificates & Keys > Web server and stay in the Certificates tab. Delete the webserver_custom_cert.pem file by clicking on the three dots on the right and select "Delete".

5) Upload new certificate

Now upload your certificate by clicking on the upwards arrow on the top right, select your newly created webserver_custom_cert.pem file and select the category "Own". Then click "Upload":

IMPORTANT: After the upload the file name has to be webserver_custom_cert.pem! If this is not the case you can change the file's name in the web interface:

6) Restart

Restart the device for changes to go into effect. If you've done anything wrong the CORE will automatically recreate the standard files.

Congratulations! Now you should be able to access your CORE securely over HTTPS on all the devices you've added in PART 1.

File Overview

Here's a short summary of all the files you now have in your ~/certs folder and where they belong: