SSL Certificate Installation Tutorial

This tutorial shows how to install a certificate using the traditional approach of using paid for services and how to use the free SSL provider Let's Encrypt. The standard paid for services can be used by any Mako Server deployment, however, the Let's Encrypt Tutorial is designed for Linux deployments, where the server is publicly available on the Internet.

Installing an SSL certificate is not required unless you need secure communication for your web applications running on the server.

We need to use a well known Certificate Authority (CA) to sign our certificate in order to get browsers to accept a secure connection without popping up a warning. Well known CAs have their public certificate pre-installed in all major operating systems (Windows/Linux/Mac). If you are not using a well known CA, you will have to manually install the CAs certificate in all operating systems (or browsers) that you plan on using.

We recommend reading the tutorial Certificate Management for Embedded Systems if you are new to certificate management. The tutorial provides a good introduction to SSL certificate management and the chain of trust that leads up to the CA (root) certificate.

Installing a certificate using standard paid for services

We must perform the following steps for creating and installing a certificate.

  1. Create a private key and Certificate Signing Request (CSR)
  2. Have a well known CA sign our public certificate by using the CSR
  3. Wait for the CA to send us the signed certificate
  4. Assemble the signed certificate and the chain of trust
  5. Copy the certificate and the private key to the online server
  6. Configure and restart the Mako Server
  7. Test the certificate

Create a private key and Certificate Signing Request (CSR)

Creating a private key and a Certificate Signing Request (CSR) can be done by using the OpenSSL command line tool. As an alternative (or if you find the OpenSSL command line tool difficult to use), download and install our Certificate Management Tool. This tool is designed for users that want to act as their own CA, but the tool can also be used for creating a private key and a CSR that can be signed by a well known CA.

If you use our Certificate Management Tool, make sure you create an RSA root certificate. Well known CAs that can sign ECC certificates are currently not common. After creating the RSA root certificate (CA certificate), proceed to creating a certificate for your own domain name. Make sure to carefully follow the instructions in the Certificate Management Tool. When you have created the certificate, the files of interest will be:

HOMEDIR/.certmgr-db/RSA/keys-and-certs/simplemq.tk.key HOMEDIR/.certmgr-db/RSA/tmp/csr-simplemq.tk.req

The domain simplemq.tk is what we used when we signed our certificate. Look for files with the name including your domain name. Note: the Certificate Management Tool also created a public certificate signed with the CA initially created by the Certificate Management Tool, but we will not use this certificate. Instead, we will have a well known CA sign our CSR (csr-simplemq.tk.req).

Make sure you save the private key and the CSR in a safe (and trusted) place. You can use the CSR whenever you need to create/sign a new certificate.

Have a well know CA sign our public certificate by using the CSR

The following instructions shows how to obtain a free 90 day certificate from Comodo. You need to repeat the process (except for creating a private key and CSR) after 90 days. Signing and installing certificates are a bit tedious; thus you may consider using a paid for CA service that provides a certificate valid for three years.

Navigate to Comodo's free SSL certificate page and click the free certificate button. Open the CSR you created in the step above in an editor, select all, and copy the data. Paste this data into the CSR field at the Comodo's web site. Select "OTHER" for server software and click Next. Follow the wizard.

You will eventually get to a page where you have to validate that you own the domain name.

Figure 4: Select HTTP CSR Hash as validation method

Map the server using WebDAV

To map/mount the online server as a file system, use the URL: http://server-address/fs/. In Windows, you can go to Map Network Drive and enter the URL to map the online server as a drive in Windows. See the WebDAV information page for the BarracudaDrive product for more information on how to map/mount a WebDAV drive.

Since you do not have an email account setup with the domain name, select HTTP CSR Hash as validation method. Assuming you have your online www directory mapped to your local computer, go ahead and create a file with the name <MD5 hash of CSR>.txt on the mapped drive. Copy the SHA-1 hash from Comodos web site and paste into this file. The file should have two lines:

<Value of SHA1 hash of CSR> comodoca.com

Before clicking continue in the Comodo wizard, make sure you can open the file you just created by navigating to:

