GDS Push — Zertifikatsausrollung

GDS Push ist der primäre Mechanismus zur Zertifikatsausrollung auf von IDIAL verwalteten OPC UA Geräten. IDIAL verbindet sich mit der OPC UA Global Discovery Server (GDS) Schnittstelle des Zielgeräts, stellt über den konfigurierten PKI-Endpoint ein Zertifikat aus und überträgt es in den Zertifikatsspeicher des Geräts. Die Trust List (CA-Kette und CRL) wird gleichzeitig auf dem Gerät eingerichtet.

Vor der ersten Ausrollung verifiziert IDIAL die Verbindung zum Gerät und speichert die Zugangsdaten für nachfolgende automatisierte Operationen.

POST /gds/push

Stellt ein Zertifikat aus und überträgt es auf einen GDS-fähigen OPC UA Endpoint. Falls das Gerät noch nicht im Inventar eingetragen ist, wird es automatisch registriert. Übermittelte Zugangsdaten werden für zukünftige automatisierte Erneuerungen gespeichert.

Authentifizierung: X-API-Key erforderlich

Anfrage

curl -X POST http://localhost:5000/gds/push \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840,
    "name": "PLC Linie 1",
    "subject": "CN=plc-line1,O=ExampleCorp,C=DE",
    "username": "admin",
    "password": "secret",
    "issuer": true,
    "trusted": false,
    "security_policy": 8,
    "security_mode": 2,
    "debug": false
  }'

Anfragefelder

Feld	Typ	Pflicht	Standard	Beschreibung
`server`	string	Ja	—	IP-Adresse oder FQDN des Zielgeräts. Eindeutiger Bezeichner des Endpoints in IDIAL.
`port`	integer	Nein	`4840`	OPC UA Port.
`name`	string	Nein	—	Anzeigename des Endpoints. Hat keinen Einfluss auf den Zertifikatsinhalt.
`subject`	string	Nein	—	Gewünschter Subject DN für das Zielzertifikat. Wird er weggelassen, wertet IDIAL verfügbare Standardwerte für den Zertifikatssubjekt aus.
`username`	string	Nein	—	Benutzername, den IDIAL für die Verbindung zum GDS-Endpoint verwendet. Aktualisiert den gespeicherten Benutzernamen für zukünftige Operationen.
`password`	string	Nein	—	Passwort für die GDS-Verbindung. Wird verschlüsselt für zukünftige automatisierte Operationen gespeichert.
`issuer`	boolean	Nein	`false`	Bei `true` wird das Aussteller-CA-Zertifikat des IDIAL OPC UA Client-Zertifikats zum Gerätevertrauensspeicher hinzugefügt.
`trusted`	boolean	Nein	`false`	Bei `true` wird das IDIAL OPC UA Client-Zertifikat selbst zum Gerätevertrauensspeicher hinzugefügt.
`security_policy`	integer	Nein	`31`	Security-Policy-Bitmaske. Siehe Parameter-Referenz.
`security_mode`	integer	Nein	`0`	Security Mode. Siehe Parameter-Referenz.
`debug`	boolean	Nein	`false`	Bei `true` werden zusätzliche Prozessinformationen in der Antwort ausgegeben.

tipp

Verwenden Sie issuer: true (anstatt oder zusätzlich zu trusted: true), damit das Gerät die IDIAL-Verbindung auch nach einer Erneuerung des Client-Zertifikats weiterhin akzeptiert. Dies verhindert unbeabsichtigte Verbindungssperren.

Antwort 200

{
  "success": true,
  "execution": "GDS Push completed successfully",
  "error": "",
  "result": {}
}

Antwortfelder

Feld	Typ	Beschreibung
`success`	boolean	Gibt an, ob die Operation erfolgreich war.
`execution`	string	Ausführungsstatusmeldung.
`error`	string	Fehlermeldung, falls die Operation fehlgeschlagen ist.
`result`	object \| null	Zusätzliche Ergebnisdaten.

Antwort 422

Wird zurückgegeben, wenn die Validierung der Zertifikatsanfrage fehlgeschlagen ist — das Zertifikat konnte nicht ausgestellt werden.

Antwort 500

{"error": "string"}

GET /gds/push/{host_or_url}

Gibt den GDS-Push-Status für einen bestimmten Inventareintrag zurück.

Authentifizierung: X-API-Key erforderlich

Anfrage

curl -X GET http://localhost:5000/gds/push/192.168.1.10 \
  -H "X-API-Key: your-api-key"

Antwort 200

Format entspricht POST /gds/push.

Antwort 404

{"error": "string"}

POST /gds/push/onboarding

