PKI-Konfiguration

PKI-Endpunkte definieren die Zertifizierungsstellen, die IDIAL für die Zertifikatsausstellung an verwaltete OPC UA Geräte verwendet. Jedem Inventareintrag wird ein PKI-Endpunkt zugewiesen. Dieser legt fest, welche CA das Zertifikat für das jeweilige Gerät ausstellt und welche Trust List auf dem Gerät bereitgestellt wird.

GET /pki

Gibt alle in IDIAL konfigurierten PKI-Endpunkte zurück.

Authentifizierung: X-API-Key erforderlich

Response 200

Array von PKI-Endpunkt-Konfigurationsobjekten.

[
  {
    "id": 1,
    "name": "Production EST",
    "url": "https://est.example.com/.well-known/est",
    "auth_method": "basic_auth",
    "tls_validation": "standard"
  }
]

GET /pki/ca

Lädt das CA-Zertifikat vom konfigurierten PKI-Endpunkt im PEM- oder DER-Format herunter. Dient zur Überprüfung, ob IDIAL mit der richtigen Zertifizierungsstelle verbunden ist.

Authentifizierung: X-API-Key erforderlich

Response 200: Binäres CA-Zertifikat (PEM oder DER).

GET /pki/crl

Lädt die Certificate Revocation List (CRL) vom konfigurierten PKI-Endpunkt im PEM- oder DER-Format herunter.

Authentifizierung: X-API-Key erforderlich

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

GET /pki/est

Gibt alle in IDIAL verwalteten EST-Endpunktkonfigurationen zurück. Dieser Endpunkt wird verwendet, um die aktuelle EST-Konfiguration von IDIAL abzurufen. Die zurückgegebene id wird für alle Änderungsoperationen an EST-Konfigurationen benötigt.

Authentifizierung: X-API-Key erforderlich

Response 200

Array von EST-Konfigurationsobjekten:

[
  {
    "id": 1,
    "last_validated": "2026-03-06 10:30:45",
    "server": "est.example.com",
    "port": 8443,
    "enroll_endpoint": "/.well-known/est/profile1/simpleenroll",
    "renew_endpoint": "/.well-known/est/profile1/simplereenroll",
    "username": "estuser",
    "password_hash": "a1b2c3d4e5f6...",
    "enroll_auth": "basic",
    "renew_auth": "certificate",
    "tlschain": "MIIBxDCC...",
    "cacert": "MIIBxDCC...",
    "description": "Production EST Endpoint"
  }
]

Antwortfelder

Feld	Typ	Beschreibung
`id`	integer	Eindeutiger Bezeichner der EST-Konfiguration. Wird für alle Änderungsoperationen benötigt.
`last_validated`	string	Datum und Uhrzeit der letzten erfolgreichen Validierung. Leerer Wert, wenn der EST-Endpunkt noch nicht validiert wurde — in diesem Fall kann er keinem verwalteten Gerät zugewiesen werden.
`server`	string	IP-Adresse oder DNS-FQDN des EST-Servers. Das Serverzertifikat des EST-Servers sollte diesen Wert im SAN-Attribut enthalten, damit IDIAL die TLS-Server-Authentifizierung erfolgreich durchführen kann. Wenn ein DNS-FQDN angegeben wird, muss dieser von IDIAL auflösbar sein.
`port`	integer	Netzwerkport des EST-Server-Endpunkts.
`enroll_endpoint`	string	URI auf dem Server für die initiale Zertifikatsausstellung; entspricht dem `/simpleenroll`-Endpunkt im EST-Standard.
`renew_endpoint`	string	URI auf dem Server für die Zertifikatserneuerung; entspricht dem `/simplereenroll`-Endpunkt im EST-Standard. IDIAL erwartet standardmäßig TLS-Client-Authentifizierung mit dem Zertifikat, das erneuert werden soll.
`username`	string	Benutzername für Basic-Authentifizierung, sofern konfiguriert.
`password_hash`	string	SHA-256-Hash des aktuellen Basic-Auth-Passworts. Aus Sicherheitsgründen wird kein Klartext-Passwort zurückgegeben. Das Passwort kann über den Update-Endpunkt geändert werden.
`enroll_auth`	string	Aktuell konfigurierte Authentifizierungsmethode für den `/simpleenroll`-Endpunkt.
`renew_auth`	string	Aktuell konfigurierte Authentifizierungsmethode für den `/simplereenroll`-Endpunkt.
`tlschain`	string	Base64-kodiertes PKCS7-Objekt der Vertrauenskette des EST-Serverzertifikats. Ermöglicht die Überprüfung, ob die korrekte Vertrauenskette für die TLS-Server-Zertifikatvalidierung konfiguriert ist. Enthält die Kette vom EST-Server-Issuing-CA-Zertifikat bis zum Root-CA-Zertifikat.
`cacert`	string	Base64-kodiertes PKCS7-Objekt der Root-CA-Zertifikate, die vom EST-Server bereitgestellt werden. Nur verfügbar, wenn der EST-Server den `/cacerts`-Endpunkt gemäß RFC 7030 anbietet.
`description`	string	Beschreibender Name des EST-Endpunkts zur leichteren Identifikation in der Benutzeroberfläche.

