PKI Configuration
PKI endpoints define the certificate authorities IDIAL uses to issue certificates to managed OPC UA devices. Each inventory entry is assigned a PKI endpoint that determines which CA issues the certificate and which trust list is provisioned on the device.
IDIAL supports four PKI types:
| Type ID | Name | Description |
|---|---|---|
0 | None | No PKI configured. |
1 | Internal | IDIAL uses its own internal CA. |
2 | EST | Enrollment over Secure Transport (RFC 7030). |
3 | CMP | Certificate Management Protocol (RFC 4210). |
GET /pki
Returns the supported PKI protocol types.
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/pki \
-H "X-API-Key: your-api-key"
Response 200
[
{"pki_type_id": 0, "pki_type": "none"},
{"pki_type_id": 1, "pki_type": "internal"},
{"pki_type_id": 2, "pki_type": "est"},
{"pki_type_id": 3, "pki_type": "cmp"}
]
GET /pki/inventory
Returns all configured PKI inventory entries.
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/pki/inventory \
-H "X-API-Key: your-api-key"
Response 200
[
{
"pki_id": 1,
"name": "Production EST",
"pki_type_id": 2,
"pki_connection": "est.example.com:8443",
"username": "estuser",
"password_encrypted": 1,
"additional_path_segment": "/profile1",
"est_client_certificate_sha1": "A1:B2:C3:D4:E5:F6:...",
"est_cdp_urls": ["http://crl.example.com/crl.crl"],
"tls_cdp_urls": [],
"tls_ca": ["MIIBxDCC..."],
"tls_crls_info": [
{
"crl_number": 42,
"crl_last_update": "2026-04-01T00:00:00",
"crl_next_update": "2026-05-01T00:00:00"
}
],
"creator_id": null
}
]
Response Fields
| Field | Type | Description |
|---|---|---|
pki_id | integer | Unique PKI entry identifier. |
name | string | null | Display name of the PKI entry. |
pki_type_id | integer | PKI type (0=none, 1=internal, 2=EST, 3=CMP). |
pki_connection | string | Connection string (host:port). |
username | string | null | Username for PKI authentication. |
password_encrypted | integer | Whether the password is stored encrypted (1) or not (0). |
additional_path_segment | string | null | Additional URL path segment for EST endpoints. |
est_client_certificate_sha1 | string | null | SHA-1 thumbprint of the EST client certificate. |
est_cdp_urls | string[] | CRL Distribution Point URLs for the EST CA certificate. |
tls_cdp_urls | string[] | CRL Distribution Point URLs for the TLS CA certificate. |
tls_ca | string[] | TLS CA certificate(s) used to verify the PKI server. |
tls_crls_info | object[] | CRL metadata for each configured TLS CRL. |
creator_id | string | null | Identifier of the creator (system or user). |
GET /pki/inventory/{pki_id}
Returns a single PKI inventory entry by ID.
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/pki/inventory/1 \
-H "X-API-Key: your-api-key"
Response 200
Single PKI entry. Response format matches GET /pki/inventory.
Response 404
{"error": "string"}
GET /pki/inventory/creator/{creator_id}
Returns all PKI inventory entries for a given creator ID.
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/pki/inventory/creator/system \
-H "X-API-Key: your-api-key"
Response 200
Array of PKI entries. Response format matches GET /pki/inventory.
POST /pki/inventory
Creates a new PKI inventory entry.
Authentication: Required (X-API-Key header)
Request
curl -X POST http://localhost:5000/pki/inventory \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"pki_type": 2,
"pki_connection": "est.example.com:8443",
"name": "Production EST",
"username": "estuser",
"password": "secret",
"additional_path_segment": "/profile1"
}'
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
pki_type | integer (0–3) | Yes | PKI type ID. |
pki_connection | string | Yes | Connection string (host:port). |
name | string | No | Display name. |
username | string | No | Authentication username. |
password | string | No | Authentication password. |
password_encrypted | integer (0/1) | No | Whether the supplied password is already encrypted. |
additional_path_segment | string | No | Additional EST URL path segment (e.g. "/profile1"). |
est_client_pkcs12_base64 | string (≥ 160 chars) | No | Base64-encoded PKCS#12 for EST client certificate authentication (write-only). |
est_client_pkcs12_password | string (≤ 1024 chars) | No | Password for the EST client PKCS#12 (write-only). |
est_cdp_urls | string[] | No | CRL Distribution Point URLs for the EST CA certificate. |
tls_cdp_urls | string[] | No | CRL Distribution Point URLs for the TLS CA certificate. |
tls_ca | string[] | No | TLS CA certificates used to verify the PKI server. |
tls_crls | string[] | No | TLS CRL files. |
creator_id | any | No | Creator identifier. |
Response 200
Created PKI entry. Response format matches GET /pki/inventory.
PATCH /pki/inventory/{pki_id}
Updates an existing PKI inventory entry. Only supplied fields are updated.
Authentication: Required (X-API-Key header)
Request
curl -X PATCH http://localhost:5000/pki/inventory/1 \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"name": "Updated EST", "additional_path_segment": "/new-profile"}'
Request Fields
Same as POST /pki/inventory. All fields are optional.
Response 200
Updated PKI entry. Response format matches GET /pki/inventory.
Response 404
{"error": "string"}
DELETE /pki/inventory/{pki_id}
Deletes a PKI inventory entry.
Authentication: Required (X-API-Key header)
Request
curl -X DELETE http://localhost:5000/pki/inventory/1 \
-H "X-API-Key: your-api-key"
Response 200
Deleted PKI entry. Response format matches GET /pki/inventory.
Response 404
{"error": "string"}
GET /pki/exec/validate/{pki_id}
Connects to the EST server for the specified PKI entry and fetches its CA certificates. Stores the result locally and returns the CA certificate fingerprints. The PKI entry must be of type 2 (EST).
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/pki/exec/validate/1 \
-H "X-API-Key: your-api-key"
Response 200
{
"pki_id": 1,
"host": "est.example.com",
"port": 8443,
"ca_fingerprints": [
"A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78"
]
}
Response Fields
| Field | Type | Description |
|---|---|---|
pki_id | integer | ID of the PKI entry that was validated. |
host | string | EST server hostname. |
port | integer | EST server port. |
ca_fingerprints | string[] | SHA-1 fingerprints of the fetched CA certificates. |
Response 400
Returned when the PKI entry is not of type EST, or has no connection configured.
GET /pki/exec/validate-strict/{pki_id}
Performs a strict EST CA certificate validation, including TLS chain verification against the configured tls_ca. Requires the PKI entry to have TLS CA certificates configured.
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/pki/exec/validate-strict/1 \
-H "X-API-Key: your-api-key"
Response 200
Response format matches GET /pki/exec/validate/{pki_id}.
Response 400
Returned when the PKI entry is not of type EST, has no connection configured, or has no TLS CA configured.
GET /pki/ca/{pki_id}
Downloads the CA certificate for the specified PKI entry. Supports internal (type 1) and EST (type 2) PKI entries.
Authentication: Not required
Request
# Download as PEM (default)
curl -X GET http://localhost:5000/pki/ca/1
# Download as DER
curl -X GET "http://localhost:5000/pki/ca/1?format=der"
Response 200
Binary CA certificate file. Add ?format=pem or ?format=der to specify the download format.
| Format | MIME type | Filename |
|---|---|---|
| PEM | application/x-pem-file | ca.pem / ca-{pki_id}.pem |
| DER | application/pkix-cert | ca.der / ca-{pki_id}.der |
Response 404
Returned when no CA certificate is available. For EST type, run GET /pki/exec/validate/{pki_id} first.
GET /pki/crl/{pki_id}
Downloads the CRL for the specified PKI entry. IDIAL resolves the CRL Distribution Point URL from the stored CA certificate or the configured est_cdp_urls and fetches the CRL live.
Authentication: Not required
Request
# Download as PEM (default)
curl -X GET http://localhost:5000/pki/crl/1
# Download as DER
curl -X GET "http://localhost:5000/pki/crl/1?format=der"
Response 200
Binary CRL file.
| Format | MIME type | Filename |
|---|---|---|
| PEM | application/x-pem-file | crl-{pki_id}.pem |
| DER | application/pkix-crl | crl-{pki_id}.der |
Response 404
Returned when no CRL Distribution Point URLs are available.
Response 502
Returned when the CRL cannot be downloaded from any CDP URL.
GET /pki/crt/{pki_id}
Downloads the EST client certificate stored for the specified PKI entry. This is the certificate IDIAL uses when authenticating to the EST server.
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/pki/crt/1 \
-H "X-API-Key: your-api-key"
Response 200
Binary EST client certificate file.
| Format | MIME type | Filename |
|---|---|---|
| PEM | application/x-pem-file | crt-{pki_id}.pem |
| DER | application/pkix-cert | crt-{pki_id}.der |
Response 404
{"error": "No EST client certificate stored for PKI entry {pki_id}"}
POST /pki/sign-client-csr
Signs a client CSR using the IDIAL internal CA and returns the issued certificate.
Authentication: Required (X-API-Key header)
Request
curl -X POST http://localhost:5000/pki/sign-client-csr \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----"}'
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
csr_pem | string | Yes | PEM-encoded Certificate Signing Request. |
Response 200
{
"certificate_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}
POST /pki/sign-server-csr
Signs a server CSR using the IDIAL internal CA and returns the issued certificate.
Authentication: Required (X-API-Key header)
Request
curl -X POST http://localhost:5000/pki/sign-server-csr \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----"}'
Request Fields
Same as POST /pki/sign-client-csr.
Response 200
Response format matches POST /pki/sign-client-csr.