Wie SSL in smoxy funktioniert

SSL/TLS-Zertifikate sind entscheidend, um den Datenverkehr zwischen Besuchern und smoxy sowie zwischen smoxy und den Origin-Servern abzusichern. smoxy bietet einen vollständig integrierten Zertifikats-Lebenszyklus - von der automatischen Generierung über Let's Encrypt bis hin zum manuellen Upload eigener Zertifikate.

Diese Anleitung erklärt, wie SSL in smoxy funktioniert, welche Zertifikatstypen verfügbar sind und wie smoxy Zertifikate verwaltet.

---

SSL-Zertifikatstypen

smoxy unterstützt zwei Arten von SSL-Zertifikaten:

Typ	Erstellt von	Erneuert von	Geeignet für
Automatisch verwaltet (Empfohlen)	smoxy über Let's Encrypt	smoxy (automatisch)	Die meisten Nutzer - kein Wartungsaufwand
Selbst verwaltet	Nutzer	Nutzer (manuell)	Enterprise-Zertifikate, EV-Zertifikate, spezielle Compliance-Anforderungen

Automatisch verwaltete Zertifikate (Empfohlen)

Beim Hinzufügen einer Domain in smoxy wird automatisch ein Wildcard-SSL-Zertifikat erstellt. Dieses Zertifikat deckt ab:

• example.com
• *.example.com (alle Subdomains)

Das Zertifikat wird über Let's Encrypt mittels DNS-basierter Validierung (ACME-Protokoll) ausgestellt. smoxy übernimmt den gesamten Lebenszyklus:

1. Zertifikatsanforderung
2. DNS-Challenge-Verifizierung
3. Zertifikatsausstellung
4. Automatische Erneuerung (gesteuert durch das empfohlene Erneuerungsfenster der CA)

Selbst verwaltete Zertifikate

Wenn ein eigenes Zertifikat verwendet werden muss (z. B. Extended Validation, organisationsspezifische Anforderungen), lässt es sich manuell hochladen.

Anforderungen:

• Zertifikatsdatei im PEM-Format
• Private-Key-Datei im PEM-Format
• Der Private Key muss zum Zertifikat passen
• Das Zertifikat darf nicht abgelaufen sein
• Das Zertifikat muss die zu verwendenden Domain(s) abdecken

INFO

Wichtig: smoxy kann manuell hochgeladene Zertifikate nicht automatisch erneuern. Es liegt in der Verantwortung des Nutzers, ein neues Zertifikat hochzuladen, bevor das aktuelle abläuft.

---

Wie die Zertifikatsgenerierung funktioniert

Schritt 1: DNS-Verifizierung

Für jeden Subject Alternative Name (SAN) auf dem Zertifikat benötigt smoxy einen CNAME-Eintrag, der auf die ACME-Verifizierungsinfrastruktur von smoxy zeigt:

_acme-challenge.example.com  →  example.com.acme.smoxy.eu.

Dieser CNAME-Eintrag ermöglicht es smoxy, die ACME DNS-01 Challenge durchzuführen, die von Let's Encrypt benötigt wird. Das Ziel ist die Domain des SANs selbst, gefolgt von .acme.smoxy.eu. (einschließlich des abschließenden Punkts). Der genaue Wert für jeden SAN wird im Tab SANs des Zertifikats angezeigt und lässt sich von dort kopieren.

INFO

Wichtig: Bei Nutzung von Cloudflare muss der Cloudflare-Proxy für den _acme-challenge CNAME-Eintrag deaktiviert sein. Weitere Informationen unter Cloudflare Setup.

Schritt 2: Zertifikatsausstellung

Sobald alle DNS-Einträge verifiziert sind, führt smoxy automatisch folgende Schritte aus:

1. Anforderung eines Zertifikats bei Let's Encrypt
2. Abschluss der ACME-Challenge
3. Download und Installation des Zertifikats
4. Aktivierung des Zertifikats für die Hostnamen

Schritt 3: Automatische Erneuerung

smoxy überwacht den Ablauf von Zertifikaten und erneuert automatisch. Der Zeitpunkt der Erneuerung richtet sich nach dem empfohlenen Erneuerungsfenster der CA (ACME Renewal Information, ARI); ist kein Fenster verfügbar, erneuert smoxy ersatzweise etwa zwei Wochen vor Ablauf. Die Erneuerung folgt dem gleichen Verifizierungsablauf - wenn die DNS-Einträge noch vorhanden sind, erfolgt sie vollständig automatisch.

