GDS Push — Certificate Enrollment

GDS Push is the primary mechanism for certificate enrollment on OPC UA devices managed by IDIAL. IDIAL connects to the OPC UA Global Discovery Server (GDS) interface of the target device, issues a certificate via the configured PKI endpoint, and transfers it to the device's certificate store. At the same time, the trust list (CA chain and CRL) is provisioned on the device.

Before the first enrollment, IDIAL verifies the connection to the device and stores the credentials for subsequent automated operations.

POST /gds/push

Issues a certificate and transfers it to a GDS-capable OPC UA endpoint. If the device does not yet exist in the inventory, it is automatically registered. The submitted credentials are stored for future automated renewals.

Authentication: X-API-Key required

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
}

Field	Type	Required	Default	Description
server	string	Yes	—	IP address or FQDN of the target device. The server value is the unique identifier of the endpoint within the IDIAL database — there must not be multiple endpoints with the same server identifier.
port	integer	No	4840	OPC UA port
name	string	No	—	Name of the endpoint, freely chosen by OT personnel. Helps to uniquely identify the target component, as IP addresses are not always unique in large OT environments. The name has no effect on the certificate content and is used solely for readability and reporting.
subject	string	No	—	Desired subject DN for the target certificate. If no value is provided, IDIAL evaluates the options for setting default information in the subject DN during certificate issuance. Note: The PKI may have specific requirements regarding the subject DN format and content. In practice, parts of the DN (e.g., OU, O, C) are often predefined by the issuing CA via the certificate template.
username	string	No	—	Username that IDIAL uses to connect to the GDS endpoint. Optional — if the user is already defined in IDIAL, this field can be omitted. If set, IDIAL updates the username in the configuration and uses it for all subsequent requests.
password	string	No	—	Password of the user that IDIAL uses to connect to the GDS endpoint. Optional — if the user is already defined, this field can be omitted. If set, IDIAL updates the password and uses it for all subsequent requests. Encrypted before storage.
issuer	boolean	No	false	Default: false. If true: The issuer CA certificate of the OPC UA client certificate used by IDIAL is added to the device's trust store and marked as trusted. Recommended practice: Renewal of the client certificate does not affect the trust relationship as long as it is issued by the same issuer.
trusted	boolean	No	false	Default: false. If true: The OPC UA client certificate used by IDIAL is explicitly added to the device's trust store. It is recommended to also set issuer: true to ensure the issuer is trusted. Otherwise, the client may be locked out of the endpoint if the client certificate changes and is not explicitly trusted again.
security_policy	integer	No	31	See Parameter Reference
security_mode	integer	No	0	See Parameter Reference
debug	boolean	No	false	Default: false. If true: Additional process information is added to the response.

tip

Use issuer: true (instead of or in addition to trusted: true) so that the device continues to accept the IDIAL connection after the client certificate is renewed. This prevents unintended connection lockouts.

Response 200

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

Responses

Code	Description
200	Certificate successfully enrolled
422	Validation error — certificate could not be provisioned
500	{"error": "string"}

---

GET /gds/push/{host_or_url}

Triggers GDS Push for an existing inventory entry. Uses the stored credentials and PKI configuration from the inventory. No request body required.

Authentication: X-API-Key required

Path Parameters

Parameter	Description
host_or_url	IP address, hostname, or OPC UA URL of an inventory entry

Response 200

Identical to POST /gds/push.

---

POST /gds/push/change

Changes or renews the certificate on an existing GDS endpoint. Extends the parameters of POST /gds/push with the selection of the algorithm for key pair generation.

Authentication: X-API-Key required

Request Body

Identical to POST /gds/push, extended with the following fields:

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

Field	Type	Default	Description
self_signed	boolean	true	Indicates whether the new certificate should be self-signed
algorithm	integer	2048	RSA key length in bits. Allowed values: 1024, 2048, 3072, 4096

---

POST /gds/firmware

Reads firmware information directly from a GDS-capable OPC UA device. Returns product name, manufacturer, software version, and device type.

Authentication: X-API-Key required

Request Body

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

Field	Type	Required	Default	Description
server	string	Yes	—	IP address or FQDN
port	integer	No	4840	OPC UA port
username	string	No	—	Username (taken from inventory if not provided)
password	string	No	—	Password (taken from inventory if not provided)
security_policy	integer	No	0	Security policy bitmask
security_mode	integer	No	0	Security mode
allow_insecure_connection	boolean	No	false	Allow connection without certificate trust validation

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}

Equivalent to POST /gds/firmware, but uses the credentials of an existing inventory entry.

Authentication: X-API-Key required

Path Parameters

Parameter	Description
host_or_url	IP address, hostname, or OPC UA URL of an inventory entry

---

GET /gds/status/{host_or_url}

Reads the GDS status of a device: GDS state, current device time, and information about whether provisioning mode is active or enabled.

Authentication: X-API-Key required

Path Parameters

Parameter	Description
host_or_url	IP address, hostname, or OPC UA URL of an inventory entry

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

Downloads the OPC UA client certificate that IDIAL uses when connecting to OPC UA GDS devices. The certificate is returned in PEM or DER format. It must be trusted by the managed OPC UA endpoints for IDIAL to establish a connection.

Authentication: X-API-Key required

Response 200: Binary certificate file (PEM or DER).

---

Examples

# Initial certificate enrollment (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
  }'

# Trigger GDS Push via inventory entry
curl -X GET "http://localhost:5000/gds/push/192.168.1.10" \
  -H "X-API-Key: your-api-key"

# Read firmware information
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}'

# Download IDIAL's own OPC UA client certificate
curl -X GET http://localhost:5000/gds/crt \
  -H "X-API-Key: your-api-key" \
  -o idial-client.pem