Zertifikat manuell erneuern oder ändern

Bei einem Key Compromise, einem Konfigurationsfehler oder einem Ad-hoc-Bedarf kann ein Zertifikat unabhängig vom Scheduler sofort erneuert werden. IDIAL bietet zwei Endpunkte: POST /gds/push für eine einfache Erneuerung mit bestehenden Parametern und POST /gds/push/change für eine Neuausstellung mit geänderten Zertifikatsparametern.

warnung

Eine manuelle Erneuerung überschreibt das aktuelle Zertifikat auf dem Gerät sofort. Stelle sicher, dass das Gerät erreichbar ist und die Verbindungsparameter korrekt sind, bevor du fortfährst.

Voraussetzungen

• Das Gerät ist im Inventar eingetragen
• Ein PKI-Endpunkt ist dem Gerät zugewiesen (oder die Verbindungsparameter werden direkt übergeben)
• Das Gerät ist über Netzwerk erreichbar
• API-Key liegt vor

Schritt 1 — Einfache Erneuerung (POST /gds/push)

POST /gds/push stellt ein neues Zertifikat aus und überträgt es auf das Gerät. Die Zertifikatsparameter werden aus dem konfigurierten PKI-Endpunkt übernommen.

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.100",
    "port": 4840
  }' \
  https://<idial-host>:5000/gds/push

Anfrageparameter

Parameter	Typ	Standard	Beschreibung
server	string	—	IP-Adresse oder FQDN des OPC UA-Servers
port	integer	4840	OPC UA-Port (1–65535)
subject	string	—	Zertifikats-Subject (übersteuert PKI-Konfiguration)
username	string	—	Authentifizierungs-Benutzername (übersteuert Inventareintrag)
password	string	—	Authentifizierungs-Passwort (übersteuert Inventareintrag)
trusted	boolean	false	Zertifikat in die TRUSTED Trust List schreiben
issuer	boolean	false	Zertifikat in die ISSUER Trust List schreiben
security_policy	integer	0	Bitmask der erlaubten Security Policies (siehe Parameter-Referenz)
security_mode	integer	0	Bitmask der erlaubten Security Modes (siehe Parameter-Referenz)
allow_insecure_connection	boolean	false	Zertifikatsprüfung und CRL-Check überspringen

hinweis

username und password müssen entweder beide gesetzt oder beide leer sein. Sind sie nicht angegeben, verwendet IDIAL die im Inventareintrag hinterlegten Zugangsdaten.

Erfolgsantwort

{
  "success": true,
  "execution": "Certificate Update successfully executed\nGDS Push finished with success",
  "error": ""
}

Schritt 2 — Erneuerung mit geänderten Parametern (POST /gds/push/change)

POST /gds/push/change stellt ein neues Zertifikat mit abweichenden Parametern aus — z.B. ein anderer Schlüsselalgorithmus oder ein selbstsigniertes Zertifikat.

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.100",
    "port": 4840,
    "self_signed": false,
    "algorithm": 4096
  }' \
  https://<idial-host>:5000/gds/push/change

Zusätzliche Parameter (gegenüber POST /gds/push)

Parameter	Typ	Standard	Beschreibung
self_signed	boolean	true	Selbstsigniertes Zertifikat ausstellen
algorithm	integer	2048	RSA-Schlüssellänge in Bits: 1024, 2048, 3072 oder 4096

tipp

Nutze POST /gds/push/change mit "algorithm": 4096, wenn ein Gerät nach einem Key Compromise ein neues Schlüsselpaar benötigt. Der neue Schlüssel wird auf dem GDS-Server erzeugt und sofort auf das Gerät übertragen.

warnung

Ein Schlüsselwechsel ändert den Fingerabdruck des Gerätezertifikats. Systeme, die das alte Zertifikat explizit vertrauen (z.B. über pinned certificates), müssen aktualisiert werden.

Schritt 3 — Ergebnis prüfen

Nach der Erneuerung kann das aktuell installierte Zertifikat abgerufen werden:

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.100",
    "port": 4840,
    "fingerprint": "SHA1",
    "x509": true
  }' \
  https://<idial-host>:5000/gds/monitor/crt

Die Antwort enthält den Fingerabdruck und die vollständigen X.509-Details des neu ausgestellten Zertifikats.

Zusammenfassung

POST /gds/push         → Zertifikat mit bestehenden Parametern erneuern
POST /gds/push/change  → Zertifikat mit neuen Parametern ausstellen
POST /gds/monitor/crt  → Erneuerungsergebnis prüfen

Nächste Schritte

• POST /gds/push — API-Referenz

Fehlerbehebung

Symptom	Mögliche Ursache	Lösung
"success": false mit Verbindungsfehler	Gerät nicht erreichbar	IP/Port prüfen, Netzwerkverbindung testen
"success": false mit Authentifizierungsfehler	Zugangsdaten fehlen oder falsch	username/password direkt im Request übergeben
Erneuerung erfolgreich, altes Zertifikat noch aktiv	Gerät braucht Neustart	Gerät neu starten, um neues Zertifikat zu aktivieren
allow_insecure_connection erforderlich	CRL nicht erreichbar oder Zertifikat nicht in Trust List	CRL-Erreichbarkeit prüfen oder Trust List aktualisieren