---

Subject Alternative Names (SANs)

Ein Subject Alternative Name (SAN) ist ein einzelner Domainname, der von einem SSL-Zertifikat abgedeckt wird. Beim Erstellen einer neuen Domain in smoxy werden zwei Standard-SANs hinzugefügt:

• example.com - die Root-Domain
• *.example.com - Wildcard für alle Subdomains

Zusätzliche SANs hinzufügen

Wenn zusätzliche spezifische Subdomains abgedeckt werden müssen (z. B. spezifisch.sub.example.com, die nicht vom Wildcard abgedeckt wird), kann smoxy zusätzliche SANs zum Zertifikat hinzufügen. Jeder SAN benötigt seinen eigenen _acme-challenge CNAME-Eintrag zur DNS-Verifizierung.

Wird ein solcher Hostname einer Zone hinzugefügt und das DNS der Domain von smoxy verwaltet, kann das automatisch geschehen: smoxy bietet an, den fehlenden SAN hinzuzufügen, den Validierungseintrag anzulegen und die Zertifikatserneuerung in einem Schritt auszulösen. Siehe Automatische DNS-Einrichtung.

SAN-Status

Jeder SAN hat zwei unabhängige Status:

Status	Werte	Bedeutung
DNS-Status	Unknown / Valid / Missing	Ob der _acme-challenge CNAME-Eintrag korrekt konfiguriert ist. Unknown bedeutet, dass noch keine Prüfung erfolgt ist; Missing umfasst jeden Fall, in dem der erwartete Eintrag nicht gefunden wird - auch einen CNAME, der auf das falsche Ziel zeigt, oder einen kollidierenden TXT-Eintrag
SSL-Status	Covered / Not covered	Ob das aktuelle Zertifikat diese Domain tatsächlich enthält

smoxy überprüft regelmäßig die DNS-Einträge:

• Alle 24 Stunden für gültige Einträge (um eine Entfernung zu erkennen)
• Jede 1 Stunde für fehlende Einträge (um nachträgliches Hinzufügen zu erkennen)

Über den SANs-Tab lässt sich mit DNS erneut prüfen zusätzlich eine manuelle Prüfung auslösen. Danach plant smoxy die nächste automatische Prüfung in 24 Stunden für einen weiterhin gültigen Eintrag oder in 5 Minuten für einen weiterhin fehlenden.

Wenn neue SANs hinzugefügt und deren DNS verifiziert wurde, löst smoxy automatisch eine Zertifikatserneuerung aus, um die neuen Domains einzuschließen.

---

Zertifikatsstatus

Das SSL-Zertifikat in smoxy kann sich in einem der folgenden Zustände befinden:

Status	Bedeutung	Handlungsbedarf
Pending	Zertifikatsgenerierung wurde gestartet, ist aber noch nicht abgeschlossen	Auf den Abschluss der Generierung warten
Active	Zertifikat ist gültig und funktioniert	Keiner
Renewing	Eine Erneuerung läuft	Keiner - smoxy erledigt dies automatisch
Expired	Das Zertifikat hat sein Ablaufdatum überschritten	Automatisch verwaltet: die _acme-challenge-Einträge prüfen, damit die Erneuerung abschließen kann. Selbst verwaltet: ein neues Zertifikat hochladen
Failed	Generierung oder Erneuerung des Zertifikats ist fehlgeschlagen	Den DNS-Status jedes SANs und den letzten Versuch auf den konkreten Fehler prüfen

INFO

Hinweis: DNS-Probleme erscheinen nicht als Zertifikatsstatus, sondern zeigen sich pro SAN als DNS-Status Missing auf dem SANs-Tab. Häufige Ursachen sind ein fehlender _acme-challenge CNAME-Eintrag, ein CNAME, der auf das falsche Ziel zeigt, oder ein kollidierender TXT-Eintrag für _acme-challenge. Wie sich diese jeweils beheben lassen, zeigt die SSL-Fehlerbehebung.

---

Workflow der Zertifikatsgenerierung

Im Hintergrund verfolgt smoxy die Zertifikatsgenerierung durch einen detaillierten Workflow:

Der Tab „Versuche“: jeder Zertifikats-Generierungsversuch mit seiner schrittweisen Timeline.

Jede Generierung oder Erneuerung wird als Versuch erfasst, der Processing, Succeeded oder Failed ist. Ein Versuch durchläuft der Reihe nach die folgenden Schritte:

