Zum Hauptinhalt springen

TLS-Konfiguration

Diese Seite dokumentiert die Endpunkte zur Abfrage und Konfiguration des TLS-Zertifikats der IDIAL REST API. TLS sichert die Kommunikation zwischen Clients und der API ab. Die hier beschriebenen Endpunkte ermöglichen es, den aktuellen TLS-Status zu prüfen und ein neues Zertifikat hochzuladen.

GET /tls​

Gibt die aktuelle TLS-Konfiguration der IDIAL REST API zurück. Die Antwort enthält den Zertifikatsstatus, Dateipfade, das aktive Serverzertifikat im PEM-Format, dessen SHA1-Fingerabdruck sowie unterstützte TLS-Protokolle und Cipher-Suites. Dieser Endpunkt wird verwendet, um vor dem Produktiveinsatz von IDIAL die korrekte TLS-Konfiguration zu verifizieren.

Authentifizierung: Nicht erforderlich

Anfrage​

curl -X GET http://localhost:5000/tls

Antwort 200​

{
  "enabled": true,
  "cert_file": "/app/certs/server.crt",
  "key_file": "/app/certs/server.key",
  "tls_server_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "fingerprint": "A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78",
  "protocols": ["TLSv1_2", "TLSv1_3"],
  "ciphers": ["ECDHE-RSA-AES256-GCM-SHA384", "TLS_AES_256_GCM_SHA384"],
  "message": "TLS active"
}

Antwortfelder​

FeldTypBeschreibung
enabledbooleanTLS-Verfügbarkeitsstatus. true: Sowohl Zertifikat- als auch private Schlüsseldatei existieren und sind lesbar. false: Mindestens eine der Dateien fehlt oder ist nicht lesbar. Zweck: Schnelle TLS-Statusprüfung für Anwendungen und Monitoring.
cert_filestringAbsoluter Dateisystempfad zur TLS-Zertifikatsdatei im Container.
key_filestringAbsoluter Dateisystempfad zur privaten TLS-Schlüsseldatei im Container.
tls_server_certificatestringVollständiger PEM-kodierter Zertifikatsinhalt des von IDIAL verwendeten TLS-Zertifikats. Inhalt: Vollständiges Zertifikat einschließlich der Header -----BEGIN CERTIFICATE----- und -----END CERTIFICATE-----. Leerer String "", wenn die Zertifikatsdatei nicht verfügbar ist. Zweck: Zertifikatsvalidierung und -analyse ohne Dateisystemzugriff.
fingerprintstringSHA1-Fingerabdruck des TLS-Zertifikats im Hexadezimalformat. Format: Durch Doppelpunkte getrennte Hex-Paare (z. B. "A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78"). Leerer String "", wenn kein Zertifikat verfügbar. Zweck: Zertifikatsidentifikation und -verifikation.
protocolsstring[]Liste der unterstützten TLS-Protokollversionen, die im System verfügbar sind. Beispiele: ["TLSv1_2", "TLSv1_3"]. Zweck: Protokollkompatibilitätsprüfung für Client-Verbindungen.
ciphersstring[]Liste der verfügbaren Cipher-Suites, die vom TLS-Kontext unterstützt werden. Alphabetisch sortiert. Beispiele: ["TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", "ECDHE-RSA-AES256-GCM-SHA384"]. Zweck: Sicherheitskonfiguration und Cipher-Suite-Auswahl.
messagestringMenschenlesbare Statusbeschreibung. "TLS active" wenn beide Dateien verfügbar sind. "TLS inactive (certificate and key required)" wenn Dateien fehlen. Kann spezifische Statusinformationen aus TLS-Operationen enthalten.

POST /tls​

Lädt einen PKCS#12-Container hoch, um TLS für die IDIAL REST API zu konfigurieren. IDIAL extrahiert das Zertifikat und den privaten Schlüssel, validiert sie und schreibt sie in das Dateisystem. TLS wird unmittelbar nach einem erfolgreichen Upload aktiviert. Der IDIAL-Dienst muss neu gestartet werden, damit der TLS-Kontext vollständig angewendet wird.

Authentifizierung: Erforderlich (X-API-Key-Header)

Anfrage-Body​

{
  "tls_server_pkcs12_base64": "MIIKxgIBAzCCCoIGCSqGSIb3...",
  "tls_server_pkcs12_password": "your-pkcs12-password"
}

Anfrage-Felder​

FeldTypPflichtfeldBeschreibung
tls_server_pkcs12_base64stringJaBase64-kodierter PKCS#12-Container mit TLS-Zertifikat und privatem Schlüssel. Format: Standard-Base64-Kodierung ohne Leerzeichen oder Zeilenumbrüche. Muss sowohl das X.509-Zertifikat als auch den zugehörigen privaten Schlüssel enthalten. Kein explizites Größenlimit, allerdings gelten praktische Grenzen aufgrund von Systemressourcen. Die Base64-Dekodierung wird vor der PKCS#12-Verarbeitung validiert.
tls_server_pkcs12_passwordstringJaPasswort zur Entschlüsselung des PKCS#12-Containers. Wird ausschließlich während der Verarbeitung verwendet und nicht dauerhaft gespeichert. Ein leerer String wird abgelehnt. UTF-8-String-Kodierung wird unterstützt.

Antwort 200​

Die Antwort entspricht dem Format von GET /tls.

Antwort 400​

{"error": "string"}

Validierung fehlgeschlagen: fehlende Felder, ungültiges Base64-Format oder falsches Passwort.

warnung

Nach dem Hochladen eines neuen TLS-Zertifikats über diesen Endpunkt sollte der IDIAL-Dienst neu gestartet werden, um sicherzustellen, dass der neue TLS-Kontext vollständig geladen wird. Das Feld enabled in der Antwort bestätigt, dass die Dateien erfolgreich geschrieben wurden.

tipp

So erstellen Sie einen PKCS#12-Container aus einem vorhandenen PEM-Zertifikat und -Schlüssel:

openssl pkcs12 -export \
  -in server.crt \
  -inkey server.key \
  -out server.p12 \
  -passout pass:your-password

# Convert to base64 for the API request:
base64 -w 0 server.p12

Beispiele​

# GET /tls - TLS-Status prüfen
curl -X GET http://localhost:5000/tls

# POST /tls - Zertifikat hochladen
curl -X POST http://localhost:5000/tls \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tls_server_pkcs12_base64": "MIIKxgIBAzCC...",
    "tls_server_pkcs12_password": "your-pkcs12-password"
  }'