Renewing or Replacing a Certificate Manually

In the event of a key compromise, a configuration error, or an ad-hoc requirement, a certificate can be renewed immediately, independently of the scheduler. IDIAL provides two endpoints: POST /gds/push for a straightforward renewal using existing parameters, and POST /gds/push/change for re-issuance with changed certificate parameters.

warning

A manual renewal overwrites the current certificate on the device immediately. Ensure the device is reachable and the connection parameters are correct before proceeding.

Prerequisites

• The device is registered in the inventory
• A PKI endpoint is assigned to the device (or the connection parameters are passed directly)
• The device is reachable over the network
• An API key is available

Step 1 — Simple renewal (POST /gds/push)

POST /gds/push issues a new certificate and transfers it to the device. The certificate parameters are taken from the configured PKI endpoint.

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.100",
    "port": 4840
  }' \
  https://<idial-host>:5000/gds/push

Request parameters

Parameter	Type	Default	Description
server	string	—	IP address or FQDN of the OPC UA server
port	integer	4840	OPC UA port (1–65535)
subject	string	—	Certificate subject (overrides PKI configuration)
username	string	—	Authentication username (overrides inventory entry)
password	string	—	Authentication password (overrides inventory entry)
trusted	boolean	false	Write certificate into the TRUSTED trust list
issuer	boolean	false	Write certificate into the ISSUER trust list
security_policy	integer	0	Bitmask of allowed Security Policies (see Parameter Reference)
security_mode	integer	0	Bitmask of allowed Security Modes (see Parameter Reference)
allow_insecure_connection	boolean	false	Skip certificate verification and CRL check

note

username and password must either both be set or both be empty. If not provided, IDIAL uses the credentials stored in the inventory entry.

Success response

{
  "success": true,
  "execution": "Certificate Update successfully executed\nGDS Push finished with success",
  "error": ""
}

Step 2 — Renewal with changed parameters (POST /gds/push/change)

POST /gds/push/change issues a new certificate with different parameters — for example, a different key algorithm or a self-signed certificate.

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.100",
    "port": 4840,
    "self_signed": false,
    "algorithm": 4096
  }' \
  https://<idial-host>:5000/gds/push/change

Additional parameters (compared to POST /gds/push)

Parameter	Type	Default	Description
self_signed	boolean	true	Issue a self-signed certificate
algorithm	integer	2048	RSA key length in bits: 1024, 2048, 3072, or 4096

tip

Use POST /gds/push/change with "algorithm": 4096 when a device requires a new key pair after a key compromise. The new key is generated on the GDS server and immediately transferred to the device.

warning

A key change alters the fingerprint of the device certificate. Systems that explicitly trust the old certificate (e.g. via pinned certificates) must be updated.

Step 3 — Verify the result

After the renewal, the currently installed certificate can be retrieved:

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.100",
    "port": 4840,
    "fingerprint": "SHA1",
    "x509": true
  }' \
  https://<idial-host>:5000/gds/monitor/crt

The response contains the fingerprint and full X.509 details of the newly issued certificate.

Summary

POST /gds/push         → renew certificate with existing parameters
POST /gds/push/change  → issue certificate with new parameters
POST /gds/monitor/crt  → verify renewal result

Next steps

• POST /gds/push — API Reference

Troubleshooting

Symptom	Possible cause	Solution
"success": false with connection error	Device unreachable	Check IP/port, test network connectivity
"success": false with authentication error	Credentials missing or incorrect	Pass username/password directly in the request
Renewal successful but old certificate still active	Device requires restart	Restart the device to activate the new certificate
allow_insecure_connection required	CRL unreachable or certificate not in trust list	Check CRL reachability or update trust list