Schritt	Was passiert
Initialize	Der Versuch wird eingerichtet
Verify CNAME Record	Prüft die _acme-challenge CNAME-Einträge für alle SANs
Create ACME Order	Fordert eine Zertifikatsbestellung bei Let's Encrypt an
Provision DNS Record	Legt den DNS-01-Challenge-Eintrag an
Await DNS Propagation	Wartet, bis der Challenge-Eintrag auflösbar ist
Authorize	Lässt die CA die Challenge validieren
Poll Order Status	Wartet, bis die Bestellung bereit ist
Download Certificate	Lädt das ausgestellte Zertifikat herunter
Save Certificate	Speichert und aktiviert das Zertifikat

Wenn ein vorübergehender Fehler während der Generierung auftritt, versucht smoxy es automatisch mit exponentiellem Backoff erneut. Die möglichen Fehler fallen in zwei Gruppen - Probleme im ACME-/DNS-Ablauf bei automatisch verwalteten Zertifikaten und Validierungsfehler beim Hochladen eines benutzerdefinierten Zertifikats:

Fehler	Ursache	Lösung
Rate limit	Zu viele Zertifikatsanfragen bei Let's Encrypt	Automatisch - smoxy wartet und versucht es später erneut
CNAME record missing	Der _acme-challenge CNAME-Eintrag fehlt für einen oder mehrere SANs	Den/die fehlenden CNAME-Eintrag/Einträge hinzufügen. Bei Cloudflare den Proxy für den Challenge-Eintrag deaktivieren (siehe Cloudflare Setup)
CNAME record invalid	Der CNAME-Eintrag existiert, zeigt aber auf das falsche Ziel	Den CNAME auf das exakte Ziel aktualisieren, das im SANs-Tab angezeigt wird
DNS provisioning failed	smoxy konnte den DNS-01-Challenge-Eintrag nicht anlegen	Vorübergehend - smoxy versucht es automatisch erneut
ACME error	Die Zertifizierungsstelle hat einen Fehler gemeldet	DNS-Propagierung prüfen; smoxy versucht es automatisch erneut
Invalid PEM	Ein hochgeladenes Zertifikat oder ein Schlüssel enthält keine gültigen PEM-Daten	Die Datei im PEM-Format neu exportieren und erneut hochladen
Key mismatch	Der hochgeladene Private Key passt nicht zum Zertifikat	Den Private Key hochladen, der zum Zertifikat gehört
Certificate expired	Das hochgeladene Zertifikat ist bereits abgelaufen	Ein aktuelles Zertifikat beschaffen und hochladen
SAN mismatch	Das hochgeladene Zertifikat deckt nicht alle konfigurierten SANs ab	Ein Zertifikat verwenden, das die Domains abdeckt
Invalid chain	Die hochgeladene Kette / das Zwischenzertifikat enthält keine gültigen PEM-Daten	Eine gültige Zwischenzertifikatskette im Feld Chain-PEM angeben
Internal error	Ein unerwarteter Fehler ist aufgetreten	Erneut versuchen; bei anhaltendem Fehler den Support kontaktieren

---

Selbst verwaltetes Zertifikat hochladen

Um ein eigenes SSL-Zertifikat hochzuladen:

1. In der smoxy-Seitenleiste SSL-Zertifikate öffnen
2. Auf Neues Zertifikat klicken, um den Dialog Neues SSL-Zertifikat zu öffnen
3. Als Typ die Option Benutzerdefiniert wählen
4. Bereitstellen:
   • Zertifikat-PEM: Das Server-Zertifikat im PEM-Format
   • Privater-Schlüssel-PEM: Der passende private Schlüssel
   • Chain-PEM (optional): Etwaige Zwischenzertifikate, in diesem separaten Feld

Validierung

Beim Upload validiert smoxy:

• Das Zertifikat ist parsebar und im gültigen PEM-Format
• Der Private Key passt zum Zertifikat
• Das Zertifikat ist nicht abgelaufen
• Die SANs im Zertifikat decken die Domain ab

Wenn sich die SANs im neuen Zertifikat von den aktuellen unterscheiden, zeigt smoxy die Unterschiede an und bittet um Bestätigung, bevor fortgefahren wird.

Nach dem Upload

• Das vorherige Zertifikat wird zu Audit-Zwecken archiviert
• Das neue Zertifikat wird sofort aktiviert
• Da selbst verwaltete Zertifikate nicht automatisch erneuert werden, muss vor Ablauf ein Ersatzzertifikat hochgeladen werden

