GDS Push — Zertifikatsausrollung

GDS Push ist der primäre Mechanismus zur Zertifikatsausrollung für OPC UA Geräte, die von IDIAL verwaltet werden. IDIAL verbindet sich mit der OPC UA Global Discovery Server (GDS) Schnittstelle des Zielgeräts, stellt über den konfigurierten PKI-Endpunkt ein Zertifikat aus und überträgt es in den Zertifikatsspeicher des Geräts. Gleichzeitig wird die Trust List (CA-Kette und CRL) auf dem Gerät bereitgestellt.

Vor der ersten Ausrollung prüft IDIAL die Verbindung zum Gerät und speichert die Zugangsdaten für nachfolgende automatisierte Vorgänge.

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 vorhanden ist, wird es automatisch registriert. Die übermittelten Zugangsdaten werden für zukünftige automatisierte Erneuerungen gespeichert.

Authentifizierung: X-API-Key erforderlich

Request Body

{
  "server": "192.168.1.10",
  "port": 4840,
  "name": "PLC Line 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
}

Feld	Typ	Pflicht	Standard	Beschreibung
`server`	string	Ja	—	IP-Adresse oder FQDN des Zielgeräts. Der `server`-Wert ist der eindeutige Bezeichner des Endpoints innerhalb der IDIAL-Datenbank — es darf nicht mehrere Endpoints mit demselben `server`-Bezeichner geben.
`port`	integer	Nein	`4840`	OPC UA Port
`name`	string	Nein	—	Name des Endpoints, der frei vom OT-Personal gewählt werden kann. Hilft dabei, die Zielkomponente eindeutig zu identifizieren, da IP-Adressen in großen OT-Umgebungen nicht immer eindeutig sind. Der Name hat keinen Einfluss auf den Zertifikatsinhalt und dient ausschließlich der Lesbarkeit und dem Reporting.
`subject`	string	Nein	—	Gewünschter Subject DN für das Zielzertifikat. Wird kein Wert angegeben, bewertet IDIAL die Optionen zur Festlegung von Standardinformationen im Subject DN bei der Zertifikatsausstellung. Hinweis: Die PKI kann spezifische Anforderungen an das Subject-DN-Format und den Inhalt stellen. In der Praxis werden Teile des DN (z. B. OU, O, C) oft durch die Ausstellende CA über das Zertifikatstemplate vorgegeben.
`username`	string	Nein	—	Benutzername, den IDIAL zur Verbindung mit dem GDS-Endpunkt verwendet. Optional — wenn der Benutzer bereits in IDIAL definiert ist, kann dieses Feld entfallen. Wenn gesetzt, aktualisiert IDIAL den Benutzernamen in der Konfiguration und verwendet ihn für alle nachfolgenden Anfragen.
`password`	string	Nein	—	Passwort des Benutzers, den IDIAL zur Verbindung mit dem GDS-Endpunkt verwendet. Optional — wenn der Benutzer bereits definiert ist, kann dieses Feld entfallen. Wenn gesetzt, aktualisiert IDIAL das Passwort und verwendet es für alle nachfolgenden Anfragen. Wird vor der Speicherung verschlüsselt.
`issuer`	boolean	Nein	`false`	Standard: `false`. Bei `true`: Das Aussteller-CA-Zertifikat des von IDIAL verwendeten OPC UA Client-Zertifikats wird dem Truststore des Geräts hinzugefügt und als vertrauenswürdig markiert. Empfohlene Vorgehensweise: Die Erneuerung des Client-Zertifikats hat keinen Einfluss auf die Vertrauensstellung, solange es vom selben Aussteller ausgestellt wurde.
`trusted`	boolean	Nein	`false`	Standard: `false`. Bei `true`: Das von IDIAL verwendete OPC UA Client-Zertifikat wird explizit dem Truststore des Geräts hinzugefügt. Es wird empfohlen, zusätzlich `issuer: true` zu setzen, um sicherzustellen, dass der Aussteller vertrauenswürdig ist. Andernfalls kann der Client vom Zugriff auf den Endpunkt ausgesperrt werden, wenn sich das Client-Zertifikat ändert und nicht erneut explizit als vertrauenswürdig eingestuft wurde.
`security_policy`	integer	Nein	`31`	Siehe Parameter-Referenz
`security_mode`	integer	Nein	`0`	Siehe Parameter-Referenz
`debug`	boolean	Nein	`false`	Standard: `false`. Bei `true`: Zusätzliche Prozessinformationen werden der Antwort hinzugefügt.

tipp

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

Response 200

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

Responses

Code	Beschreibung
`200`	Zertifikat erfolgreich ausgerollt
`422`	Validierungsfehler — Zertifikat konnte nicht bereitgestellt werden
`500`	`{"error": "string"}`

GET /gds/push/{host_or_url}

Löst GDS Push für einen vorhandenen Inventareintrag aus. Verwendet die gespeicherten Zugangsdaten und die PKI-Konfiguration aus dem Inventar. Kein Request Body erforderlich.

Authentifizierung: X-API-Key erforderlich

Pfadparameter

Parameter	Beschreibung
`host_or_url`	IP-Adresse, Hostname oder OPC UA URL eines Inventareintrags

Response 200

Identisch mit POST /gds/push.

POST /gds/push/change

