Versions Compared

Old Version 9

changes.mady.by.user jtel Support

Saved on

compared with

New Version Current

changes.mady.by.user jtel Support

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Sv translation
languageen

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.

Info
titleNote

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.

Info

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-NameRecord TypeDNS-ZoneIP-Address
jtelAexample.comxx.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 sectionExplanationExample FilenameNote

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 acdjtel.example.com
Intermediate certificateThis 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 certificateA 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.

Anchor
http
http

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.

Anchor
https
https

Create the haproxy.pem file

The certificate chain will be put together with a simple cat command in Linux.

Code Block
titleGenerate the haproxy.pem file
# 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

Code Block
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

Code Block
# 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

Code Block
openssl x509 -text -in haproxy.pem

Converting .pfx Certificates to .pem format

Code Block
# 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


Sv translation
languagefr

Sv translation
languagede

Einführung

SSL- oder TLS-Zertifikate sind ein bekannter Industriestandard für Verschlüsselung und Sicherheit. Sie werden heute auf praktisch jeder Website verwendet. Auf dieser Seite werden die verschiedenen Szenarien für die Implementierung von SSL-Zertifikaten mit Ihrer jtel ACD erläutert und eine Anleitung für die Installation gegeben.

Info
titleNote

Technisch gesehen wird SSL schon seit langem nicht mehr verwendet. Vielmehr ist TLS oder Transport Layer Security der sicherere Nachfolger von SSL und seit langem in Gebrauch. Das Wort SSL wird jedoch immer noch häufig verwendet, um diese Familie von Zertifikaten, Standards und Funktionen zu bezeichnen. Wir werden daher auch für die folgende Erklärung das Wort SSL verwenden

Ihre jtel ACD Mit SSL

Der Zugang zu Ihrer jtel ACD kann durch SSL gesichert werden. Ein Zertifikat wird auf dem jtel Load Balancer installiert, um SSL-Verschlüsselung beim Zugriff auf Ihr jtel Portal, Chat oder WhatsApp API, REST oder SOAP API zu ermöglichen. Kurz gesagt, alles, was Sie sicher über das öffentliche Internet zugänglich machen wollen.

Je nach Standort Ihres Systems gibt es einige Unterschiede. Wenn Sie eine Lizenz in der jtel Cloud-Umgebung erworben haben, wird Ihr Zertifikat das ganze Jahr über von jtel bereitgestellt und verwaltet. Bei On-Premise-Systemen müssen Sie jedoch Ihr eigenes SSL-Zertifikat bereitstellen. Bei den Cloud-Systemen unserer Partner kann das Zertifikat von Ihnen oder von unserem Partner bereitgestellt werden.

jtel Cloud

Das Zertifikat wird von jtel bereitgestellt und ganzjährig verwaltet.

jtel Partner Cloud

Bei den Cloud-Systemen unserer Partner wird das Zertifikat entweder von unserem Partner oder von Ihnen bereitgestellt.

jtel On Premise

Das Zertifikat wird von Ihnen zur Verfügung gestellt.

Vorbereitung

Wenn Sie das SSL-Zertifikat für Ihre jtel-Installation zur Verfügung stellen, sind die folgenden Dinge erforderlich, die im Folgenden beschrieben werden.

Info

Der in diesem Beispiel verwendete DNS-Name lautet wie folgt:

jtel.beispiel.com

Der in diesem Beispiel verwendete DNS-Name lautet Die in diesem Beispiel verwendete Gateway-IP-Adresse lautet wie folgt: folgt:

xx.xxx.xx.xxx

Benennen der Website / DNS

Bevor Sie ein neues Zertifikat erwerben oder ein bereits vorhandenes verwenden, müssen Sie einen Namen für die Website des jtel Portals wählen. Unser Beispielname ist jtel.beispiel.com

Dieser Name muss dann in Ihrer öffentlichen DNS-Zone (Azure DNS, Google DNS oder das DNS Ihres Internet-Providers) konfiguriert werden, um sicherzustellen, dass der Datenverkehr zu diesem Internet-Domain-Namen zu Ihrem Gateway/Firewall/Router geleitet wird, der Ihre externe IP-Adresse verwaltet.

Die unten stehende IP-Adresse ist die öffentliche IP-Adresse Ihres Gateways / Ihrer Firewall. Der Eintragstyp "A" steht für einen "Adresseintrag" und wird verwendet, um die Subdomain jtel.beispiel.com auf die IP-Adresse des Gateways / der Firewall / des Routers zu verweisen.

DNS-NameEintragstypDNS-ZoneIP-Adresse
jtelAbeispiel.comxx.xxx.xx.xxx

Routen von https Anfragen 

Das Gateway / die Firewall / der Router muss so konfiguriert werden, dass eingehende https-Anfragen an Port 443 an die interne IP-Adresse des jtel Load Balancer weitergeleitet werden.

Dies wird in der Regel durch 1:1 oder Port-Weiterleitungsregeln im betreffenden Gateway / in der Firewall erreicht (wie genau dies zu bewerkstelligen ist, kann von Hersteller zu Hersteller variieren und wird in diesem Artikel nicht behandelt).