Response 500

{"error": "string"}

POST /pki/est

Fügt einen neuen EST-Endpunkt zu IDIAL hinzu. IDIAL verwendet EST, um Zertifikate für verbundene Geräte und Workloads auszustellen und zu erneuern. Es ist üblich, mehrere EST-Endpunkte zu konfigurieren, da unterschiedliche Zertifikatsvorlagen für verschiedene Gerätekategorien oder organisatorische Anforderungen benötigt werden.

hinweis

Der EST-Endpunkt wird in IDIAL angelegt, aber während dieser Phase nicht validiert. Um den Endpunkt zu validieren, muss anschließend ein Aufruf an /pki/est/validate erfolgen. Nach erfolgreicher Validierung enthält das Feld last_validated den Zeitstempel der letzten erfolgreichen Verbindung.

Das folgende Beispiel verdeutlicht den Aufbau der EST-Verbindungs-URL:

EST URL:
https://server-fqdn.domain:8443/.well-known/est/profile1/simpleenroll
\________________/ \__/ \___________________________________/
server       port    enroll_endpoint / renew_endpoint

Authentifizierung: X-API-Key erforderlich

Anfrage-Body

{
  "server": "est.example.com",
  "port": 8443,
  "enroll_endpoint": "/.well-known/est/profile1/simpleenroll",
  "renew_endpoint": "/.well-known/est/profile1/simplereenroll",
  "username": "estuser",
  "password": "secret",
  "enroll_auth": "basic",
  "renew_auth": "certificate",
  "tlschain": "MIIBxDCC...",
  "validate_server": true,
  "description": "Production EST Endpoint"
}

Anfrage-Felder

