Introduction
SSL or TLS Certificates are a known industry standard for encryption and security. They are used on basically every website today. This page aims to explain the different scenarios of implementing SSL Certificates on your jtel acd, as well as provide a walkthrough on how to do the installation itself.
Note
Technically SSL has not been used in a long time. Rather, TLS or Transport Layer Security has been the more secure successor to SSL and in use for a long time. However, the word SSL is still widely used to indicate this family of certificates, standards and functionality. We will as such also use the word SSL for the following explanation
Your jtel ACD With SSL
Access to your jtel ACD can be secured by SSL. A certificate is installed on the jtel Load Balancer to enable SSL-Encryption when accessing either your jtel portal, Chat or WhatsApp API, REST or SOAP API. In short anything you want to make available securely via the public internet.
There are some differences depending on the location of your system. If you have purchased a license within the jtel Cloud environment, your certificate will be provided and managed by jtel year-round. However, for example on On Premise systems, you will have to provide your own SSL-Certificate. As for our Partners Cloud systems, the certificate might be provided by you, or our partner.
jtel Cloud
The certificate is provided by jtel and managed year-round.
jtel Partner Cloud
On the cloud systems of our partners, the certificate will either be provided by our partner, or by you.
jtel On Premise
The certificate will be provided by you.
Preparations
If you are providing the SSL certificate for your jtel installation, the following things described below are required.
The DNS-Name used in this example is as follows:
jtel.example.com
The Gateway IP-Address used in this example is as follows:
xx.xxx.xx.xxx
Naming the Website / DNS
Before acquiring a new certificate or using a preexisting one, a name for the jtel Portal website must be chosen. Our example name is jtel.example.com
This name must then be configured in your Public DNS-Zone (Azure DNS, Google DNS, or the DNS of your internet provider) to ensure that traffic to this internet domain name will be routed to your gateway / firewall / router which handles your external IP address.
The IP-Address below will be the Public IP-Address of your gateway / firewall. The record type "A" indicates an "Address Record" and it is used to point the subdomain jtel.example.com to the IP address of the gateway / firewall / router.
| DNS-Name | Record Type | DNS-Zone | IP-Address |
|---|---|---|---|
| jtel | A | example.com | xx.xxx.xx.xxx |
Routing https requests
The gateway / firewall / router will need to be configured to route incoming https requests to port 443 to the internal IP address of the jtel load balancer.
This is usually achieved using 1:1 or Port Forwarding rules in the gateway / firewall concerned (how exactly to do this may vary from manufacturer to manufacturer and is not discussed in this article).
The certificate will be installed on the jtel load balancer which will decrypt the https-request and route the traffic to the webserver or chatserver using http.
A simplified explanation of the route could look as follows:
- https request from any device
- → Travel through public internet
- Your Gateway
- → Unchanged https request
- jtel Load Balancer
- → Decrypted http request
- jtel Webserver
SSL Certificate Chain
An SSL certificate chain consists of several parts which form a chain of certificates.
- Root certificates are trusted because most internet browsers and devices already trust the known root certificate authorities worldwide.
- Because the small number of root certificate authorities cannot be expected to deal with all browser requests worldwide, intermediate certificate authorities are used to distribute the load. Certificates which identify an intermediate certificate authority are issued by the root authority.
- There may be more than one intermediate certificate authority, which will be provided with a trusted certificate from the previously trusted intermediate certificate authority and so on. The last one will be trusted by the root.
- The server certificate is the one which identifies the end server, in our case jtel.example.com.
The server certificate contains the server's public key, which can be used to encrypt information which only the server will be able to decrypt (at least today, 11.07.2023, that is still the case but improvements in quantum computing may change this in the future ...).
The verification of the certificate chain uses the reverse direction:
- The certificate signature is verified using the public key in the issuer's certificate (next one down the chain)
- and so on
- Until the root certificate is reached. This certificate can be verified, because the browser knows this certificate to be a trusted entity and so can simply compare what it knows with what the server is providing in the certificate chain.
The full certificate chain is required for installation. This consists of more than one section:
| Certificate section | Explanation | Example Filename | Note |
|---|---|---|---|
End entity certificate Alias Server Certificate | This certificate section is a digitally signed statement issued by the Certificate Authority containing the public key and subject of the certificate. | end_entity_cetificate.crt | This certificate binds the public key to its contained identifying information (subject). The subject in our example would be jtel.example.com |
| Intermediate certificate | This certificate section is a certificate which is signed and authenticated by the Root certificate. The section acts as a middle-man between the End entity and root certificate. | intermediate_certificate.crt | More than one intermediate certificates can exist in a chain, but at least one is required. |
| Root certificate | A root certificate is a trusted certificate which sits at the top of the certificate chain. It identifies and belongs to the trusted CA (Certificate Authority). | root_certificate.crt | The root certificate is used to issue intermediate certificates. All certificates issued by a root certificate inherit the trust of the root certificate. |
| Private key | The private key is a unique key generated by the party who requests the certificate in a CSR (certificate signing request). It is the part of the chain which is always kept secret and never shared. It should if possible only be installed locally on the machine where the certificate chain is installed. | private_key.key | The private key is used to decrypt the incoming messages which were encrypted using the public key contained in the certificate. |
TLS
The last step is using TLS to establish secure communications.
This is a short explanation of how this works (by no means technically complete - there are plenty of good references out there if you really want to find out exactly how it works, however this explanation captures the essence of what is happening):
- The client contacts the server on port 443 and requests a secure connection
- The server responds using it's certificate chain (without the private key)
- The client verifies the certificate chain as described above
- The client generates a random encryption key which it sends to the server after encrypting it with the public key of the server provided in the certificate
- Only the server can decrypt this using the private key. It then uses the key generated by the client to encrypt a session key, which it sends back to the client.
- Only the client knows the random encryption key it used, and so it can decrypt the session key.
- Now, the session key is established, and the end to end encryption uses the symmetric session key for the duration of the TCP connection to encrypt all data.
Installation
If your system previously had no certificate installed and was running via http, start here. If you are exchanging your certificate before its expiry and your jtel ACD was configured for https before, start here.
Change the haproxy configuration to https
For systems with one Load Balancer and HAProxy use this.
For redundant systems with two Load Balancers and HaProxys use this.
Create the haproxy.pem file
The certificate chain will be put together with a simple cat command in Linux.
# Create a backup of the current haproxy.pem file if required cp /etc/haproxy/haproxy.pem /<backup-location>/haproxy.pem # Build the haproxy.pem Certificate file cat end_entity_cetificate.crt intermediate_certificate.crt root_certificate.crt private_key.key > haproxy.pem # copy the haproxy.pem file to the correct location on the Load Balancer cp <your-path-to-.pem>/haproxy.pem /etc/haproxy/haproxy.pem # change the file access rights cd /etc/haproxy/ chmod 400 haproxy.pem # reload the haproxy systemctl reload haproxy
Tests
After finishing, test access with your new https URL.
Example URL Admin
https://jtel.example.com/CarrierPortal/admin
Example URL Client
https://jtel.example.com/CarrierPortal/login/<ResellerUID>/<ClientUID>
Further Information
Further information regarding security and encryption can be found on these pages:
SSL/TLS Certificates - Self-signed certificate
SSL/TLS Certificates - Let's Encrypt Certificate
SSL/TLS Certificates - OCSP stapling
SSL/TLS Certificates - Connecting to the outside world
SSL/TLS Certificates - Configure haproxy for several subdomains
Useful openssl commands
openssl can be used to for example ensure that the end_entity_cetificate.crt and private_key.key match. It can also be used to ensure that the private key is not corrupted and to check the validity of the certificate itself.
Use the following commands if needed:
Checking the private key
Make sure the private key is not corrupted. If the output “RSA key ok“ then the private key is correct. openssl rsa -check -noout -in private_key.key
End entity and private key match
# Make sure the end entity certificate and the private key match together. Calculate the modulus of the of the private key openssl rsa -modulus -noout -in private_key.key | openssl md5 # Calculate the modulus of the server certificate openssl x509 -modulus -noout -in end_entity_certificate.crt| openssl md5 # If both outputs are identical then the private key matches to the end entity certificate.
Checking the certificate validity
openssl x509 -text -in haproxy.pem
Converting .pfx Certificates to .pem format
# The following command can be used to convert a .pfx certificate file to .pem Format (the password for the certificate will be required): openssl pkcs12 -in acd.cg.internal.pfx -out /root/haproxy.pem -nodes