Ändert oder erneuert das Zertifikat auf einem vorhandenen GDS-Endpoint. Erweitert die Parameter von POST /gds/push um die Auswahl des Algorithmus für die Schlüsselpaar-Generierung.

Authentifizierung: X-API-Key erforderlich

Request Body

Identisch mit POST /gds/push, ergänzt um folgende Felder:

{
  "self_signed": true,
  "algorithm": 2048
}

Feld	Typ	Standard	Beschreibung
`self_signed`	boolean	`true`	Gibt an, ob das neue Zertifikat selbstsigniert sein soll
`algorithm`	integer	`2048`	RSA-Schlüssellänge in Bit. Zulässige Werte: `1024`, `2048`, `3072`, `4096`

POST /gds/firmware

Liest Firmware-Informationen direkt von einem GDS-fähigen OPC UA Gerät aus. Gibt Produktname, Hersteller, Softwareversion und Gerätetyp zurück.

Authentifizierung: X-API-Key erforderlich

Request Body

{
  "server": "192.168.1.10",
  "port": 4840,
  "username": "admin",
  "password": "secret",
  "security_policy": 0,
  "security_mode": 0,
  "allow_insecure_connection": false
}

Feld	Typ	Pflicht	Standard	Beschreibung
`server`	string	Ja	—	IP-Adresse oder FQDN
`port`	integer	Nein	`4840`	OPC UA Port
`username`	string	Nein	—	Benutzername (wird aus dem Inventar übernommen, wenn nicht angegeben)
`password`	string	Nein	—	Passwort (wird aus dem Inventar übernommen, wenn nicht angegeben)
`security_policy`	integer	Nein	`0`	Security Policy Bitmaske
`security_mode`	integer	Nein	`0`	Security Mode
`allow_insecure_connection`	boolean	Nein	`false`	Verbindung ohne Zertifikatsvertrauensprüfung zulassen

Response 200

{
  "url": "opc.tcp://192.168.1.10:4840",
  "gds_time": "2026-03-30T10:00:00",
  "product_name": "SIMATIC S7-1500",
  "product_uri": "urn:siemens.com:S7-1500",
  "manufacturer_name": "Siemens AG",
  "software_version": "V2.9.2",
  "known_device": true,
  "generic_device": false,
  "device_name": "S7-1500",
  "firmware_version": "V2.9.2"
}

GET /gds/firmware/{host_or_url}

Entspricht POST /gds/firmware, verwendet jedoch die Zugangsdaten eines vorhandenen Inventareintrags.

Authentifizierung: X-API-Key erforderlich

Pfadparameter

Parameter	Beschreibung
`host_or_url`	IP-Adresse, Hostname oder OPC UA URL eines Inventareintrags

GET /gds/status/{host_or_url}

Liest den GDS-Status eines Geräts aus: GDS-Zustand, aktuelle Gerätezeit sowie Informationen darüber, ob der Provisionierungsmodus aktiv oder aktiviert ist.

Authentifizierung: X-API-Key erforderlich

Pfadparameter

Parameter	Beschreibung
`host_or_url`	IP-Adresse, Hostname oder OPC UA URL eines Inventareintrags

Response 200

{
  "gds_state": "Operational",
  "gds_time": "2026-03-30T10:00:00",
  "provisioning_mode_active": false,
  "provisioning_mode_enabled": true,
  "url": "opc.tcp://192.168.1.10:4840"
}

GET /gds/crt

Lädt das OPC UA Client-Zertifikat herunter, das IDIAL beim Verbindungsaufbau zu OPC UA GDS-Geräten verwendet. Das Zertifikat wird im PEM- oder DER-Format zurückgegeben. Es muss von den verwalteten OPC UA Endpoints als vertrauenswürdig eingestuft sein, damit IDIAL eine Verbindung aufbauen kann.

Authentifizierung: X-API-Key erforderlich

Response 200: Binäre Zertifikatsdatei (PEM oder DER).

Beispiele

# Erstmalige Zertifikatsausrollung (GDS Push)
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 Line 1",
    "username": "admin",
    "password": "secret",
    "issuer": true,
    "security_policy": 8,
    "security_mode": 2
  }'

# GDS Push über Inventareintrag ausführen
curl -X GET "http://localhost:5000/gds/push/192.168.1.10" \
  -H "X-API-Key: your-api-key"

# Firmware-Informationen auslesen
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}'

# IDIALs eigenes OPC UA Client-Zertifikat herunterladen
curl -X GET http://localhost:5000/gds/crt \
  -H "X-API-Key: your-api-key" \
  -o idial-client.pem

POST /gds/push​

Request Body​

Response 200​

Responses​

GET /gds/push/{host_or_url}​

Pfadparameter​

Response 200​

POST /gds/push/change​

Request Body​

POST /gds/firmware​

Request Body​

Response 200​

GET /gds/firmware/{host_or_url}​

Pfadparameter​

GET /gds/status/{host_or_url}​

Pfadparameter​

Response 200​

GET /gds/crt​

Beispiele​

POST /gds/push

Request Body

Response 200

Responses

GET /gds/push/{host_or_url}

Pfadparameter

Response 200

POST /gds/push/change

Request Body

POST /gds/firmware

Request Body

Response 200

GET /gds/firmware/{host_or_url}

Pfadparameter

GET /gds/status/{host_or_url}

Pfadparameter

Response 200

GET /gds/crt

Beispiele