Configuring and Assigning a PKI Endpoint to a Device

IDIAL supports multiple PKI types for issuing OPC UA application certificates. This guide explains how to view the configured PKI endpoints, download and verify the CA certificate, and assign a PKI endpoint to a GDS Push device.

note

PKI endpoints are pre-configured during IDIAL installation. Managing EST PKI endpoints (adding, editing, deleting) is done via IDIAL-APP.

PKI types in IDIAL

IDIAL supports three PKI types:

Type ID	Name	Description
1	INTERNAL	Integrated CA — IDIAL signs certificates directly using the configured CA (OpenSSL). No external PKI server required.
2	EST	EST protocol (RFC 7030) — certificate requests are forwarded to an external EST server.
3	CMP	CMP protocol (RFC 4210) — certificate requests via Certificate Management Protocol.

---

Step 1: View configured PKI endpoints

Retrieve all PKI endpoints configured in IDIAL. The pki_id is required to assign an endpoint to a device.

curl -X GET https://idial.example.com/pki \
  -H "X-API-Key: your-api-key"

Expected response (200):

[
  {
    "pki_id": 1,
    "pki_type": "INTERNAL",
    "pki_connection": "internal",
    "username": "",
    "opcua_server_template_uri": "",
    "opcua_client_template_uri": "",
    "opcua_webserver_template_uri": "",
    "ssh_webserver_template_uri": ""
  },
  {
    "pki_id": 2,
    "pki_type": "EST",
    "pki_connection": "https://est.example.com/.well-known/est",
    "username": "estuser",
    "opcua_server_template_uri": "est-opcua-server-template",
    "opcua_client_template_uri": "est-opcua-client-template",
    "opcua_webserver_template_uri": "",
    "ssh_webserver_template_uri": ""
  }
]

Response fields

Field	Description
pki_id	Unique identifier of the PKI endpoint — required for device assignment
pki_type	PKI type: INTERNAL, EST, or CMP
pki_connection	Connection identifier: "internal" for the internal type, URL for EST/CMP
username	Username for authentication at the EST/CMP server (empty for internal PKI)
opcua_server_template_uri	CA template URI for OPC UA server certificates
opcua_client_template_uri	CA template URI for OPC UA client certificates
opcua_webserver_template_uri	CA template URI for OPC UA web server certificates
ssh_webserver_template_uri	CA template URI for SSH web server certificates

Note for the following steps:

• The pki_id of the desired endpoint, e.g. 1 for the internal PKI

---

Step 2: Download and verify the CA certificate

Download the CA certificate of the internal PKI and verify that it corresponds to the expected issuer. This endpoint requires no authentication.

# Download in PEM format
curl -X GET https://idial.example.com/pki/ca \
  -H "Accept: application/x-pem-file" \
  -o ca.pem

# Download in DER format (default)
curl -X GET https://idial.example.com/pki/ca \
  -o ca.der

Verify the certificate with OpenSSL:

openssl x509 -in ca.pem -noout -subject -issuer -dates

Expected output:

subject=CN=IDIAL CA, O=BxC Security GmbH, C=DE
issuer=CN=IDIAL CA, O=BxC Security GmbH, C=DE
notBefore=Jan  1 00:00:00 2025 GMT
notAfter=Jan  1 00:00:00 2030 GMT

note

The CA certificate is self-signed (subject = issuer). It must be added to the trust stores of OPC UA devices so that certificates issued by IDIAL are accepted as trusted. The GDS Push process handles this automatically when using issuer: true.

---

Step 3: Download the CRL (optional)

Download the current Certificate Revocation List of the internal CA.

# PEM format
curl -X GET https://idial.example.com/pki/crl \
  -H "Accept: application/x-pem-file" \
  -o crl.pem

# Verify the CRL
openssl crl -in crl.pem -noout -issuer -lastupdate -nextupdate

---

Step 4: Assign a PKI endpoint to a GDS Push device

Assign the desired PKI endpoint to the device's inventory entry. Use PATCH /gds/inventory with the pki field and the corresponding pki_id from Step 1.

curl -X PATCH https://idial.example.com/gds/inventory \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840,
    "pki": 1
  }'

Field	Description
server	IP address or FQDN of the device — identifies the inventory entry
port	OPC UA port of the device
pki	pki_id from Step 1

Expected response (200):

{
  "id": 42,
  "name": "PLC Line 1",
  "url": "opc.tcp://192.168.1.10:4840",
  "server": "192.168.1.10",
  "port": 4840,
  "device_status": 1,
  "device_status_name": "active",
  "pki_endpoint": "internal",
  "cert_expdays": 365,
  "cert_revoked": false
}

After the update, the pki_endpoint field shows the connection value of the assigned PKI endpoint ("internal" or an EST/CMP URL).

---

Step 5: Confirm the assignment

Retrieve the inventory entry and verify that pki_endpoint is set correctly.

curl -X GET "https://idial.example.com/gds/inventory/192.168.1.10" \
  -H "X-API-Key: your-api-key"

Check in the response:

Field	Expected value
pki_endpoint	"internal" (type 1) or EST URL (type 2) — corresponds to the assigned endpoint

---

Process overview

Step 1  GET  /pki                     → view pki_id and pki_type
    ↓
Step 2  GET  /pki/ca                  → download and verify CA certificate
    ↓
Step 3  GET  /pki/crl  (optional)     → download CRL
    ↓
Step 4  PATCH /gds/inventory          → assign pki_id to the device
    ↓
Step 5  GET  /gds/inventory/{host}    → confirm assignment

---

Next steps

After the PKI configuration, the GDS Push workflow can be executed. The complete device registration guide is available at Registering an OPC UA GDS Push Device.

---

Troubleshooting

Symptom	Possible cause	Solution
GET /pki returns an empty list	PKI endpoints not yet configured	Use IDIAL-APP to configure PKI endpoints
GET /pki/ca returns 404	CA certificate not present on the IDIAL container	Add the CA certificate to the IDIAL container configuration
pki_endpoint remains empty after PATCH	pki field not passed correctly or pki_id invalid	Call GET /pki and verify a valid pki_id
GDS Push fails after PKI assignment	Template URI not configured or EST server unreachable	Check opcua_server_template_uri in IDIAL-APP, test connectivity to the EST server