Feld	Typ	Pflicht	Beschreibung
`server`	string	Ja	IP-Adresse oder FQDN des EST-Enrollment-Servers.
`port`	string	Ja	Port, auf dem der EST-Enrollment-Server lauscht.
`enroll_endpoint`	string	Ja	URI für die initiale oder wiederkehrende Zertifikatsausstellung für eine Zertifikatsvorlage.
`renew_endpoint`	string	Ja	URI für die Zertifikatserneuerung.
`username`	string	Nein	Benutzername für Basic-Authentifizierung an den EST-Endpunkten, für die Basic-Auth konfiguriert wurde. Wenn keine Basic-Auth-Zugangsdaten definiert sind, kann diese Authentifizierungsmethode keinem der Endpunkte zugewiesen werden — IDIAL antwortet in diesem Fall mit einem Fehler.
`password`	string	Nein	Passwort für Basic-Authentifizierung. Ein leeres Passwort ist nicht zulässig — wird es leer übergeben, verhält sich die Anfrage so, als wären weder `username` noch `password` gesendet worden.
`enroll_auth`	string	Nein	Authentifizierungsmethode für den `enroll_endpoint`.
`renew_auth`	string	Nein	Authentifizierungsmethode für den `renew_endpoint`.
`tlschain`	string	Nein	Base64-kodiertes PKCS7-Format der Vertrauenskette des EST-Serverzertifikats. Diese Kette wird zur Validierung des TLS-Serverzertifikats verwendet und sollte vom EST-Server-Issuing-CA-Zertifikat bis zum Root-CA-Zertifikat reichen. IDIAL verweigert die Verbindung zu einem nicht validierten EST-Server.
`validate_server`	boolean	Nein	Standard: `true`. IDIAL validiert standardmäßig die EST-Server-TLS-Verbindung und das Serverzertifikat. Kann auf `false` gesetzt werden, um die Validierung zu überspringen. Empfehlung: Server-Validierung aktiviert lassen, um sicherzustellen, dass Zertifikate nur über vertrauenswürdige und validierte Endpunkte ausgestellt werden.
`description`	string	Nein	Beschreibender Name des EST-Endpunkts. Wird in der Benutzeroberfläche anstelle der `id` angezeigt.

warnung

validate_server: false deaktiviert die TLS-Server-Zertifikatvalidierung. Dies sollte ausschließlich in kontrollierten Testumgebungen verwendet werden. In Produktivumgebungen ist die Server-Validierung ein kritisches Sicherheitsmerkmal, das sicherstellt, dass IDIAL Zertifikate nur über vertrauenswürdige und validierte Verbindungen ausstellt.

Response 200

{"id": 1}

Die id des neu angelegten EST-Eintrags wird im Response-Body zurückgegeben.

Response 500

{"error": "string"}

DELETE /pki/est/{id}

Löscht einen definierten EST-Endpunkt anhand seiner {id} in der URL.

warnung

Der EST-Endpunkt darf keinem verwalteten Gerät oder Workload in IDIAL mehr zugewiesen sein. Ist er noch zugewiesen, antwortet der Dienst mit einem Fehler. Alle betroffenen Workloads müssen zunächst auf einen anderen Enrollment-Endpunkt umkonfiguriert werden, bevor der EST-Endpunkt gelöscht werden kann.

Authentifizierung: X-API-Key erforderlich

Pfadparameter

Parameter	Beschreibung
`{id}`	ID des EST-Endpunkts in der IDIAL-Datenbank, der gelöscht werden soll.

Response 200

Der EST-Endpunkt wurde erfolgreich gelöscht.

Fehlerantwort (EST-Endpunkt noch in Verwendung)

{
  "in_use": [1, 2, 3],
  "error": "string"
}

Das Feld in_use enthält die IDs der IDIAL-Endpunkte, die den zu löschenden EST-Endpunkt noch verwenden.

PATCH /pki/est/{id}

Aktualisiert eine bestehende EST-Endpunktkonfiguration. Die Anfrage kann ein oder mehrere zu aktualisierende Attribute enthalten.

hinweis

Nach einer Aktualisierung der EST-Endpunktkonfiguration wird das last_validated-Flag zurückgesetzt. Anschließend muss /pki/est/validate/{id} aufgerufen werden, um eine erneute Validierung durchzuführen und sicherzustellen, dass IDIAL den Endpunkt erreichen und verwenden kann.

Authentifizierung: X-API-Key erforderlich

Anfrage-Body

Identisch mit POST /pki/est. Es werden nur die übermittelten Felder aktualisiert.

{
  "server": "est.example.com",
  "port": 8443,
  "enroll_endpoint": "/.well-known/est/profile1/simpleenroll",
  "renew_endpoint": "/.well-known/est/profile1/simplereenroll",
  "username": "estuser",
  "password": "secret",
  "enroll_auth": "basic",
  "renew_auth": "certificate",
  "tlschain": "MIIBxDCC...",
  "validate_server": true,
  "description": "Production EST Endpoint"
}