Das Zertifikat wird auf dem jtel Load Balancer installiert, der die https-Anfrage entschlüsselt und den Datenverkehr per http an den Webserver, Chatserver etc. weiterleitet.

Eine vereinfachte Erklärung der Route könnte wie folgt aussehen:

  • https Anfrage von einem Gerät
  • → Reise durch das öffentliche Internet
  • Ihr Gateway
  • → Unveränderte https Anfrage 
  • jtel Load Balancer
  • → Entschlüsselte http Anfrage
  • jtel Webserver

SSL Zertifikatskette

Eine SSL-Zertifikatskette besteht aus mehreren Teilen, die eine Kette von Zertifikaten bilden.

  • Stammzertifikate (Root certificates) sind vertrauenswürdig, da die meisten Internetbrowser und Geräte den weltweit bekannten Stammzertifizierungsstellen (root certificate authorities) bereits vertrauen.
  • Da die wenigen Stammzertifizierungsstellen nicht alle Browseranfragen weltweit bearbeiten können, werden Zwischenzertifizierungsstellen (intermediate certificate authorities) eingesetzt, um die Last zu verteilen. Zertifikate, die eine Zwischenzertifizierungsstelle identifizieren, werden von der Stammzertifizierungsstelle ausgestellt.
  • Es kann mehr als eine Zwischenzertifizierungsstelle geben, die mit einem vertrauenswürdigen Zertifikat von der zuvor vertrauenswürdigen Zwischenzertifizierungsstelle ausgestattet wird usw. Die letzte wird von der Stammzertifizierungsstelle als vertrauenswürdig eingestuft.
  • Das Serverzertifikat ist dasjenige, das den Endserver identifiziert, in unserem Fall jtel.example.com

Das Serverzertifikat enthält den öffentlichen Schlüssel des Servers, mit dem Informationen verschlüsselt werden können, die nur der Server entschlüsseln kann (zumindest ist das heute, am 11.07.2023, noch der Fall, aber Verbesserungen im Quantencomputing könnten dies in Zukunft ändern ...).

Die Überprüfung der Zertifikatskette erfolgt in umgekehrter Richtung:

  • Die Zertifikatsignatur wird anhand des öffentlichen Schlüssels im Zertifikat des Ausstellers (der nächste in der Kette) überprüft.
  • und so weiter
  • Bis das Stammzertifikat erreicht ist. Dieses Zertifikat kann verifiziert werden, da der Browser weiß, dass dieses Zertifikat eine vertrauenswürdige Instanz ist und daher einfach vergleichen kann, was er weiß, mit dem, was der Server in der Zertifikatskette angibt.

Die vollständige Zertifikatskette ist für die Installation erforderlich. Diese besteht aus mehr als einem Abschnitt:

Zertifikatsketten-SektionErklärungBeispiel DateinameNotiz

Endteilnehmer-Zertifikat

Alias Server Zertifikat

Dieser Zertifikatsabschnitt ist eine digital signierte Erklärung, die von der Zertifizierungsstelle ausgestellt wurde und den öffentlichen Schlüssel und den Betreff des Zertifikats enthält.

end_entity_cetificate.crt

Dieses Zertifikat bindet den öffentlichen Schlüssel (Public Key) an die darin enthaltenen Identifizierungsinformationen (Betreff).  Der Betreff in unserem Beispiel wäre jtel.beispiel.com
ZwischenzertifikatDieser Zertifikatsabschnitt ist ein Zertifikat, das vom Stammzertifikat signiert und authentifiziert wird. Der Abschnitt fungiert als Mittelsmann zwischen der Endinstanz (end entity) und dem Stammzertifikat (root-zertifikat).

intermediate_certificate.crt

Es kann mehr als ein Zwischenzertifikat in einer Kette geben, aber mindestens eines ist erforderlich.
StammzertifikatEin Stammzertifikat (root-zertifikat) ist ein vertrauenswürdiges Zertifikat, das an der Spitze der Zertifikatskette steht. Es identifiziert die vertrauenswürdige Zertifizierungsstelle (Certificate Authority) und gehört dieser.

root_certificate.crt

Das Stammzertifikat wird zur Ausstellung von Zwischenzertifikaten verwendet. Alle Zertifikate, die von einem Stammzertifikat ausgestellt werden, erben das Vertrauen des Stammzertifikats.
Privater Schlüssel

Der private Schlüssel ist ein eindeutiger Schlüssel, der von der Partei generiert wird, die das Zertifikat in einer CSR (Certificate Signing Request) beantragt.

Es ist der Teil der Kette, der immer geheim gehalten und niemals weitergegeben wird. Es sollte nach Möglichkeit nur lokal auf dem Rechner installiert werden, auf dem die Zertifikatskette installiert ist.

private_key.key

Der private Schlüssel wird zur Entschlüsselung der eingehenden Nachrichten verwendet, die mit dem im Zertifikat enthaltenen öffentlichen Schlüssel verschlüsselt wurden.

TLS

Der letzte Schritt ist die Verwendung von TLS, um eine sichere Kommunikation herzustellen.

