FreePBX SSL Certificates 🔐
A quick guide on adding free SSL to FreePBX. A necessary step for using the Zulu 3 soft-phone!
Setting up SSL for FreePBX isn't normally high on the priority list, as it doesn't affects system operation. If you decide to use Zulu, you will require a certificate that isn't 'self signed' (that is, the certificate required must be signed by a Certificate Authority). As my PBX is used in a lab, I don't have any way of getting a commercial SSL certificate, so this guide will talk through setting up a free SSL certificate for FreePBX.
There are two ways that I will explore for setting up SSL on FreePBX - TinyCert to create our own Certificate Authority and sign our own SSL certificates and using Let's Encrypt via DNS verification.
Before we begin
Before doing anything, I recommend making a backup of your FreePBX instance. During my foray, I managed to screw up the cert and kill httpd. A backup would have made me feel a bit more comfortable when that happened!
TinyCert - Recommended
I recommend using TinyCert to generate your SSL certificate. I have used TinyCert for a few years now to manage 'my own' Certificate Authority. The certificate will also last for one year so requires less 'maintenance' than Let's Encrypt.
Most internal domains I use in my lab (and are not exposed outside of my network, like my PBX) have SSL enabled. The chances of a man-in-the-middle attack when using unexposed services are minimal, but who doesn't prefer seeing the little padlock icon? This method does require the installation of a certificate on all end-user devices in order to use SSL, so that needs to be a consideration.
If you have followed some of my articles on setting up FreePBX at Home, you'll know I have not exposed my PBX to the web, but I still need SSL for Zulu.
To use TinyCert, start off by signing up to their website. Go ahead and log in once registration is complete. During the sign up process, you'll set/get an SSL root key. This will be needed again so keep it safe!
Now, you can add your own certificate authority. Go ahead and put in the information you want to use.
Now, you can download your CA Certificate. This will need to be installed to every device you plan to use any TinyCert certificates on.
Here's a couple of generic guides for iOS and OSX from YouTube (there may be better examples out there!)
Next up, we'll create the certificate for FreePBX. It is as simple as entering the details required on-screen, though be sure to use the sub-domain in use as the common name. I used an easily recognisable name ('XGA PBX'), but this caused httpd to import the common name as the host name and killed the web service.
We can now download the certificates for FreePBX.
We need to download;
- Certificate
- Certificate chain
- Private key (encrypted)
Once we have the three required files, open them in TextEdit.
In FreePBX, go to Admin > Certificate Management > Upload certificate.
Name must only have alpha-numeric characters, add a description of your choosing & copy your 'SSL Root Key' to passphrase.
Copy the contents of the files downloaded earlier to the text boxes below:
- FreePBX Private Key - TinyCert Private Key (encrypted) [key.enc.pem]
- FreePBX Certificate - TinyCert Certificate [cert.pem]
- FreePBX Trusted Chain - TinyCert Certificate Chain [certchain.pem]
Click 'Generate Certificate' at the bottom of the page.
Now this certificate has been added, you can visit System Admin > HTTPS Setup > Settings and choose the certificate you have just added.
Let's Encrypt
Alternatively, you can use Let's Encrypt, or LE.
LE is a non-profit certificate authority. It provides free certificates for use across the web and has recently issued over a billion certificates.
LE can be automated by using tools like Caddy or CertBot. This can make simple & free SSL for public web-accessible services a reality.
Let's Encrypt HTTP Verification
FreePBX has the ability to generate LE certs directly from the Administration page. The issue with this is, it uses the HTTP (port 80) challenge - this requires the FreePBX web server to be accessible by Let's Encrypt - even though FreePBX tell us we shouldn't open port 80 to untrusted networks.
Let's Encrypt DNS Verification
It's also possible to use DNS verification to obtain a certificate with Get HTTPS for free. This is a bit involved and requires some command-line work, but you will end up with a certificate at the end of the process.
Before you begin, you will need access to the DNS records of the domain to add a TXT record for verification. You will also need to generate a CSR for use later on (Admin > Certificate Management, Generate CSR)
Clicking 'how do I generate this?' gives you some hints and tips as you progress through the verification process.
Once you have a certificate, go to Admin > Certificate Management & choose 'upload certificate'. You will need to match the CSR to the cert you have just created.
Troubleshooting
If you have issues after installing the cert, the best place to start looking is '/etc/httpd/logs'.
Apache is run via the service httpd, so 'systemctl status httpd' will also give you some good information.
The configuration file lives in '/etc/httpd/conf.d/ssl.conf', so if you see an error on line 24 (for example), using 'nano -c /etc/httpd/conf.d/ssl.conf' will open the Nano editor and using -c will display the line number at the bottom of the terminal.
Thanks!
Hopefully this guide was helpful for installing a free certificate into FreePBX. Get in touch with any suggestions: hi@xga.ie
