Certificate Monitoring
The monitoring endpoints establish a live connection to the target device and read certificate information, trust lists, and device metadata directly. Unlike the inventory, which returns cached data, an active OPC UA connection is established with every call.
The monitoring endpoints establish a live connection to the target device. Ensure that the target device is reachable from the IDIAL container before calling these endpoints.
POST /gds/monitor/crt
Connects to a remote OPC UA server and reads its current application certificate. Optionally, the full X.509 text representation is returned and a fingerprint is calculated. This endpoint is suitable for real-time certificate inspection without relying on cached inventory data.
Authentication: X-API-Key required
Request Body
{
"server": "192.168.1.10",
"port": 4840,
"x509": false,
"fingerprint": "sha1",
"connection_security": false,
"disable_crl_check": false
}
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
server | string | Yes | — | IP address or DNS FQDN of the OPC UA server. 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 | string | No | "4840" | OPC UA port. If not provided, the default port "4840" is used. |
x509 | boolean | No | false | Include a human-readable certificate text representation in the response. If true, the x509 field with full certificate details in text format is added. |
fingerprint | string | No | — | Calculate the fingerprint of the device certificate. Supported value: "SHA1" (case-insensitive). If provided, the fingerprint field with the certificate hash is added to the response. |
connection_security | boolean | No | false | Enable secure connection mode for OPC UA communication. If true, security features are enabled for the OPC UA connection. |
disable_crl_check | boolean | No | false | Skip CRL check when establishing the connection |
Response 200
{
"url": "opc.tcp://192.168.1.10:4840",
"fingerprint": "A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78",
"x509": "Certificate:\n Data:\n Version: 3 (0x2)\n Serial Number:\n 22:b4:e2:45:34:27:f6:d5:fc:39:94:99:0d:1f:e3:b1:49:02:de:44\n Signature Algorithm: sha256WithRSAEncryption\n Issuer: C=DE, ST=Bayern, L=Muenchen, O=ExampleOPC, OU=IT, CN=opcua-server.local\n Validity\n Not Before: Mar 5 08:59:03 2026 GMT\n Not After : Mar 5 08:59:03 2027 GMT\n Subject: C=DE, ST=Bayern, L=Muenchen, O=ExampleOPC, OU=IT, CN=opcua-server.local\n ...",
"security_policy": 8,
"security_mode": 2
}
| Field | Type | Description |
|---|---|---|
url | string | Full OPC UA connection URL (opc.tcp://server:port). Only present if the device is registered in the inventory. Used to link the certificate information to known devices. |
fingerprint | string | Certificate hash in hexadecimal format. Only present if the fingerprint field was specified with a supported hash algorithm in the request. Example: "A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78". |
x509 | string | Human-readable certificate information including subject, issuer, and validity dates. Only present if x509: true was set in the request. Contains full certificate details in text format. |
security_policy | integer | Negotiated OPC UA Security Policy as a bitmask. The value indicates which policy was used during the connection. Possible values: 1 = Basic128Rsa15, 2 = Basic256, 4 = Aes128Sha256RsaOaep, 8 = Basic256Sha256, 16 = Aes256Sha256RsaPss. Full reference: Parameter Reference. |
security_mode | integer | Negotiated OPC UA Security Mode. Possible values: 0 = None, 1 = Sign, 2 = SignAndEncrypt. Full reference: Parameter Reference. |
Response 500
{"error": "string"}
GET /gds/monitor/crt/{host_or_url}
Equivalent to POST /gds/monitor/crt, but uses the configuration of an existing inventory entry. The device is identified via host_or_url. Port, security policy, and security mode are automatically taken from the inventory entry.
Authentication: X-API-Key required
Request
The path parameter host_or_url replaces the request body. It can be an IP address, a hostname, or a full OPC UA URL:
# Variant 1: IP address
curl -X GET "http://localhost:5000/gds/monitor/crt/192.168.1.10" \
-H "X-API-Key: your-api-key"
# Variant 2: Hostname
curl -X GET "http://localhost:5000/gds/monitor/crt/plc-line1.example.com" \
-H "X-API-Key: your-api-key"
# Variant 3: Full OPC UA URL
curl -X GET "http://localhost:5000/gds/monitor/crt/opc.tcp://192.168.1.10:4840" \
-H "X-API-Key: your-api-key"
Path Parameters
| Parameter | Description |
|---|---|
host_or_url | IP address, hostname, or full OPC UA URL (opc.tcp://host:port) of an existing inventory entry |
Response 200
Identical format to POST /gds/monitor/crt. The x509 and fingerprint fields are not included, as these are only returned upon explicit request in the POST body.
{
"idial_time": "2026-03-30T10:15:00+00:00",
"url": "opc.tcp://192.168.1.10:4840",
"security_policy": 8,
"security_mode": 2
}
POST /gds/inventory/crt
Reads detailed certificate information from a GDS-capable OPC UA device and stores it in the inventory. The response contains full certificate metadata: fingerprints, subject/issuer DN, validity period, extensions, public key information, SAN, and CRL distribution points.
Authentication: X-API-Key required
Request Body
Identical to POST /gds/monitor/crt (fields server, port, and connection parameters).
Response 200
{
"name": "PLC Line 1",
"url": "opc.tcp://192.168.1.10:4840",
"server": "192.168.1.10",
"port": 4840,
"device_status": 1,
"certificate": {
"certificate_from_db": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
"certificate_der_base64": "MIID...",
"sha1_thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
"sha256_spki": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
"sha1_spki": "A94A8FE5CCB19BA61C4C0873D391E987982FBBD3",
"md5_spki": "098F6BCD4621D373CADE4E832627B4F6",
"subject_dn": "CN=plc-line1,O=ExampleCorp,C=DE",
"subject_cn": "plc-line1",
"subject_o": "ExampleCorp",
"issuer_dn": "CN=Issuing CA,O=ExampleCorp,C=DE",
"serial_number": "1A2B3C4D",
"serial_number_decimal": "438954061",
"valid_from": "2025-01-01T00:00:00",
"valid_to": "2026-01-01T00:00:00",
"remaining_days": 276,
"self_signed": false,
"x509_version": 3,
"key_type": "RSA",
"authority_key_identifier": "keyid:AB:CD:EF:...",
"authority_key_identifier_hex": "ABCDEF...",
"authority_key_identifier_dirname": null,
"authority_key_identifier_serial_number": null,
"basic_constraints_ca": false,
"basic_constraints_pathlen": null,
"subject_key_identifier": "A1:B2:C3:...",
"subject_key_identifier_hex": "A1B2C3...",
"key_usage": ["digitalSignature", "keyEncipherment"],
"extended_key_usage": ["serverAuth"],
"public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
"public_key_type": "RSA",
"public_key_size": 2048,
"public_key_xml": "<RSAKeyValue>...</RSAKeyValue>",
"san": {"dns": ["plc-line1.example.com"], "ip": ["192.168.1.10"]},
"cdp": ["http://crl.example.com/issuing.crl"]
},
"certificate_revocation": {
"id": 1,
"name": "not_revoked",
"description": "certificate was checked against a CRL and is not revoked"
},
"certificate_revocation_reason": null
}
Response Fields
Top level
| Field | Type | Description |
|---|---|---|
name | string | null | Display name of the inventory entry |
url | string | Full OPC UA URL (opc.tcp://host:port) |
server | string | IP address or FQDN of the device |
port | integer | OPC UA port |
device_status | integer | null | Operational status per Parameter Reference |
certificate | object | Parsed certificate information (see below) |
certificate_revocation | object | CRL check status (fields id, name, description) |
certificate_revocation_reason | object | null | Revocation reason per RFC 5280, null if not revoked or self-signed |
certificate object
| Field | Type | Description |
|---|---|---|
certificate_from_db | string | Raw PEM certificate exactly as stored in the IDIAL database |
certificate_der_base64 | string | Certificate DER-encoded as Base64 |
sha1_thumbprint | string | null | SHA-1 fingerprint of the certificate (hex, without separators) |
sha256_spki | string | null | SHA-256 hash of the Subject Public Key Info (SPKI) |
sha1_spki | string | null | SHA-1 hash of the Subject Public Key Info (SPKI) |
md5_spki | string | null | MD5 hash of the Subject Public Key Info (SPKI) |
subject_dn | string | null | Full Subject Distinguished Name |
subject_cn | string | null | Common Name from the subject DN |
subject_o | string | null | Organization from the subject DN |
issuer_dn | string | null | Full Issuer Distinguished Name |
serial_number | string | null | Certificate serial number (hexadecimal) |
serial_number_decimal | string | null | Certificate serial number (decimal) |
valid_from | string | null | Validity start (ISO 8601) |
valid_to | string | null | Expiry date (ISO 8601) |
remaining_days | integer | null | Remaining validity days from today |
self_signed | boolean | true if issuer and subject are identical |
x509_version | integer | null | X.509 version (in practice always 3) |
key_type | string | null | Key type, e.g., "RSA" or "EC" |
authority_key_identifier | string | null | Authority Key Identifier (human-readable form) |
authority_key_identifier_hex | string | null | Authority Key Identifier (hex) |
authority_key_identifier_dirname | string | null | CA directory name from the AKI extension, if present |
authority_key_identifier_serial_number | string | null | CA serial number from the AKI extension, if present |
basic_constraints_ca | boolean | true if the certificate is marked as a CA certificate |
basic_constraints_pathlen | integer | null | Maximum chain length (CA certificates only) |
subject_key_identifier | string | null | Subject Key Identifier (human-readable form) |
subject_key_identifier_hex | string | null | Subject Key Identifier (hex) |
key_usage | string[] | List of key usage values, e.g., ["digitalSignature", "keyEncipherment"] |
extended_key_usage | string[] | List of extended key usage values, e.g., ["serverAuth"] |
public_key_pem | string | null | Public key in PEM format |
public_key_type | string | null | Key type of the public key, e.g., "RSA" |
public_key_size | integer | null | Key length in bits, e.g., 2048 |
public_key_xml | string | null | Public key in XML format (for Windows compatibility) |
san | object | Subject Alternative Names grouped by type (e.g., {"dns": [...], "ip": [...]}) |
cdp | string[] | CRL Distribution Point URIs |
GET /gds/inventory/crt/{host_or_url}
Equivalent to POST /gds/inventory/crt, but reads the certificate stored in the IDIAL database for the device — without establishing a live connection. The device is identified via host_or_url.
Authentication: X-API-Key required
Request
# Variant 1: IP address
curl -X GET "http://localhost:5000/gds/inventory/crt/192.168.1.10" \
-H "X-API-Key: your-api-key"
# Variant 2: Full OPC UA URL
curl -X GET "http://localhost:5000/gds/inventory/crt/opc.tcp://192.168.1.10:4840" \
-H "X-API-Key: your-api-key"
Path Parameters
| Parameter | Description |
|---|---|
host_or_url | IP address, hostname, or full OPC UA URL (opc.tcp://host:port) of an existing inventory entry |
Response 200
Identical format to POST /gds/inventory/crt (see field tables above).
GET /gds/monitor/plc/{host_or_url}
Reads device-specific information from an OPC UA PLC: device revision, engineering revision, model, operating mode, and serial number. A live connection to the device is established. The inventory entry is identified via host_or_url.
Authentication: X-API-Key required
Request
# Variant 1: IP address
curl -X GET "http://localhost:5000/gds/monitor/plc/192.168.1.10" \
-H "X-API-Key: your-api-key"
# Variant 2: Full OPC UA URL
curl -X GET "http://localhost:5000/gds/monitor/plc/opc.tcp://192.168.1.10:4840" \
-H "X-API-Key: your-api-key"
Path Parameters
| Parameter | Description |
|---|---|
host_or_url | IP address, hostname, or full OPC UA URL (opc.tcp://host:port) of an existing inventory entry |
Response 200
{
"url": "opc.tcp://192.168.1.10:4840",
"device_revision": "V1.0",
"engineering_revision": "V1.2",
"model": "S7-1500",
"operating_mode": "RUN",
"serial_number": "S7-15000001"
}
Response Fields
| Field | Type | Description |
|---|---|---|
url | string | Full OPC UA URL of the device (opc.tcp://host:port) |
device_revision | string | null | Hardware revision identifier of the device as reported by the device |
engineering_revision | string | null | Engineering tool revision identifier as reported by the device |
model | string | null | Device model designation, e.g., "S7-1500" |
operating_mode | string | null | Current operating mode of the device, e.g., "RUN", "STOP", or "STARTUP" |
serial_number | string | null | Serial number of the device |
The fields device_revision, engineering_revision, model, operating_mode, and serial_number are device-dependent. If a device does not report a value, null is returned.
POST /gds/monitor/trustlist
Reads the trust list of a GDS-capable OPC UA server. Depending on the trustlist bitmask, trusted certificates, trusted CRLs, issuer certificates, and issuer CRLs are returned.
Authentication: X-API-Key required
Request Body
{
"server": "192.168.1.10",
"port": 4840,
"security_policy": 8,
"security_mode": 2,
"trustlist": 15,
"mask": false
}
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
server | string | Yes | — | IP address or FQDN of the OPC UA server. The server value is the unique identifier of the endpoint within the IDIAL database. |
port | integer | No | 4840 | OPC UA port. If not provided, the default port 4840 is used. |
security_policy | integer | No | 31 | See Parameter Reference |
security_mode | integer | No | 0 | See Parameter Reference |
trustlist | integer | No | 15 | Bitmask: which trust list components to retrieve. The specified value can be a combination of multiple allowed values, which IDIAL computes to determine the desired information. Default: 15 (all components). Allowed values: 0 = none, 1 = TrustedCertificates, 2 = TrustedCrls, 4 = IssuerCertificates, 8 = IssuerCrls. Example: 15 = all components (1+2+4+8). See Parameter Reference. |
mask | boolean | No | false | Controls the OPC UA method used for trust list access. Default: false (uses the standard Open() method). If true: Uses OpenWithMasks() for extended access control. |
Response 200
{
"success": true,
"execution": "TrustedCertificates: 3 certificate(s) read\nTrustedCrls: 1 CRL(s) read\n...",
"error": "",
"result": {
"TrustedCertificates": ["MIID...", "MIID..."],
"TrustedCrls": ["MIIB..."],
"IssuerCertificates": ["MIID..."],
"IssuerCrls": []
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
success | boolean | true if the trust list retrieval was successful |
execution | string | Output text of the executed trust list script (status messages) |
error | string | Error message if success: false, otherwise empty |
result | object | null | Trust list contents split by component (see below) |
result.TrustedCertificates | string[] | PEM-encoded trusted certificates |
result.TrustedCrls | string[] | PEM-encoded trusted CRLs |
result.IssuerCertificates | string[] | PEM-encoded issuer certificates |
result.IssuerCrls | string[] | PEM-encoded issuer CRLs |
result contains only the components requested via the trustlist bitmask. Unrequested components are absent from the object. If no entries exist, an empty array is returned.
Response Codes
| Code | Description |
|---|---|
200 | Trust list contents with the requested components |
400 | Invalid input field |
500 | {"error": "string"} |
GET /gds/monitor/trustlist/{host_or_url}
Equivalent to POST /gds/monitor/trustlist, but uses an existing inventory entry. All trust list components are retrieved (trustlist: 15).
Authentication: X-API-Key required
Request
# Variant 1: IP address
curl -X GET "http://localhost:5000/gds/monitor/trustlist/192.168.1.10" \
-H "X-API-Key: your-api-key"
# Variant 2: Full OPC UA URL
curl -X GET "http://localhost:5000/gds/monitor/trustlist/opc.tcp://192.168.1.10:4840" \
-H "X-API-Key: your-api-key"
Path Parameters
| Parameter | Description |
|---|---|
host_or_url | IP address, hostname, or full OPC UA URL (opc.tcp://host:port) of an existing inventory entry |
Response 200
Identical format to POST /gds/monitor/trustlist. All components are always retrieved (trustlist: 15).
DELETE /gds/monitor/trustlist
Removes a specific certificate from the trust list of a remote GDS OPC UA server. The certificate to be deleted is identified by its SHA-1 thumbprint or alternatively by a certificate file path from which IDIAL derives the thumbprint.
Authentication: X-API-Key required
Request Body
{
"server": "192.168.1.10",
"port": 4840,
"security_policy": 8,
"security_mode": 2,
"trustlist": 1,
"thumbprint": "A1B2C3D4E5F6789012345678"
}
Additional fields compared to POST /gds/monitor/trustlist:
| Field | Type | Description |
|---|---|---|
thumbprint | string | SHA-1 thumbprint (hex, with or without 0x prefix) |
certificate | string | Path to the certificate file from which the thumbprint is derived |
Examples
# Read a device's certificate in real time
curl -X POST http://localhost:5000/gds/monitor/crt \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"server": "192.168.1.10", "port": 4840, "fingerprint": "sha1"}'
# Retrieve trust list via inventory entry
curl -X GET "http://localhost:5000/gds/monitor/trustlist/192.168.1.10" \
-H "X-API-Key: your-api-key"