Dies ist eine kurze Erläuterung der Funktionsweise (keineswegs technisch vollständig - es gibt viele gute Referenzen, wenn Sie wirklich herausfinden wollen, wie es genau funktioniert, aber diese Erklärung fasst das Wesentliche zusammen, was passiert):

  • Der Client kontaktiert den Server über Port 443 und fordert eine sichere Verbindung an
  • Der Server antwortet mit seiner Zertifikatskette (ohne den privaten Schlüssel)
  • Der Client verifiziert die Zertifikatskette wie oben beschrieben
  • Der Client generiert einen zufälligen Chiffrierschlüssel, den er an den Server sendet, nachdem er ihn mit dem im Zertifikat angegebenen öffentlichen Schlüssel des Servers verschlüsselt hat.
  • Nur der Server kann diesen mit Hilfe des privaten Schlüssels entschlüsseln. Anschließend verschlüsselt er mit dem vom Client generierten Schlüssel einen Sitzungsschlüssel, den er an den Client zurücksendet.
  • Nur der Client kennt den von ihm verwendeten zufälligen Verschlüsselungsschlüssel und kann daher den Sitzungsschlüssel entschlüsseln.
  • Nun wird der Sitzungsschlüssel festgelegt, und die Ende-zu-Ende-Verschlüsselung verwendet den symmetrischen Sitzungsschlüssel für die Dauer der TCP-Verbindung zur Verschlüsselung aller Daten.

Installation

Wenn ihr System zuvor kein Zertifikat installiert hatte und über http lief, beginnen Sie hier. Wenn Sie Ihr Zertifikat vor dessen Ablauf austauschen und Ihre jtel ACD zuvor für https konfiguriert war, beginnen Sie hier

Anchor
http
http

Ändern Sie die Haproxy-Konfiguration auf https

Für Systeme mit einem Load Balancer und HAProxy verwenden Sie dies.

Für redundante Systeme mit zwei Load Balancern und HaProxys verwenden Sie dies.

Anchor
https
https

haproxy.pem Datei erstellen

Die Zertifikatskette wird unter Linux mit einem einfachen cat-Befehl zusammengestellt.

Code Block
titleGenerate the haproxy.pem file
# Erstellen Sie bei Bedarf ein Backup der aktuellen haproxy.pem-Datei
cp /etc/haproxy/haproxy.pem /<backup-location>/haproxy.pem
# Erstellen Sie die Zertifikatsdatei haproxy.pem
cat end_entity_cetificate.crt intermediate_certificate.crt root_certificate.crt private_key.key > haproxy.pem
# Kopieren Sie die Datei haproxy.pem an den richtigen Ort auf dem Load Balancer
cp <your-path-to-.pem>/haproxy.pem /etc/haproxy/haproxy.pem
# die Dateizugriffsrechte ändern
cd /etc/haproxy/
chmod 400 haproxy.pem
# haproxy reload
systemctl reload haproxy

Tests

Testen Sie anschließend den Zugriff mit Ihrer neuen https-URL.

Beispiel URL Admin

https://jtel.example.com/CarrierPortal/admin

BeispielURL Client

https://jtel.example.com/CarrierPortal/login/<ResellerUID>/<ClientUID>

Weitere Information

Weitere Informationen zu Sicherheit und Verschlüsselung finden Sie auf diesen Seiten:

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

Nützliche openssl-Befehle

openssl kann zum Beispiel verwendet werden, um sicherzustellen, dass end_entity_cetificate.crt und private_key.key übereinstimmen. Es kann auch verwendet werden, um sicherzustellen, dass der private Schlüssel nicht beschädigt ist, und um die Gültigkeit des Zertifikats selbst zu überprüfen.

Verwenden Sie bei Bedarf die folgenden Befehle:

Prüfen des privaten Schlüssels

Code Block
Stellen Sie sicher, dass der private Schlüssel nicht beschädigt ist. Wenn die Ausgabe "RSA key ok" erscheint, ist der private Schlüssel korrekt.
openssl rsa -check -noout -in private_key.key

Endteilnehmer und privater Schlüssel stimmen überein

Code Block
# Stellen Sie sicher, dass das Endteilnehmerzertifikat und der private Schlüssel übereinstimmen. Berechnen Sie den Modulus des privaten Schlüssels
openssl rsa -modulus -noout -in private_key.key | openssl md5
# Berechnen Sie den Modulus des Server-Zertifikats
openssl x509 -modulus -noout -in end_entity_certificate.crt| openssl md5
# Wenn beide Ausgaben identisch sind, stimmt der private Schlüssel mit dem Endteilnehmerzertifikat überein.

Überprüfung der Gültigkeit des Zertifikats

Code Block
openssl x509 -text -in haproxy.pem

Konvertierung von .pfx-Zertifikaten in das .pem-Format

Code Block
# Der folgende Befehl kann verwendet werden, um eine .pfx-Zertifikatsdatei in das .pem-Format zu konvertieren (das Passwort für das Zertifikat wird benötigt):
openssl pkcs12 -in acd.cg.internal.pfx -out /root/haproxy.pem -nodes