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:

• ihredomain.com
• *.ihredomain.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 (30 Tage vor Ablauf)

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.ihredomain.com  →  ihre-org.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.

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 startet den Erneuerungsprozess 30 Tage vor Ablauf. Die Erneuerung folgt dem gleichen Verifizierungsablauf. Wenn die DNS-Einträge noch vorhanden sind, erfolgt die Erneuerung 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:

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

Zusätzliche SANs hinzufügen

Wenn zusätzliche spezifische Subdomains abgedeckt werden müssen (z. B. spezifisch.sub.ihredomain.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.

SAN-Status

Jeder SAN hat zwei unabhängige Status:

Status	Werte	Bedeutung
DNS-Status	Valid / Missing	Ob der _acme-challenge CNAME-Eintrag korrekt konfiguriert ist
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 12 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)

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
Active	Zertifikat ist gültig und funktioniert	Keiner
Pending	Zertifikatsgenerierung wurde gestartet, ist aber noch nicht abgeschlossen	Auf den Abschluss der Generierung warten
DNS Missing	Der _acme-challenge CNAME-Eintrag existiert nicht	Den erforderlichen CNAME-Eintrag beim DNS-Anbieter hinzufügen
DNS Wrong	Der CNAME-Eintrag existiert, zeigt aber auf das falsche Ziel	Den CNAME auf das korrekte smoxy-Ziel aktualisieren
DNS Duplicate	Ein TXT-Eintrag existiert für _acme-challenge anstelle des erforderlichen CNAME	Den TXT-Eintrag entfernen und stattdessen einen CNAME-Eintrag anlegen

INFO

Hinweis: Mehrere DNS-Probleme können gleichzeitig auftreten (z. B. können einige SANs fehlende Einträge haben, während andere auf falsche Ziele zeigen).

---

Workflow der Zertifikatsgenerierung

Im Hintergrund verfolgt smoxy die Zertifikatsgenerierung durch einen detaillierten Workflow:

Phase	Was passiert
Pending	Generierungsanfrage ist in der Warteschlange
Starting	Worker nimmt die Anfrage auf
CNAME Check	Verifizierung der DNS-Einträge für alle SANs
Ordering	Anforderung des Zertifikats bei Let's Encrypt
Validating	ACME-Challenge-Validierung läuft
Completed	Zertifikat erfolgreich ausgestellt und installiert

Wenn ein Fehler während der Generierung auftritt, versucht smoxy es automatisch mit exponentiellem Backoff erneut. Häufige Fehler sind:

Fehler	Ursache	Lösung
CNAME not found	DNS-Eintrag fehlt für einen oder mehrere SANs	Den/die fehlenden CNAME-Eintrag/Einträge hinzufügen
TXT record exists	Ein TXT-Eintrag für _acme-challenge kollidiert mit dem CNAME	Den TXT-Eintrag entfernen, nur den CNAME behalten
Rate limit	Zu viele Zertifikatsanfragen bei Let's Encrypt	Automatisch — smoxy wartet und versucht es nach 1 Stunde erneut
Validation failed	ACME-Challenge konnte nicht verifiziert werden	DNS-Propagierung prüfen; smoxy versucht es automatisch erneut
Cloudflare error	Cloudflare-Proxy stört die DNS-Verifizierung	Cloudflare-Proxy für den _acme-challenge Eintrag deaktivieren

---

Selbst verwaltetes Zertifikat hochladen

Um ein eigenes SSL-Zertifikat hochzuladen:

1. Zu Domains & DNS navigieren und die Domain auswählen
2. Zum SSL-Tab wechseln
3. Auf Eigenes SSL-Zertifikat hochladen klicken
4. Bereitstellen:
   • Zertifikat (PEM-Format): Die vollständige Zertifikatskette, einschließlich Zwischenzertifikate
   • Private Key (PEM-Format): Der passende private Schlüssel

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 *.ihredomain.com deckt ab:

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

Was Wildcards NICHT abdecken:

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

Beim Hinzufügen eines Hostnamens wie shop.ihredomain.com zu einer Site 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. Zu Domains & DNS navigieren und die Domain auswählen
2. Zum SSL-Tab wechseln
3. Auf den Download-Button für das Zertifikat oder den Schlüssel klicken

Erforderliche Rolle: Owner oder Maintainer

---

Subdomain-Wiederverwendung

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

• 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

Status „DNS Missing"

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

• Der Eintrag existiert beim DNS-Anbieter
• Er zeigt auf das korrekte Ziel (in smoxy angezeigt)
• Der DNS hatte genug Zeit zur Propagierung

Status „DNS Wrong"

Der CNAME-Eintrag existiert, zeigt aber auf ein falsches Ziel. Den Eintrag auf das in smoxy angezeigte Ziel aktualisieren.

Status „DNS Duplicate"

Ein TXT-Eintrag für _acme-challenge existiert neben oder anstelle des erforderlichen CNAME. Den TXT-Eintrag entfernen und sicherstellen, dass nur der CNAME-Eintrag existiert.

Zertifikat erneuert sich nicht

• Automatisch verwaltete Zertifikate erneuern sich automatisch 30 Tage 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 SSL-Tab prüfen.