http://yourdomain/<MD5 hash of CSR>.txt

Figure 5: Screenshot of our domain validation file

Click continue in the Comodo wizard and complete your registration.

Wait for the CA to send us the signed certificate

You should receive an email from Comodo with the certificate after some time if you successfully completed the Comodo SSL wizard.

Assemble the signed certificate and the chain of trust

Unpack the content of the ZIP file (attached to the Comodo email) in an empty directory. The ZIP file should contain the following:

*yourdomainname*.crt COMODORSADomainValidationSecureServerCA.crt COMODORSAAddTrustCA.crt AddTrustExternalCARoot.crt

The ZIP file contains your certificate, two intermediate Certificate Authorities (CAs), and the Comodo's public root certificate (AddTrustExternalCARoot.crt). We will not use the public root certificate since this certificate is already known by your browser. The browser keeps well known CAs in a CA database. However, we need the two intermediate CAs since we need the chain of trust leading up to the Comodo's root certificate. See the Wikipedia article Chain of trust, section Computer security, for more information on how this works.

Using your favorite text editor, create a new file and call it yourdomain.cert. Open the above list of certificate and intermediate CAs in an editor one at a time. Copy the content of these files in the order listed into your new file. Do not add AddTrustExternalCARoot.crt. Save the file. The new file must contain: *yourdomainname*.crt, COMODORSADomainValidationSecureServerCA.crt, and COMODORSAAddTrustCA.crt.

Copy the certificate and the private key to the online server

The next step is to copy your private key and your assembled certificate to your online server.

The files we created for our server are:

simplemq.tk.key The private key created by the Certificate Management Tool
simplemq.tk.cert Created by assembling certificate and intermediate CAs

An easy way to transfer the files to your online server is to copy them using the WebDAV connection that is setup to the 'www' directory on your server. However, the files need to be placed in the parent directory and not in www -- i.e. the files must be placed in /home/mako. A simple solution to this problem is to create a soft link from 'www' to the parent directory. The following Linux command does this:

ln -s .. .ROOT

Notice that we create a link (.ROOT) that starts with a dot. Files and directories that start with a dot cannot be navigated into when accessing the server using a standard HTTP client; however, the authenticated WebDAV client can access this directory.

The following screenshot shows the complete set of commands we used for creating the soft link:

Figure 6: Creating a link from 'www' to the parent directory when logged in as the Linux user 'mako'

You can now simply drag and drop the files onto the mapped online server. The following screenshot shows how we copy the files to the .ROOT directory (the soft link pointing to the parent directory).

Figure 7: Copying the private key and certificate from PC to /home/mako

Configure and restart the Mako Server

The names of the private key and the certificate must be added to the mako.conf file. The following example shows how we can directly open this file using Notepad from a PC. We have mapped the online 'www' directory as Z:.

notepad z:\.ROOT\mako.conf

Add the two following lines to mako.conf. Note, you must change the name of the key and the certificate to your own names.

certfile = "simplemq.tk.cert" keyfile = "simplemq.tk.key"

Save the file and verify that the Mako Server can load your new key and certificate. The best way to do this is to run the Mako Server in the foreground since the server prints out error messages, if any to the console. The following screenshot shows how we stop the server running in the background, navigate to /home/mako, and start the server in the foreground as user (-u) 'mako'. As you can see from the screenshot below, the server successfully loaded our new key and certificate.

Figure 8: Verifying that Mako Server can load the certificate by running the server in the foreground

Stop the server running in the foreground by the using the command CTRL-C. You can then start the server in the background by using the command: /etc/init.d/mako.sh start

Test the certificate

Navigate to https://your-domain-name. You should not get any certificate warning messages in your browser.

As a final test, you may navigate to https://www.ssllabs.com/ssltest/. Enter your domain name (hostname) and click submit. After some time, you should get a full report and no conflicts with your chain of trust.

Figure 8: Verifying that Mako Server can load the certificate by running the server in the foreground

You may now setup a trusted and secure communication between any browser and the server by entering https://your-domain-name in the browser.

