Zertifikats-Monitoring
Die Monitoring-Endpunkte stellen eine Live-Verbindung zum Zielgerät her und lesen Zertifikatsinformationen, Trust Lists und Gerätemetadaten direkt aus. Im Unterschied zum Inventar, das zwischengespeicherte Daten zurückgibt, wird bei jedem Aufruf eine aktive OPC UA Verbindung aufgebaut.
Die Monitoring-Endpunkte bauen eine Live-Verbindung zum Zielgerät auf. Stellen Sie sicher, dass das Zielgerät vom IDIAL-Container aus erreichbar ist, bevor Sie diese Endpunkte aufrufen.
POST /gds/monitor/crt
Verbindet sich mit einem entfernten OPC UA Server und liest dessen aktuelles Anwendungszertifikat aus. Optional wird die vollständige X.509-Textdarstellung zurückgegeben und ein Fingerabdruck berechnet. Dieser Endpunkt eignet sich zur Echtzeit-Zertifikatsprüfung, ohne auf zwischengespeicherte Inventardaten angewiesen zu sein.
Authentifizierung: X-API-Key erforderlich
Request Body
{
"server": "192.168.1.10",
"port": 4840,
"x509": false,
"fingerprint": "sha1",
"connection_security": false,
"disable_crl_check": false
}
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
server | string | Ja | — | IP-Adresse oder DNS-FQDN des OPC UA Servers. Der server-Wert ist der eindeutige Bezeichner des Endpoints innerhalb der IDIAL-Datenbank — es darf nicht mehrere Endpoints mit demselben server-Bezeichner geben. |
port | string | Nein | "4840" | OPC UA Port. Wenn nicht angegeben, wird der Standard-Port "4840" verwendet. |
x509 | boolean | Nein | false | Menschenlesbare Zertifikatstextdarstellung in der Antwort einschließen. Bei true wird das Feld x509 mit vollständigen Zertifikatsdetails im Textformat hinzugefügt. |
fingerprint | string | Nein | — | Fingerabdruck des Gerätezertifikats berechnen. Unterstützter Wert: "SHA1" (Groß-/Kleinschreibung irrelevant). Wenn angegeben, wird das Feld fingerprint mit dem Hash des Zertifikats in der Antwort ergänzt. |
connection_security | boolean | Nein | false | Gesicherten Verbindungsmodus für die OPC UA Kommunikation aktivieren. Bei true werden Sicherheitsfunktionen für die OPC UA Verbindung aktiviert. |
disable_crl_check | boolean | Nein | false | CRL-Prüfung beim Verbindungsaufbau überspringen |
Response 200
{
"url": "opc.tcp://192.168.1.10:4840",
"fingerprint": "A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78",
"x509": "Certificate:\n Data:\n Version: 3 (0x2)\n Serial Number:\n 22:b4:e2:45:34:27:f6:d5:fc:39:94:99:0d:1f:e3:b1:49:02:de:44\n Signature Algorithm: sha256WithRSAEncryption\n Issuer: C=DE, ST=Bayern, L=Muenchen, O=ExampleOPC, OU=IT, CN=opcua-server.local\n Validity\n Not Before: Mar 5 08:59:03 2026 GMT\n Not After : Mar 5 08:59:03 2027 GMT\n Subject: C=DE, ST=Bayern, L=Muenchen, O=ExampleOPC, OU=IT, CN=opcua-server.local\n ...",
"security_policy": 8,
"security_mode": 2
}
| Feld | Typ | Beschreibung |
|---|---|---|
url | string | Vollständige OPC UA Verbindungs-URL (opc.tcp://server:port). Nur vorhanden, wenn das Gerät im Inventar eingetragen ist. Dient zur Verknüpfung der Zertifikatsinformationen mit bekannten Geräten. |
fingerprint | string | Hash des Zertifikats im Hexadezimalformat. Nur vorhanden, wenn im Request das Feld fingerprint mit einem unterstützten Hash-Algorithmus angegeben wurde. Beispiel: "A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78". |
x509 | string | Menschenlesbare Zertifikatsinformationen einschließlich Subject, Issuer und Gültigkeitsdaten. Nur vorhanden, wenn x509: true im Request gesetzt wurde. Enthält vollständige Zertifikatsdetails im Textformat. |
security_policy | integer | Ausgehandelte OPC UA Security Policy als Bitmask. Der Wert gibt an, welche Policy bei der Verbindung verwendet wurde. Mögliche Werte: 1 = Basic128Rsa15, 2 = Basic256, 4 = Aes128Sha256RsaOaep, 8 = Basic256Sha256, 16 = Aes256Sha256RsaPss. Vollständige Referenz: Parameter-Referenz. |
security_mode | integer | Ausgehandelter OPC UA Security Mode. Mögliche Werte: 0 = None, 1 = Sign, 2 = SignAndEncrypt. Vollständige Referenz: Parameter-Referenz. |
Response 500
{"error": "string"}
GET /gds/monitor/crt/{host_or_url}
Entspricht POST /gds/monitor/crt, verwendet jedoch die Konfiguration eines vorhandenen Inventareintrags. Das Gerät wird über host_or_url identifiziert. Port, Security Policy und Security Mode werden automatisch aus dem Inventareintrag übernommen.
Authentifizierung: X-API-Key erforderlich
Anfrage
Der Pfadparameter host_or_url ersetzt den Request Body. Er kann eine IP-Adresse, ein Hostname oder eine vollständige OPC UA URL sein:
# Variante 1: IP-Adresse
curl -X GET "http://localhost:5000/gds/monitor/crt/192.168.1.10" \
-H "X-API-Key: your-api-key"
# Variante 2: Hostname
curl -X GET "http://localhost:5000/gds/monitor/crt/plc-line1.example.com" \
-H "X-API-Key: your-api-key"
# Variante 3: vollständige OPC UA URL
curl -X GET "http://localhost:5000/gds/monitor/crt/opc.tcp://192.168.1.10:4840" \
-H "X-API-Key: your-api-key"
Pfadparameter
| Parameter | Beschreibung |
|---|---|
host_or_url | IP-Adresse, Hostname oder vollständige OPC UA URL (opc.tcp://host:port) eines vorhandenen Inventareintrags |
Antwort 200
Identisches Format wie POST /gds/monitor/crt. Felder x509 und fingerprint sind nicht enthalten, da diese nur auf explizite Anforderung im POST-Body zurückgegeben werden.
{
"idial_time": "2026-03-30T10:15:00+00:00",
"url": "opc.tcp://192.168.1.10:4840",
"security_policy": 8,
"security_mode": 2
}
POST /gds/inventory/crt
Liest detaillierte Zertifikatsinformationen von einem GDS-fähigen OPC UA Gerät aus und speichert sie im Inventar. Die Antwort enthält vollständige Zertifikatsmetadaten: Fingerabdrücke, Subject/Issuer DN, Gültigkeitszeitraum, Erweiterungen, Public-Key-Informationen, SAN sowie CRL Distribution Points.
Authentifizierung: X-API-Key erforderlich
Request Body
Identisch mit POST /gds/monitor/crt (Felder server, port und Verbindungsparameter).
Antwort 200
{
"name": "PLC Line 1",
"url": "opc.tcp://192.168.1.10:4840",
"server": "192.168.1.10",
"port": 4840,
"device_status": 1,
"certificate": {
"certificate_from_db": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
"certificate_der_base64": "MIID...",
"sha1_thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
"sha256_spki": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
"sha1_spki": "A94A8FE5CCB19BA61C4C0873D391E987982FBBD3",
"md5_spki": "098F6BCD4621D373CADE4E832627B4F6",
"subject_dn": "CN=plc-line1,O=ExampleCorp,C=DE",
"subject_cn": "plc-line1",
"subject_o": "ExampleCorp",
"issuer_dn": "CN=Issuing CA,O=ExampleCorp,C=DE",
"serial_number": "1A2B3C4D",
"serial_number_decimal": "438954061",
"valid_from": "2025-01-01T00:00:00",
"valid_to": "2026-01-01T00:00:00",
"remaining_days": 276,
"self_signed": false,
"x509_version": 3,
"key_type": "RSA",
"authority_key_identifier": "keyid:AB:CD:EF:...",
"authority_key_identifier_hex": "ABCDEF...",
"authority_key_identifier_dirname": null,
"authority_key_identifier_serial_number": null,
"basic_constraints_ca": false,
"basic_constraints_pathlen": null,
"subject_key_identifier": "A1:B2:C3:...",
"subject_key_identifier_hex": "A1B2C3...",
"key_usage": ["digitalSignature", "keyEncipherment"],
"extended_key_usage": ["serverAuth"],
"public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
"public_key_type": "RSA",
"public_key_size": 2048,
"public_key_xml": "<RSAKeyValue>...</RSAKeyValue>",
"san": {"dns": ["plc-line1.example.com"], "ip": ["192.168.1.10"]},
"cdp": ["http://crl.example.com/issuing.crl"]
},
"certificate_revocation": {
"id": 1,
"name": "not_revoked",
"description": "certificate was checked against a CRL and is not revoked"
},
"certificate_revocation_reason": null
}
Antwortfelder
Toplevel
| Feld | Typ | Beschreibung |
|---|---|---|
name | string | null | Anzeigename des Inventareintrags |
url | string | Vollständige OPC UA URL (opc.tcp://host:port) |
server | string | IP-Adresse oder FQDN des Geräts |
port | integer | OPC UA Port |
device_status | integer | null | Betriebsstatus gemäß Parameter-Referenz |
certificate | object | Geparste Zertifikatsinformationen (siehe unten) |
certificate_revocation | object | CRL-Prüfstatus (Felder id, name, description) |
certificate_revocation_reason | object | null | Widerrufsgrund gemäß RFC 5280, null wenn nicht widerrufen oder selbstsigniert |
certificate-Objekt
| Feld | Typ | Beschreibung |
|---|---|---|
certificate_from_db | string | Rohes PEM-Zertifikat exakt wie in der IDIAL-Datenbank gespeichert |
certificate_der_base64 | string | Zertifikat DER-kodiert als Base64 |
sha1_thumbprint | string | null | SHA-1-Fingerabdruck des Zertifikats (Hex, ohne Trennzeichen) |
sha256_spki | string | null | SHA-256-Hash des Subject Public Key Info (SPKI) |
sha1_spki | string | null | SHA-1-Hash des Subject Public Key Info (SPKI) |
md5_spki | string | null | MD5-Hash des Subject Public Key Info (SPKI) |
subject_dn | string | null | Vollständiger Subject Distinguished Name |
subject_cn | string | null | Common Name aus dem Subject DN |
subject_o | string | null | Organization aus dem Subject DN |
issuer_dn | string | null | Vollständiger Issuer Distinguished Name |
serial_number | string | null | Seriennummer des Zertifikats (hexadezimal) |
serial_number_decimal | string | null | Seriennummer des Zertifikats (dezimal) |
valid_from | string | null | Gültigkeitsbeginn (ISO 8601) |
valid_to | string | null | Ablaufdatum (ISO 8601) |
remaining_days | integer | null | Verbleibende Gültigkeitstage ab heute |
self_signed | boolean | true wenn Issuer und Subject identisch sind |
x509_version | integer | null | X.509-Version (in der Praxis immer 3) |
key_type | string | null | Schlüsseltyp, z. B. "RSA" oder "EC" |
authority_key_identifier | string | null | Authority Key Identifier (lesbare Form) |
authority_key_identifier_hex | string | null | Authority Key Identifier (Hex) |
authority_key_identifier_dirname | string | null | CA-Verzeichnisname aus der AKI-Erweiterung, falls vorhanden |
authority_key_identifier_serial_number | string | null | CA-Seriennummer aus der AKI-Erweiterung, falls vorhanden |
basic_constraints_ca | boolean | true wenn das Zertifikat als CA-Zertifikat markiert ist |
basic_constraints_pathlen | integer | null | Maximale Kettenlänge (nur bei CA-Zertifikaten) |
subject_key_identifier | string | null | Subject Key Identifier (lesbare Form) |
subject_key_identifier_hex | string | null | Subject Key Identifier (Hex) |
key_usage | string[] | Liste der Key Usage-Werte, z. B. ["digitalSignature", "keyEncipherment"] |
extended_key_usage | string[] | Liste der Extended Key Usage-Werte, z. B. ["serverAuth"] |
public_key_pem | string | null | Öffentlicher Schlüssel im PEM-Format |
public_key_type | string | null | Schlüsseltyp des öffentlichen Schlüssels, z. B. "RSA" |
public_key_size | integer | null | Schlüssellänge in Bits, z. B. 2048 |
public_key_xml | string | null | Öffentlicher Schlüssel im XML-Format (für Windows-Kompatibilität) |
san | object | Subject Alternative Names, gruppiert nach Typ (z. B. {"dns": [...], "ip": [...]}) |
cdp | string[] | CRL Distribution Point URIs |
GET /gds/inventory/crt/{host_or_url}
Entspricht POST /gds/inventory/crt, liest jedoch das in der IDIAL-Datenbank gespeicherte Zertifikat des Geräts aus — ohne eine Live-Verbindung aufzubauen. Das Gerät wird über host_or_url identifiziert.
Authentifizierung: X-API-Key erforderlich
Anfrage
# Variante 1: IP-Adresse
curl -X GET "http://localhost:5000/gds/inventory/crt/192.168.1.10" \
-H "X-API-Key: your-api-key"
# Variante 2: vollständige OPC UA URL
curl -X GET "http://localhost:5000/gds/inventory/crt/opc.tcp://192.168.1.10:4840" \
-H "X-API-Key: your-api-key"
Pfadparameter
| Parameter | Beschreibung |
|---|---|
host_or_url | IP-Adresse, Hostname oder vollständige OPC UA URL (opc.tcp://host:port) eines vorhandenen Inventareintrags |
Antwort 200
Identisches Format wie POST /gds/inventory/crt (siehe Feldtabellen oben).
GET /gds/monitor/plc/{host_or_url}
Liest gerätespezifische Informationen von einer OPC UA SPS aus: Geräterevision, Engineering-Revision, Modell, Betriebsmodus und Seriennummer. Es wird eine Live-Verbindung zum Gerät aufgebaut. Der Inventareintrag wird über host_or_url identifiziert.
Authentifizierung: X-API-Key erforderlich
Anfrage
# Variante 1: IP-Adresse
curl -X GET "http://localhost:5000/gds/monitor/plc/192.168.1.10" \
-H "X-API-Key: your-api-key"
# Variante 2: vollständige OPC UA URL
curl -X GET "http://localhost:5000/gds/monitor/plc/opc.tcp://192.168.1.10:4840" \
-H "X-API-Key: your-api-key"
Pfadparameter
| Parameter | Beschreibung |
|---|---|
host_or_url | IP-Adresse, Hostname oder vollständige OPC UA URL (opc.tcp://host:port) eines vorhandenen Inventareintrags |
Antwort 200
{
"url": "opc.tcp://192.168.1.10:4840",
"device_revision": "V1.0",
"engineering_revision": "V1.2",
"model": "S7-1500",
"operating_mode": "RUN",
"serial_number": "S7-15000001"
}
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
url | string | Vollständige OPC UA URL des Geräts (opc.tcp://host:port) |
device_revision | string | null | Hardware-Revisionskennung des Geräts, wie vom Gerät gemeldet |
engineering_revision | string | null | Engineering-Tool-Revisionskennung, wie vom Gerät gemeldet |
model | string | null | Gerätemodellbezeichnung, z. B. "S7-1500" |
operating_mode | string | null | Aktueller Betriebsmodus des Geräts, z. B. "RUN", "STOP" oder "STARTUP" |
serial_number | string | null | Seriennummer des Geräts |
Die Felder device_revision, engineering_revision, model, operating_mode und serial_number sind geräteabhängig. Wenn ein Gerät einen Wert nicht meldet, wird null zurückgegeben.
POST /gds/monitor/trustlist
Liest die Trust List eines GDS-fähigen OPC UA Servers aus. Abhängig von der trustlist-Bitmaske werden vertrauenswürdige Zertifikate, vertrauenswürdige CRLs, Ausstellerzertifikate und Aussteller-CRLs zurückgegeben.
Authentifizierung: X-API-Key erforderlich
Request Body
{
"server": "192.168.1.10",
"port": 4840,
"security_policy": 8,
"security_mode": 2,
"trustlist": 15,
"mask": false
}
| Feld | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
server | string | Ja | — | IP-Adresse oder FQDN des OPC UA Servers. Der server-Wert ist der eindeutige Bezeichner des Endpoints innerhalb der IDIAL-Datenbank. |
port | integer | Nein | 4840 | OPC UA Port. Wenn nicht angegeben, wird der Standard-Port 4840 verwendet. |
security_policy | integer | Nein | 31 | Siehe Parameter-Referenz |
security_mode | integer | Nein | 0 | Siehe Parameter-Referenz |
trustlist | integer | Nein | 15 | Bitmaske: welche Trust-List-Komponenten abgerufen werden sollen. Der angegebene Wert kann eine Kombination mehrerer erlaubter Werte sein, die von IDIAL zur Ermittlung der gewünschten Informationen berechnet wird. Standard: 15 (alle Komponenten). Erlaubte Werte: 0 = keine, 1 = TrustedCertificates, 2 = TrustedCrls, 4 = IssuerCertificates, 8 = IssuerCrls. Beispiel: 15 = alle Komponenten (1+2+4+8). Siehe Parameter-Referenz. |
mask | boolean | Nein | false | Steuert die für den Trust-List-Zugriff verwendete OPC UA Methode. Standard: false (verwendet die Open()-Standardmethode). Bei true: Verwendet OpenWithMasks() für erweiterte Zugriffskontrolle. |
Antwort 200
{
"success": true,
"execution": "TrustedCertificates: 3 certificate(s) read\nTrustedCrls: 1 CRL(s) read\n...",
"error": "",
"result": {
"TrustedCertificates": ["MIID...", "MIID..."],
"TrustedCrls": ["MIIB..."],
"IssuerCertificates": ["MIID..."],
"IssuerCrls": []
}
}
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
success | boolean | true wenn der Trust-List-Abruf erfolgreich war |
execution | string | Ausgabetext des ausgeführten Trust-List-Skripts (Statusmeldungen) |
error | string | Fehlermeldung bei success: false, sonst leer |
result | object | null | Trust-List-Inhalte aufgeteilt nach Komponente (siehe unten) |
result.TrustedCertificates | string[] | PEM-kodierte vertrauenswürdige Zertifikate |
result.TrustedCrls | string[] | PEM-kodierte vertrauenswürdige CRLs |
result.IssuerCertificates | string[] | PEM-kodierte Ausstellerzertifikate |
result.IssuerCrls | string[] | PEM-kodierte Aussteller-CRLs |
result enthält nur die Komponenten, die über die trustlist-Bitmaske angefordert wurden. Nicht angeforderte Komponenten fehlen im Objekt. Wenn keine Einträge vorhanden sind, wird ein leeres Array zurückgegeben.
Antwortcodes
| Code | Beschreibung |
|---|---|
200 | Trust-List-Inhalte mit den angeforderten Komponenten |
400 | Ungültiges Eingabefeld |
500 | {"error": "string"} |
GET /gds/monitor/trustlist/{host_or_url}
Entspricht POST /gds/monitor/trustlist, verwendet jedoch einen vorhandenen Inventareintrag. Es werden alle Trust-List-Komponenten abgerufen (trustlist: 15).
Authentifizierung: X-API-Key erforderlich
Anfrage
# Variante 1: IP-Adresse
curl -X GET "http://localhost:5000/gds/monitor/trustlist/192.168.1.10" \
-H "X-API-Key: your-api-key"
# Variante 2: vollständige OPC UA URL
curl -X GET "http://localhost:5000/gds/monitor/trustlist/opc.tcp://192.168.1.10:4840" \
-H "X-API-Key: your-api-key"
Pfadparameter
| Parameter | Beschreibung |
|---|---|
host_or_url | IP-Adresse, Hostname oder vollständige OPC UA URL (opc.tcp://host:port) eines vorhandenen Inventareintrags |
Antwort 200
Identisches Format wie POST /gds/monitor/trustlist. Es werden immer alle Komponenten abgerufen (trustlist: 15).
DELETE /gds/monitor/trustlist
Entfernt ein bestimmtes Zertifikat aus der Trust List eines entfernten GDS OPC UA Servers. Das zu löschende Zertifikat wird über seinen SHA-1-Thumbprint identifiziert oder alternativ über einen Zertifikatsdateipfad, aus dem IDIAL den Thumbprint ableitet.
Authentifizierung: X-API-Key erforderlich
Request Body
{
"server": "192.168.1.10",
"port": 4840,
"security_policy": 8,
"security_mode": 2,
"trustlist": 1,
"thumbprint": "A1B2C3D4E5F6789012345678"
}
Zusätzliche Felder gegenüber POST /gds/monitor/trustlist:
| Feld | Typ | Beschreibung |
|---|---|---|
thumbprint | string | SHA-1-Thumbprint (Hex, mit oder ohne 0x-Präfix) |
certificate | string | Pfad zur Zertifikatsdatei, aus der der Thumbprint abgeleitet wird |
Beispiele
# Zertifikat eines Geräts im Echtzeitzugriff lesen
curl -X POST http://localhost:5000/gds/monitor/crt \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"server": "192.168.1.10", "port": 4840, "fingerprint": "sha1"}'
# Trust List über Inventareintrag abrufen
curl -X GET "http://localhost:5000/gds/monitor/trustlist/192.168.1.10" \
-H "X-API-Key: your-api-key"