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 acme.sh 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 https://get.acme.sh | sh

Now that the tool is installed, lets setup our certificate.

acme.sh --issue --dns dns_he -d yourdomain.com -d pbx.yourdomain.com --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.

acme.sh --issue --dns dns_he -d acme-test.voice1.me --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/.acme.sh/acme-test.voice1.me/acme-test.voice1.me.key
[Mon Jan 01 15:27:15 PST 2018] Single domain='acme-test.voice1.me'
[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='acme-test.voice1.me'
[Mon Jan 01 15:27:15 PST 2018] Getting new-authz for domain='acme-test.voice1.me'
[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/.acme.sh/dnsapi/dns_he.sh
[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] Verifying:acme-test.voice1.me
[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.
-----BEGIN CERTIFICATE-----
MIIFCTCCA/GgAwIBAgISA12J5WTITahjxX2FCZin7B6wMA0GCSqGSIb3DQEBCwUA
MEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD
ExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xODAxMjkyMjI5NDBaFw0x
ODA0MjkyMjI5NDBaMB4xHDAaBgNVBAMTE2FjbWUtdGVzdC52b2ljZTEubWUwggEi
MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDB9nvM21kfWviuGiak9uynRyx6
3Ize3MzIH1H+rWmBx0vsAfBuPle/3CmU/9hXAqAENOpkZsRyHnEgJ5yT/c+klZcN
V3pWULC4gOqSsFP9t11ABpdASXyX3yHlwsxQwxkf6LKS8v4aXyJ2ViRyMeZ34Jw7
VfErdRXqBAmGkTa+cdrQ+4hF2UcHVhbq3gYFZZV4R0OArXI94zhvOYNKYIEAzy3j
2Rd/9UtTS5tEHvFb+lEqkTia+6+T1QHq2oFSR0Hsp5V/VJbQLNZDLxopbRonRY3A
DVKDB3Ki8bk139fmcXLLE/jFEMRM35tU5A8flwmg+ZvxmarYaUV5Uz7QQx57AgMB
AAGjggITMIICDzAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEG
CCsGAQUFBwMCMAwGA1UdEwEB/wQCAL+8712KJD0OBBYEFGCr5YH6the1Kpbs/DSD
EetvikOYMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMG8GCCsGAQUF
BwEBBGMwYTAuBggrBgEFBQcwAYYiaHR0cDovL29jc3AuaW50LXgzLmxldHNlbmNy
eXB0Lm9yZzAvBggrBgEFBQcwAoYjaHR0cDovL2NlcnQuaW50LXgzLmxldHNlbmNy
eXB0Lm9yZy8wHgYDVR0RBBcwFYITYWNtZS10ZXN0LnZvaWNlMS5tZTCB/gYDVR0g
BIH2MIHzMAgGBmeBDAECATCB5gYLKwYBBAGC3xMBAQEwgdYwJgYIKwYBBQUHAgEW
Gmh0dHA6Ly9jcHMubGV0c2VuY3J5cHQub3JnMIGrBggrBgEFBQcCAjCBngyBm1Ro
aXMgQ2VydGlmaWNhdGUgbWF5IG9ubHkgYmUgcmVsaWVkIHVwb24gYnkgUmVseWlu
ZyBQYXJ0aWVzIGFuZCBvbmx5IGluIGFjY29yZGFuY2Ugd2l0aCB0aGUgQ2VydGlm
aWNhdGUgUG9saWN5IGZvdW5kIGF0IGh0dHBzOi8vbGV0c2VuY3J5cHQub3JnL3Jl
cG9zaXRvcnkvMA0GCSqGSIb3DQEBCwUAA4IBAQA+Yst80NGD9HXCUNI7Zh2fnRd+
plGqm1bdIzoqPhg2gfcw56sYGfVmIgQaDQM3z5SRXuyf7I2jkm6O4fVLH2CgaXy/
LYgkoT+YpMZhi1zps378Qi8pt26aw/HqhNHNID8jwkqDE4I28Aw/qFPmbfZYMGFf
IZpf4hPc8b0eMSV70Kc6In1zHNiOHCgxzWfcWRa0O+ZuERrsVZevlDWeCT3voTif
i5jXGibiXZbxBVFLnOqVgd7KX4GclmrOD2Cwtc5XdPGaqumZ23rOnQySyV+hRjR5
AjTDqbhYK/S5Wcw/gHmkyhqNlgHg4WcRArFN8z9KHXMpLZU/msVq2LoYnqDO
-----END CERTIFICATE-----
[Mon Jan 01 15:29:41 PST 2018] Your cert is in /root/.acme.sh/acme-test.voice1.me/acme-test.voice1.me.cer
[Mon Jan 01 15:29:41 PST 2018] Your cert key is in /root/.acme.sh/acme-test.voice1.me/acme-test.voice1.me.key
[Mon Jan 01 15:29:42 PST 2018] The intermediate CA cert is in /root/.acme.sh/acme-test.voice1.me/ca.cer
[Mon Jan 01 15:29:42 PST 2018] And the full chain certs is there: /root/.acme.sh/acme-test.voice1.me/fullchain.cer

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 acme.sh and the structure of their location may change in the future. Conveniently acme.sh provides us the option to ‘install’ our certificates where we would like. (Actually this just creates the files we need to use.)

acme.sh --install-cert -d acme-test.voice1.me --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 acme.sh 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 https://192.168.1.100/admin.

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

acme.sh 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 acme.sh –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.