Führt den GDS-Push-Onboarding-Workflow für einen neuen Endpoint durch. Dabei wird die initiale Vertrauensbeziehung aufgebaut und die Zugangsdaten des Geräts im Inventar registriert.

Authentifizierung: X-API-Key erforderlich

Anfrage

curl -X POST http://localhost:5000/gds/push/onboarding \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840,
    "username": "admin",
    "password": "secret"
  }'

Anfragefelder

Identisch mit POST /gds/push.

Antwort 200

Format entspricht POST /gds/push.

GET /gds/push/onboarding/{host_or_url}

Gibt den Onboarding-Status für einen bestimmten GDS-Inventareintrag zurück.

Authentifizierung: X-API-Key erforderlich

Anfrage

curl -X GET http://localhost:5000/gds/push/onboarding/192.168.1.10 \
  -H "X-API-Key: your-api-key"

Antwort 200

Format entspricht POST /gds/push.

Antwort 404

{"error": "string"}

POST /gds/push/change

Löst eine Zertifikatswechseloperation für einen oder mehrere GDS-Inventareinträge aus. Wird verwendet, um eine Zertifikatserneuerung außerhalb des normalen Scheduler-Zyklus zu erzwingen.

Authentifizierung: X-API-Key erforderlich

Anfrage

curl -X POST http://localhost:5000/gds/push/change \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840
  }'

Anfragefelder

Feld	Typ	Pflicht	Beschreibung
`server`	string	Ja	Hostname oder IP des Ziel-Endpoints.
`port`	integer (1–65535)	Nein	Port (Standard: `4840`).

Antwort 200

Format entspricht POST /gds/push.

POST /gds/firmware (veraltet)

Liest die Firmware-Version von einem GDS-Endpoint aus. Verwenden Sie stattdessen GET /gds/monitor/firmware/{host_or_url}.

Authentifizierung: X-API-Key erforderlich

Anfrage

curl -X POST http://localhost:5000/gds/firmware \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"server": "192.168.1.10", "port": 4840}'

Anfragefelder

Feld	Typ	Pflicht	Beschreibung
`server`	string	Ja	Hostname oder IP des Zielgeräts.
`port`	integer	Nein	OPC UA Port (Standard: `4840`).
`username`	string	Nein	Authentifizierungsbenutzername.
`password`	string	Nein	Authentifizierungspasswort.
`security_policy`	integer	Nein	Security-Policy-Bitmaske.
`security_mode`	integer	Nein	Security-Mode-Bitmaske.
`allow_insecure_connection`	boolean	Nein	Verbindung ohne Sicherheit erlauben.

Antwort 200

{
  "url": "opc.tcp://192.168.1.10:4840",
  "firmware_version": "V03.01.03",
  "device_name": "SIMATIC S7-1500 OPC UA"
}

GET /gds/crt

Gibt das IDIAL OPC UA Client-Zertifikat zurück (das Zertifikat, das IDIAL bei der Verbindung zu GDS-Endpoints verwendet).

Authentifizierung: X-API-Key erforderlich

Anfrage

curl -X GET http://localhost:5000/gds/crt \
  -H "X-API-Key: your-api-key"

Antwort 200

Binäre Zertifikatsdatei (PEM- oder DER-Format). Fügen Sie ?format=pem oder ?format=der an die URL an, um das Format festzulegen.

Antwort 404

{"error": "OPCUA client certificate not found"}

POST /gds/push​

Anfrage​

Anfragefelder​

Antwort 200​

Antwortfelder​

Antwort 422​

Antwort 500​

GET /gds/push/{host_or_url}​

Anfrage​

Antwort 200​

Antwort 404​

POST /gds/push/onboarding​

Anfrage​

Anfragefelder​

Antwort 200​

GET /gds/push/onboarding/{host_or_url}​

Anfrage​

Antwort 200​

Antwort 404​

POST /gds/push/change​

Anfrage​

Anfragefelder​

Antwort 200​

POST /gds/firmware (veraltet)​

Anfrage​

Anfragefelder​

Antwort 200​

GET /gds/crt​

Anfrage​

Antwort 200​

Antwort 404​

POST /gds/push

Anfrage

Anfragefelder

Antwort 200

Antwortfelder

Antwort 422

Antwort 500

GET /gds/push/{host_or_url}

Anfrage

Antwort 200

Antwort 404

POST /gds/push/onboarding

Anfrage

Anfragefelder

Antwort 200

GET /gds/push/onboarding/{host_or_url}

Anfrage

Antwort 200

Antwort 404

POST /gds/push/change

Anfrage

Anfragefelder

Antwort 200

POST /gds/firmware (veraltet)

Anfrage

Anfragefelder

Antwort 200

GET /gds/crt

Anfrage

Antwort 200

Antwort 404