Securing Digium Switchvox with Letsencrypt

Adding Lets Encrypt SSL to Digium Switchvox

Digium Switchvox lets you install a custom SSL certificate. By doing so you are able to allow your your users to access your Switchvox using a common DNS name with out the need to click through SSL warnings. With the recent updates to Digium Switchvox around adding stronger SSL authentication checks, I thought it would be a good time to let everyone who does not currently have a commercial SSL Certificate, (or those who do) how to get one for free. The standard practice is to purchase a valid SSL certificate from a trusted authority and install it on your Digium Switchvox. But have you ever wanted to use a free certificate from Letsencrypt? 

If you do not know what letsencrypt (LE) is, take a look over at their website for a full description. For the purpose of this tutorial however all you need to know is that LE allows you to request an SSL certificate in an automated method. The certificates are valid for only 90 days vs a standard purchased SSL is valid for 365 days up to 3yrs.

As LE gains in popularity many services are adding the SSL service to their products to help clients secure the devices and services. At this time however Digium Switchvox does not do this, and there are several reasons why this poses a support challenge. You can however install a valid LE certificate and this tutorial will walk you through just how to do that.

Keep in mind that you will need to update your certificate every 90 days. And this may prove reason enough to just purchase a commercially available SSL Certificate. You can do so here if you like for only $29.00 per year. But that would defeat the purpose of this tutorial.

To start with we will need to get the software installed on a computer. For this purpose we are using the shell script and not the officially supported certbot client. We are using this utility because in the future we want to create a lightweight docker image to automate our process.

We also are going to need to use DNS authentication of our domains. This is because we want to automate as much as possible, and because the current draft of v2 API will allow wildcard certificates, which can only be authenticated with DNS. In our case we will use Hurricane Electrics free DNS service. There are others and yours might well be supported as well. This also adds the ability for us to create SSL certificates from a separate system, rather then from the primary system the certificate is to be deployed on.

Lets grab the tools.

curl | sh

Now that the tool is installed, lets setup our certificate. --issue --dns dns_he -d -d --force

This will create all the stuff needed to issue a signing request and get your certificate. At the end you will see a message like the following. --issue --dns dns_he -d --force
[Mon Jan 01 15:27:15 PST 2018] Creating domain key
[Mon Jan 01 15:27:15 PST 2018] The domain key is here: /root/
[Mon Jan 01 15:27:15 PST 2018] Single domain=''
[Mon Jan 01 15:27:15 PST 2018] Getting domain auth token for each domain
[Mon Jan 01 15:27:15 PST 2018] Getting webroot for domain=''
[Mon Jan 01 15:27:15 PST 2018] Getting new-authz for domain=''
[Mon Jan 01 15:27:23 PST 2018] The new-authz request is ok.
[Mon Jan 01 15:27:23 PST 2018] Found domain api file: /root/
[Mon Jan 01 15:27:23 PST 2018] Using DNS-01 Hurricane Electric hook
[Mon Jan 01 15:27:24 PST 2018] TXT record added successfully.
[Mon Jan 01 15:27:24 PST 2018] Sleep 120 seconds for the txt records to take effect
[Mon Jan 01 15:29:25 PST 2018]
[Mon Jan 01 15:29:33 PST 2018] Success
[Mon Jan 01 15:29:33 PST 2018] Cleaning up after DNS-01 Hurricane Electric hook
[Mon Jan 01 15:29:38 PST 2018] Record removed successfully.
[Mon Jan 01 15:29:38 PST 2018] Verify finished, start to sign.
[Mon Jan 01 15:29:41 PST 2018] Cert success.
[Mon Jan 01 15:29:41 PST 2018] Your cert is in /root/
[Mon Jan 01 15:29:41 PST 2018] Your cert key is in /root/
[Mon Jan 01 15:29:42 PST 2018] The intermediate CA cert is in /root/
[Mon Jan 01 15:29:42 PST 2018] And the full chain certs is there: /root/

Please note, using the DNS method you do not have to have a valid A, AAAA record. Only the ability to create the needed TXT record. This also allows you to provision off several domains before you know the related A records.

Note the 4 lines at the end of the output. They tell you where the certificates are installed. HOWEVER DO NOT COPY THEM!!!!

Generating the SSL Certificates

While these are perfectly valid SSL certificates, they are used internally by and the structure of their location may change in the future. Conveniently provides us the option to ‘install’ our certificates where we would like. (Actually this just creates the files we need to use.) --install-cert -d --cert-file ~/certificate.pem --key-file ~/key.pem --ca-file ~/ca-intermediate.pem --fullchain-file ~/fullchain.pem

You should see the output

[Mon Jan 01 15:44:54 PST 2018] Installing cert to:/root/certificate.pem
[Mon Jan 01 15:44:54 PST 2018] Installing CA to:/root/ca-intermediate.pem
[Mon Jan 01 15:44:54 PST 2018] Installing key to:/root/key.pem
[Mon Jan 01 15:44:54 PST 2018] Installing full chain to:/root/fullchain.pem

And in the directory specified you will see all 4 files:

ls -l
total 16
-rw-r--r-- 1 root root 1647 Jan 01 15:44 ca-intermediate.pem
-rw-r--r-- 1 root root 1805 Jan 01 15:44 certificate.pem
-rw-r--r-- 1 root root 3452 Jan 01 15:44 fullchain.pem
-rwx------ 1 root root 1679 Jan 01 15:44 key.pem

If you notice the utility set the permissions on key.pem to allow only the owner (root) to access the file.

These file are now needed to add your SSL Certificate to your Switchvox PBX. Login to your Switchvox Admin interface

Navigate to Server > Networking > HTTPs & Proxy

From here you will copy and paste the certificate.pem, key.pem and ca-intermediate.pem and click the blue Save HTTPS and Proxy button.

Your PBX will save the configurations and restart your network interface and services. (THIS WILL CAUSE YOU TO DROP CALLS) so don’t do this during production hours. You may additionally need to restart your browser to allow it to clear its cache.

You should then end up with a valid SSL certificate in your Switchvox PBX.

To renew this certificate, simply issue the command:

Renewing Certificates will automatically attempt to renew the certificate, as it installed a cronjob to automatically run for you.  Set a calendar reminder for 80 days from the day you generated your SSL certificate and log back in and simply reissue the –install-cert command referenced in the section “Generating the SSL Certificates” to recreate the new certificates, and copy them to your Swtichvox.


The next step…

As you can tell there is still a little manual work. You could refine this process a little by creating a new bash script that automatically emailed or copied the files for you and sent you a notification of the renewals. And of course you may be asking, Can’t I just automatically push the certificate into the Switchvox? We will discover the answer to those questions in the future, for now however, I hope you enjoy your new free SSL Certificate.


One thought on “Securing Digium Switchvox with Letsencrypt

  1. Pingback:Enabling Switchvox remote workers | VOICE1 LLC - 1.855.252.8788

Comments are closed.