HTTPS und Zertifikate in Velocity #

Diese Seite richtet sich an Administratoren, die eine Website mit Velocity über HTTPS ausliefern. Das HTTPS von Velocity kümmert sich um sich selbst. Ist kein Zertifikat konfiguriert, erzeugt der Server sein eigenes und liefert trotzdem HTTPS aus. Ist eine Quelle konfiguriert (Ihre eigenen Dateien, ein Archiv, ein PKCS#12-Bundle, Let's Encrypt oder eine andere ACME-CA), prüft er das Zertifikat, liefert es aus, überwacht es, erneuert es und tauscht das neue im laufenden Server aus, ohne Neustart und ohne eine Verbindung abzubrechen. Gilt für Exponential Velocity 0.0.4.27 und später.

Worauf Sie sich verlassen können #

• Es gibt keinen Moment, in dem der Server unverschlüsseltes HTTP beantwortet, aber kein HTTPS (HTTPS startet zuerst).
• Ein defektes oder abgelaufenes Zertifikat erreicht nie einen Besucher: Das Paar wird vor der Verwendung geprüft (lässt sich parsen, ist nicht abgelaufen, der Schlüssel gehört dazu), und ein selbstsigniertes Zertifikat springt ein, bis das echte wieder verwendbar ist.
• Die Erneuerung braucht nichts von Ihnen: Let's-Encrypt-Zertifikate werden in einem Hintergrundjob erneuert, nach einem Fehlschlag mit wachsenden Pausen (5 Minuten, verdoppelt bis zu einem Tag), sodass die Ratenbegrenzungen einer CA nie aufgebraucht werden.
• HTTP/2 ist inbegriffen (HTTP/2 und Sicherheit).

Schnellstart #

Alle Einstellungen liegen unter Q.web.https in der Site-Datei (zum Beispiel /etc/qbix/sites-enabled/example.com.conf oder /etc/vc/... für Velocity) oder im JSON von --config.

Let's Encrypt (Port 80 dieses Servers aus dem Internet erreichbar, DNS zeigt hierher):

{ "Q": { "web": { "https": {
  "port": 443,
  "mode": "letsencrypt",
  "acme": { "email": "your-contact-address", "domains": ["example.com", "www.example.com"] }
} } } }

Ihre eigenen Dateien:

{ "Q": { "web": { "https": {
  "port": 443,
  "mode": "files",
  "cert": "/etc/ssl/example.com/fullchain.pem",
  "key":  "/etc/ssl/example.com/privkey.pem"
} } } }

Entwicklung, ganz ohne Zertifikat:

{ "Q": { "web": { "https": { "port": 8443, "mode": "self-signed" } } } }

Starten Sie den Server. Die Konsole gibt eine Zeile wie tls: certificate ready (EC, openssl-ecdsa, 0.1s, 397 days, localhost ...) aus. Prüfen Sie jederzeit mit:

qbixconsole ssl:show

Probieren Sie immer zuerst das Staging-Verzeichnis von Let's Encrypt aus ("directory": "letsencrypt-staging"): Seine Zertifikate sind nicht vertrauenswürdig, aber seine Ratenbegrenzungen großzügig.

Einstellungen (unter Q.web.https) #

files: cert (Standard config/certs/fullchain.pem; Blattzertifikat allein oder mit Kette; PEM, DER oder PKCS#7), key (Standard config/certs/privkey.pem; darf dieselbe Datei sein), chain (optional), keyPassword / keyPasswordFile / keyPasswordEnv.

archive: archive (.zip, .tar, .tar.gz/.tgz, .tar.bz2, .tar.xz, .rar, .7z), password* für ein verschlüsseltes Archiv, keyPassword* für einen verschlüsselten Schlüssel.

pkcs12: bundle (.p12 / .pfx) und sein password, passwordFile, passwordEnv.

letsencrypt / ACME (Q.web.https.acme):

certbot und remote (eine URL, die alle checkInterval heruntergeladen wird, Standard 86400) stehen ebenfalls zur Verfügung; siehe docs/https.md der Engine.

Wie es sich verhält #

1. Eine Quelle liefert das Zertifikat; das Paar wird geprüft; HTTPS liest nur eine private Kopie (<ssl dir>/active-<port>-<fingerprint>-<pid>.pem), die diesem Serverprozess gehört, sodass eine Datei, die anderswo neu geschrieben wird, keinen Handshake stören kann. Ein zweiter Server im selben Verzeichnis und auf demselben Port schreibt seine eigene Kopie (behoben in 0.0.4.28: Zuvor konnte ein zweiter Server dem ersten das HTTPS wegnehmen).
2. Alle watchInterval Sekunden werden die Dateien der Quelle geprüft; ein geändertes, gültiges Paar wird der nächsten Verbindung präsentiert. Ein Zertifikat, das vor seinem Schlüssel geschrieben wird, bekommt ein Intervall Zeit, um zur Ruhe zu kommen.
3. Selbstsigniert wird in dieser Reihenfolge versucht: PHP openssl mit ECDSA P-256; PHP openssl mit RSA 2048, signiert mit SHA-256; das System-Programm openssl; das Snakeoil-Paar des Systems. Es gilt 397 Tage, wird 30 Tage vor Ablauf und bei jeder Änderung der Namen erneuert und liegt in ssl/self-signed.*. (Release 0.0.4.27 signiert mit SHA-256, weil Systeme, die SHA-1 ablehnen, das frühere Zertifikat abgelehnt haben.)
4. Auswahl pro Domain (SNI): Das Zertifikat, das eine Domain abdeckt, wird pro Verbindung ausgewählt und im Reiter Domains des Panels angezeigt (Control Panel).

Was in ssl/ liegt #

ssl/
  self-signed.pem, self-signed.key      the self-signed pair
  active-443-<fp>-<pid>.pem/.key        the copy one server reads (do not edit)
  imported/                             pairs imported from DER, archives, bundles, remote
  acme/account-<ca>.pem                 one account key per CA: keep it
  acme/<first domain>/fullchain.pem, privkey.pem, state.json
  acme/challenges/<token>               pending HTTP-01 answers (short-lived)

Sichern Sie ssl/. Alles darin lässt sich neu erzeugen, außer den ACME-Kontoschlüsseln.

Betrieb #

• qbixconsole ssl:show (und --json): das ausgelieferte Zertifikat und jedes bekannte Zertifikat nach Ablaufdatum. Achten Sie auf daysLeft: Unter 14 bei einem CA-Zertifikat bedeutet, dass die Erneuerung seit zwei Wochen fehlschlägt; acme.lastError sagt, warum.
• Der Reiter SSL des Control Panels zeigt dasselbe, bearbeitet die unbedenklichen Einstellungen (Modus, ACME-E-Mail und -Verzeichnis, renewAt, Hostnamen), erneuert und lädt neu ohne Neustart.
• Lassen Sie NTP laufen: Zertifikate werden gegen die Systemuhr geprüft.

Fehlerbehebung #

Grenzen und Sicherheitshinweise #

• Für files, pkcs12, .zip/.tar*, selbstsigniert oder Let's Encrypt ist kein externes Programm nötig; die openssl-Extension von PHP genügt.
• Private Schlüssel werden mit 0600 atomar geschrieben und nie protokolliert. Externe Programme laufen mit einer Argumentliste, nie über eine Shell. Der ACME-Client prüft das Zertifikat der CA (schalten Sie verify nur für eine Test-CA ab).
• Wildcards brauchen dns-01 mit einem Hook-Programm.

Verwandte Seiten #

• Control Panel (Reiter SSL und Domains), Scheduler (Erneuerungsjobs), Webserver Velocity
• Spezifikationen: HTTP/2 und Sicherheit, Engine-Einstellungen (Wiederaufnahme von TLS-Sitzungen, --https-port)
• Aktualisierung: Hinweise zur Aktualisierung der Velocity-Engine, Velocity-Engines ([HTTPSSettings])
• Changelog: Engine Exponential Velocity
• Geschichte: 24. September (Zertifikatssubsystem), 25. bis 30. September (Reiter SSL, Zertifikate pro Domain)