Response 200

Der EST-Endpunkt wurde erfolgreich aktualisiert.

Response 500

{"error": "string"}

POST /pki/sign-client-csr

Signiert einen Client-CSR (Certificate Signing Request) über das konfigurierte PKI-Protokoll. Unterstützt EST, CMP und interne Protokolle. Gibt das signierte X.509-Zertifikat im PEM-Format zurück.

Authentifizierung: X-API-Key erforderlich

Request Body

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "pki_protocol": "internal"
}

Feld	Typ	Pflicht	Standard	Beschreibung
`csr`	string	Ja	—	PEM-formatierter Certificate Signing Request
`pki_protocol`	string	Nein	`"internal"`	Protokoll: `"internal"`, `"est"` oder `"cmp"`

Response 200

{
  "x509": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
}

hinweis

Die Protokolle "est" und "cmp" sind für eine zukünftige Implementierungsphase vorgesehen. Derzeit wird ausschließlich "internal" vollständig unterstützt. Bei Verwendung von "est" oder "cmp" gibt der Endpunkt HTTP 501 zurück.

POST /pki/sign-server-csr

Entspricht POST /pki/sign-client-csr, signiert jedoch einen Server-CSR. Gibt das signierte X.509-Zertifikat zurück.

Authentifizierung: X-API-Key erforderlich

Request und Response: Identisch mit POST /pki/sign-client-csr.

Beispiele

# PKI-Endpunkte auflisten
curl -X GET http://localhost:5000/pki \
  -H "X-API-Key: your-api-key"

# CA-Zertifikat herunterladen
curl -X GET http://localhost:5000/pki/ca \
  -H "X-API-Key: your-api-key" \
  -o ca.pem

# Alle EST-Endpunkte auflisten
curl -X GET http://localhost:5000/pki/est \
  -H "X-API-Key: your-api-key"

# Neuen EST-Endpunkt hinzufügen
curl -X POST http://localhost:5000/pki/est \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "est.example.com",
    "port": 8443,
    "enroll_endpoint": "/.well-known/est/profile1/simpleenroll",
    "renew_endpoint": "/.well-known/est/profile1/simplereenroll",
    "validate_server": true,
    "description": "Production EST"
  }'

# EST-Endpunkt löschen
curl -X DELETE http://localhost:5000/pki/est/1 \
  -H "X-API-Key: your-api-key"

# Client-CSR signieren
curl -X POST http://localhost:5000/pki/sign-client-csr \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
    "pki_protocol": "internal"
  }'

GET /pki​

Response 200​

GET /pki/ca​

GET /pki/crl​

GET /pki/est​

Response 200​

Antwortfelder​

Response 500​

POST /pki/est​

Anfrage-Body​

Anfrage-Felder​

Response 200​

Response 500​

DELETE /pki/est/{id}​

Pfadparameter​

Response 200​

Fehlerantwort (EST-Endpunkt noch in Verwendung)​

PATCH /pki/est/{id}​

Anfrage-Body​

Response 200​

Response 500​

POST /pki/sign-client-csr​

Request Body​

Response 200​

POST /pki/sign-server-csr​

Beispiele​

GET /pki

Response 200

GET /pki/ca

GET /pki/crl

GET /pki/est

Response 200

Antwortfelder

Response 500

POST /pki/est

Anfrage-Body

Anfrage-Felder

Response 200

Response 500

DELETE /pki/est/{id}

Pfadparameter

Response 200

Fehlerantwort (EST-Endpunkt noch in Verwendung)

PATCH /pki/est/{id}

Anfrage-Body

Response 200

Response 500

POST /pki/sign-client-csr

Request Body

Response 200

POST /pki/sign-server-csr

Beispiele