TLS für die IDIAL REST API konfigurieren

Standardmäßig läuft die IDIAL REST API ohne TLS. Für den produktiven Einsatz sollte HTTPS aktiviert werden, damit API-Keys und Nutzdaten verschlüsselt übertragen werden. Diese Anleitung beschreibt zwei Wege: das Hochladen eines Zertifikats per API und die Konfiguration über Umgebungsvariablen im Docker Compose.

warnung

Nach dem Hochladen eines neuen TLS-Zertifikats über die API muss der IDIAL-Container neugestartet werden, damit der neue TLS-Kontext vollständig aktiv wird.

Voraussetzungen

• Ein TLS-Zertifikat liegt vor (als PKCS#12-Datei oder als separates PEM-Zertifikat + Schlüssel)
• API-Key liegt vor (für den Upload-Weg)
• Zugriff auf die Docker-Compose-Konfiguration (für den Umgebungsvariablen-Weg)

Weg A — TLS-Zertifikat per API hochladen

Schritt 1 — Aktuellen TLS-Status prüfen

curl -s https://<idial-host>:5000/tls

hinweis

GET /tls erfordert keine Authentifizierung.

Beispielantwort bei inaktivem TLS:

{
  "enabled": false,
  "cert_file": "/app/tls/tls_server_cert.pem",
  "key_file": "/app/tls/tls_server_key.pem",
  "tls_server_certificate": null,
  "fingerprint": null,
  "protocols": [],
  "ciphers": [],
  "message": "TLS inactive — certificate or key file not found"
}

Schritt 2 — PKCS#12-Datei als Base64 kodieren

base64 -w 0 mein-zertifikat.p12 > cert_b64.txt

Schritt 3 — Zertifikat hochladen

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d "{
    \"tls_server_pkcs12_base64\": \"$(cat cert_b64.txt)\",
    \"tls_server_pkcs12_password\": \"<pkcs12-passwort>\"
  }" \
  https://<idial-host>:5000/tls

Parameter	Typ	Pflicht	Beschreibung
tls_server_pkcs12_base64	string	ja	Base64-kodierter Inhalt der PKCS#12-Datei (.p12 / .pfx)
tls_server_pkcs12_password	string	ja	Passwort zum Entschlüsseln der PKCS#12-Datei

Schritt 4 — Container neu starten

docker compose restart idial

Schritt 5 — TLS-Status bestätigen

curl -s https://<idial-host>:5000/tls

Erwartete Antwort bei aktivem TLS:

{
  "enabled": true,
  "cert_file": "/app/tls/tls_server_cert.pem",
  "key_file": "/app/tls/tls_server_key.pem",
  "tls_server_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "fingerprint": "A1:B2:C3:D4:E5:F6:07:08:09:10:11:12:13:14:15:16:17:18:19:20",
  "protocols": ["TLSv1_2", "TLSv1_3"],
  "ciphers": ["TLS_AES_256_GCM_SHA384", "..."],
  "message": "TLS active"
}

Antwortfelder

Feld	Beschreibung
enabled	true wenn Zertifikat- und Schlüsseldatei vorhanden und lesbar
cert_file	Absoluter Pfad zur Zertifikatsdatei im Container
key_file	Absoluter Pfad zur Schlüsseldatei im Container
tls_server_certificate	Vollständiges PEM-Zertifikat
fingerprint	SHA-1-Fingerabdruck, doppelpunktgetrennt
protocols	Unterstützte TLS-Versionen
ciphers	Unterstützte Cipher Suites
message	Statusbeschreibung

Weg B — TLS über Umgebungsvariablen konfigurieren

Alternativ können Zertifikat und Schlüssel über Docker Volumes bereitgestellt werden.

Umgebungsvariablen

Variable	Standard im Container	Beschreibung
IDIAL_TLS_CERT_FILE	/app/tls/tls_server_cert.pem	Pfad zur TLS-Zertifikatsdatei (PEM)
IDIAL_TLS_KEY_FILE	/app/tls/tls_server_key.pem	Pfad zur privaten Schlüsseldatei (PEM)

Docker-Compose-Beispiel

services:
  idial:
    image: idial:latest
    volumes:
      - rest_tls:/app/tls:rw
    environment:
      - IDIAL_TLS_CERT_FILE=/app/tls/tls_server_cert.pem
      - IDIAL_TLS_KEY_FILE=/app/tls/tls_server_key.pem
    ports:
      - "${IDIAL_REST_PORT:-5000}:5000"

volumes:
  rest_tls:

Lege die PEM-Dateien vor dem Start in das Volume:

docker run --rm \
  -v rest_tls:/target \
  -v /pfad/zu/certs:/certs:ro \
  alpine sh -c "cp /certs/tls_server_cert.pem /target/ && cp /certs/tls_server_key.pem /target/"

tipp

Weg B eignet sich besonders für automatisierte Deployments, bei denen Zertifikate über ein Secrets-Management-System (z.B. Vault, Kubernetes Secrets) bereitgestellt werden.

Zusammenfassung

GET /tls            → TLS-Status prüfen (keine Authentifizierung)
POST /tls           → PKCS#12-Zertifikat hochladen (API-Key erforderlich)
Docker restart      → Neuen TLS-Kontext aktivieren
Umgebungsvariablen  → Alternativ Pfade zu PEM-Dateien konfigurieren

Nächste Schritte

• GET /tls und POST /tls — API-Referenz
• GDS-Push-Gerät registrieren

Fehlerbehebung

Symptom	Mögliche Ursache	Lösung
"enabled": false nach Neustart	Zertifikat- oder Schlüsseldatei nicht im Volume	Volume-Mount und Dateipfade prüfen
Upload schlägt fehl	Falsches PKCS#12-Passwort	Passwort prüfen, PKCS#12-Datei mit openssl pkcs12 -info testen
Browser zeigt Zertifikatswarnung	Selbstsigniertes Zertifikat	CA-Zertifikat im Browser/Client als vertrauenswürdig hinterlegen
HTTP statt HTTPS nach Neustart	TLS-Dateien nicht lesbar (Berechtigungen)	Dateirechte im Container prüfen: docker exec idial ls -la /app/tls/