---

Wildcard-Zertifikate

smoxy erstellt standardmäßig Wildcard-Zertifikate. Ein Wildcard-Zertifikat für *.example.com deckt ab:

• www.example.com
• shop.example.com
• api.example.com
• Jede andere einstufige Subdomain

Was Wildcards NICHT abdecken:

• Die Root-Domain selbst (example.com) - diese wird als separater SAN hinzugefügt
• Mehrstufige Subdomains (sub.sub.example.com) - diese benötigen zusätzliche SANs

Beim Hinzufügen eines Hostnamens wie shop.example.com zu einer smoxy-Zone (der Beschleunigungs- und Sicherheitskonfiguration für einen Hostnamen - zu unterscheiden von einer DNS-Zone) prüft smoxy, ob das vorhandene Wildcard-Zertifikat ihn bereits abdeckt. Falls ja, ist keine zusätzliche Zertifikatsarbeit erforderlich.

---

Zertifikate herunterladen

Das SSL-Zertifikat und der Private Key lassen sich zur Verwendung in externen Tools herunterladen:

1. In der smoxy-Seitenleiste SSL-Zertifikate öffnen und das Zertifikat auswählen
2. Über die Download-Schaltflächen das Zertifikat, die Chain oder den privaten Schlüssel herunterladen

Erforderliche Rolle: Owner oder Manager

---

Subdomain-Wiederverwendung

Beim Erstellen der Hauptdomain (z. B. example.com) wird ein Wildcard-Zertifikat generiert, das alle Subdomains wiederverwenden können. Beim Hinzufügen von Subdomains als Hostnamen zu Zonen:

• Es ist keine zusätzliche DNS-Verifizierung für die Subdomain erforderlich
• Das vorhandene Wildcard-Zertifikat deckt die Subdomain automatisch ab
• Dies beschleunigt die Einrichtung zusätzlicher Hostnamen erheblich

INFO

Empfehlung: Immer zuerst die Hauptdomain erstellen und dann die Subdomains hinzufügen. So ist sichergestellt, dass das Wildcard-Zertifikat vorhanden ist und Subdomains ohne zusätzliche SSL-Schritte konfiguriert werden können.

---

Fehlerbehebung

Zertifikat bleibt im Status „Pending"

• Prüfen, ob alle erforderlichen _acme-challenge CNAME-Einträge beim DNS-Anbieter gesetzt sind
• Die DNS-Propagierung kann bis zu 48 Stunden dauern (normalerweise aber deutlich schneller)
• Bei Nutzung von Cloudflare sicherstellen, dass der Proxy für Challenge-Einträge deaktiviert ist

DNS-Status „Missing": Eintrag nicht gefunden

Der _acme-challenge CNAME-Eintrag wurde nicht gefunden. Prüfen:

• Der Eintrag existiert beim DNS-Anbieter
• Er zeigt auf das korrekte Ziel (im SANs-Tab des Zertifikats angezeigt)
• Der DNS hatte genug Zeit zur Propagierung

DNS-Status „Missing": CNAME zeigt auf das falsche Ziel

Der CNAME-Eintrag existiert, zeigt aber auf ein falsches Ziel und gilt daher weiterhin als Missing. Den Eintrag auf das exakte Ziel aktualisieren, das im SANs-Tab des Zertifikats angezeigt wird.

DNS-Status „Missing": kollidierender TXT-Eintrag

Ein TXT-Eintrag für _acme-challenge existiert neben oder anstelle des erforderlichen CNAME, was ebenfalls zu einem Missing-Status führt. Den TXT-Eintrag entfernen und sicherstellen, dass nur der CNAME-Eintrag existiert.

Zertifikat erneuert sich nicht

• Automatisch verwaltete Zertifikate erneuern sich automatisch innerhalb des empfohlenen Erneuerungsfensters der CA (ersatzweise etwa zwei Wochen vor Ablauf)
• Sicherstellen, dass die _acme-challenge CNAME-Einträge noch vorhanden sind
• Selbst verwaltete Zertifikate werden niemals automatisch erneuert - ein Ersatzzertifikat muss hochgeladen werden

SAN-Änderungen werden nicht übernommen

Nach dem Hinzufügen neuer SANs muss smoxy das Zertifikat neu generieren. Das geschieht automatisch, sobald die DNS-Verifizierung für den neuen SAN bestanden ist. Den DNS-Status des SANs im SANs-Tab des Zertifikats prüfen.