# Wie SSL in smoxy funktioniert

SSL/TLS-Zertifikate sind entscheidend, um den Datenverkehr zwischen deinen Besuchern und smoxy sowie zwischen smoxy und deinen 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 für dich 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**                  | Du                       | Du (manuell)        | Enterprise-Zertifikate, EV-Zertifikate, spezielle Compliance-Anforderungen |

#### Automatisch verwaltete Zertifikate (Empfohlen)

Wenn du eine Domain in smoxy hinzufügst, wird automatisch ein **Wildcard-SSL-Zertifikat** erstellt. Dieses Zertifikat deckt ab:

* `deinedomain.com`
* `*.deinedomain.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 du ein eigenes Zertifikat verwenden musst (z. B. Extended Validation, organisationsspezifische Anforderungen), kannst du es 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 Domain(s) abdecken, die du verwenden möchtest

{% hint style="info" %}
**Wichtig:** smoxy kann manuell hochgeladene Zertifikate nicht automatisch erneuern. Du bist dafür verantwortlich, ein neues Zertifikat hochzuladen, bevor das aktuelle abläuft.
{% endhint %}

***

### 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.deinedomain.com  →  deine-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.

{% hint style="info" %}
**Wichtig:** Wenn du Cloudflare verwendest, muss der Cloudflare-Proxy für den `_acme-challenge` CNAME-Eintrag **deaktiviert** sein. Weitere Informationen findest du unter Cloudflare Setup.
{% endhint %}

#### 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 deine 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. Wenn du eine neue Domain in smoxy erstellst, werden zwei Standard-SANs hinzugefügt:

* `deinedomain.com` — die Root-Domain
* `*.deinedomain.com` — Wildcard für alle Subdomains

#### Zusätzliche SANs hinzufügen

Wenn du zusätzliche spezifische Subdomains abdecken musst (z. B. `spezifisch.sub.deinedomain.com`, die nicht vom Wildcard abgedeckt wird), kann smoxy zusätzliche SANs zu deinem 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 zu erkennen, wenn du sie hinzugefügt hast)

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

***

### Zertifikatsstatus

Dein 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         | Warte auf den Abschluss der Generierung                               |
| **DNS Missing**   | Der `_acme-challenge` CNAME-Eintrag existiert nicht                               | Füge den erforderlichen CNAME-Eintrag bei deinem DNS-Anbieter hinzu   |
| **DNS Wrong**     | Der CNAME-Eintrag existiert, zeigt aber auf das falsche Ziel                      | Aktualisiere den CNAME auf das korrekte smoxy-Ziel                    |
| **DNS Duplicate** | Ein TXT-Eintrag existiert für `_acme-challenge` anstelle des erforderlichen CNAME | Entferne den TXT-Eintrag und erstelle stattdessen einen CNAME-Eintrag |

{% hint style="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).
{% endhint %}

***

### 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                  | Füge den/die fehlenden CNAME-Eintrag/Einträge hinzu                  |
| **TXT record exists** | Ein TXT-Eintrag für `_acme-challenge` kollidiert mit dem CNAME | Entferne den TXT-Eintrag, behalte nur den CNAME                      |
| **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                 | Überprüfe die DNS-Propagierung; smoxy versucht es automatisch erneut |
| **Cloudflare error**  | Cloudflare-Proxy stört die DNS-Verifizierung                   | Deaktiviere den Cloudflare-Proxy für den `_acme-challenge` Eintrag   |

***

### Selbst verwaltetes Zertifikat hochladen

Um ein eigenes SSL-Zertifikat hochzuladen:

1. Navigiere zu **Domains & DNS** und wähle deine Domain aus
2. Gehe zum **SSL**-Tab
3. Klicke auf **Eigenes SSL-Zertifikat hochladen**
4. Stelle bereit:
   * **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 deine Domain ab

Wenn sich die SANs im neuen Zertifikat von den aktuellen unterscheiden, zeigt smoxy dir 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, **musst du vor Ablauf ein Ersatzzertifikat hochladen**

***

### Wildcard-Zertifikate

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

* `www.deinedomain.com`
* `shop.deinedomain.com`
* `api.deinedomain.com`
* Jede andere einstufige Subdomain

**Was Wildcards NICHT abdecken:**

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

Wenn du einen Hostnamen wie `shop.deinedomain.com` zu einer Site hinzufügst, prüft smoxy, ob das vorhandene Wildcard-Zertifikat ihn bereits abdeckt. Falls ja, ist keine zusätzliche Zertifikatsarbeit erforderlich.

***

### Zertifikate herunterladen

Du kannst dein SSL-Zertifikat und den Private Key zur Verwendung in externen Tools herunterladen:

1. Navigiere zu **Domains & DNS** und wähle deine Domain aus
2. Gehe zum **SSL**-Tab
3. Klicke auf den **Download**-Button für das Zertifikat oder den Schlüssel

**Erforderliche Rolle:** Owner oder Maintainer

***

### Subdomain-Wiederverwendung

Wenn du die Hauptdomain (z. B. `deinedomain.com`) erstellst und ein Wildcard-Zertifikat generiert wird, können alle Subdomains dieses Zertifikat wiederverwenden. 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

**Empfehlung:** Erstelle immer zuerst deine Hauptdomain und füge dann die Subdomains hinzu. So stellst du sicher, dass das Wildcard-Zertifikat vorhanden ist und Subdomains ohne zusätzliche SSL-Schritte konfiguriert werden können.

***

### Fehlerbehebung

#### Zertifikat bleibt im Status "Pending"

* Überprüfe, ob alle erforderlichen `_acme-challenge` CNAME-Einträge bei deinem DNS-Anbieter gesetzt sind
* Die DNS-Propagierung kann bis zu 48 Stunden dauern (normalerweise aber deutlich schneller)
* Wenn du Cloudflare verwendest, stelle sicher, dass der Proxy für Challenge-Einträge deaktiviert ist

#### Status "DNS Missing"

Der `_acme-challenge` CNAME-Eintrag wurde nicht gefunden. Überprüfe:

* Der Eintrag existiert bei deinem 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. Aktualisiere den Eintrag auf das in smoxy angezeigte Ziel.

#### Status "DNS Duplicate"

Ein TXT-Eintrag für `_acme-challenge` existiert neben oder anstelle des erforderlichen CNAME. Entferne den TXT-Eintrag und stelle sicher, dass nur der CNAME-Eintrag existiert.

#### Zertifikat erneuert sich nicht

* Automatisch verwaltete Zertifikate erneuern sich automatisch 30 Tage vor Ablauf
* Stelle sicher, dass die `_acme-challenge` CNAME-Einträge noch vorhanden sind
* Selbst verwaltete Zertifikate werden **niemals** automatisch erneuert — du musst ein Ersatzzertifikat hochladen

#### SAN-Änderungen werden nicht übernommen

Nach dem Hinzufügen neuer SANs muss smoxy das Zertifikat neu generieren. Dies geschieht automatisch, sobald die DNS-Verifizierung für den neuen SAN bestanden ist. Überprüfe den DNS-Status des SANs im SSL-Tab.