Let's Encrypt Tutorial

The following tutorial assumes you have Linux command line experience. The tutorial also assumes you have the user 'mako' and the home directory for the mako server in /home/mako as explained in the Installing Mako Server as a Service on Linux tutorial. You can use any directory other than /home/mako, but you must adjust the commands below accordingly. All commands below assume you are logged in as user root. We also use the domain name "mydomain.com". Replace "mydomain.com" with your domain name in all commands/scripts below. Let’s Encrypt certificates are valid for three months only at a time and manually installing the new certificate every third month is tedious. We will, for this reason, design some scripts for updating the certificate automatically.

The official Let’s Encrypt client is Certboot; however, we will not use this client since the tool brings a lot of bagage and usually fails to install on low end computers and/or Virtual Private Servers. Instead, we will use a tool called getssl, which runs as a bash script.

Start by running the following commands. The tools installed are required for the getssl script and you must have cron installed to automate certificate renewal.

apt-get update; apt-get install wget openssl dnsutils cron

Navigate to a location where you want the getssl script and run the following commands. We keep the script in the /root directory.

cd /root; wget https://raw.githubusercontent.com/srvrco/getssl/master/getssl; chmod +x getssl

Perform the initial configuration for your domain:

./getssl -c mydomain.com

After running the above, use an editor and open .getssl/mydomain.com/getssl.cfg. We are using the nano editor:

nano .getssl/mydomain.com/getssl.cfg

Scroll down to the line where you see:

#CA="https://acme-v01.api.letsencrypt.org"

Remove the hashtag in front of the above line.

Scroll down to the line where you see the ACL. Remove the ACL and replace with the following:

ACL=('/home/mako/www/.well-known/acme-challenge')

Note that the above line assumes the Mako Server is configured to load /home/mako/www as a root application.

Save the file and exit the editor. Make sure the Mako Server is running, and run the following command to fetch the certificate for your domain name:

./getssl mydomain.com

You should have a private key and a signed certificate in .getssl/mydomain.com/ if the above command succeeds.

Create the directory ~mako/certificates/ as user mako. Use an editor and open ~mako/mako.conf and enter the following:

certfile={ "certificates/mydomain.com.crt", } keyfile={ "certificates/mydomain.com.key", }

Save the file, and make sure the file is owned by user 'mako'.

Open /root/docert in an editor, paste in the following, and change the domain name:

#!/bin/bash cd /root ./getssl mydomain.com diff -q .getssl/mydomain.com/mydomain.com.crt ~mako/certificates/mydomain.com.crt if [ $? -ne 0 ] ; then cp .getssl/mydomain.com/mydomain.com.crt ~mako/certificates/ cp .getssl/mydomain.com/mydomain.com.key ~mako/certificates/ cd ~mako/certificates/ chown mako node4* cd /tmp wget localhost/newcert.lsp fi

Save the script and exit the editor. Run the following command to make the script executable:

chmod +x docert

The above script runs getssl for your domain name and copies the certificate and key to ~mako/certificates if the certificate has changed or is new. If the certificate is copied, the Mako Server must be notified. We could have restarted the Mako Server to reload the new certificate, but we will instead design a Lua script that enables us to reload the new certificate without having to restart the server. Notice the line where we run wget in the above bash script. The command activates the newcert.lsp script in the Mako Server's www directory.

Open ~mako/www/newcert.lsp in an editor, and paste in the following LSP/Lua code:

<?lsp local pn = request:peername() if ba.cmpaddr("::1", pn) or ba.cmpaddr("127.0.0.1", pn) then print(mako.loadcerts()) else response:senderror(404) end ?>

The above LSP page makes the Mako Server load the new certificate by calling mako.loadcerts().

The final step is to make sure the docert script runs at regular intervals. The script will check if it is time to upgrade the certificate and copy any new certificate to the Mako Server's certificate directory.

Run the following command:

crontab -e

In the cron script, paste in the following:

0 0 * * 0 /root/docert

Save the cron script. Cron will now run our docert script every Sunday at midnight.

Posted in Tutorials