Managing a Device's Trust List

A device's OPC UA trust list contains all certificates and Certificate Revocation Lists (CRLs) that the device trusts. IDIAL can retrieve this list directly from the device — via the device's GDS service. This guide describes how to retrieve and interpret the trust list.

note

To retrieve the trust list, the device must provide an OPC UA GDS service (Global Discovery Service) and the IDIAL server must possess the necessary credentials to authenticate at the GDS.

Prerequisites

• The device is reachable over the network
• GDS admin credentials are available (or are stored in the inventory entry)
• An API key is available

Step 1 — Retrieve the full trust list

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

The value 15 is a bitmask that requests all four components simultaneously.

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)
security_policy	integer	31	Bitmask of allowed Security Policies (see Parameter Reference)
security_mode	integer	0	Security Mode: 0=None, 1=Sign, 2=SignAndEncrypt
trustlist	integer	15	Bitmask of components to retrieve (see below)
mask	boolean	false	Use OpenWithMasks() instead of Open()
username	string	—	GDS admin username
password	string	—	GDS admin password

Bitmask values for trustlist

Bit	Value	Component	Description
0	1	TrustedCertificates	Certificates the device trusts directly
1	2	TrustedCrls	CRLs for the trusted certificates
2	4	IssuerCertificates	CA certificates of the issuers
3	8	IssuerCrls	CRLs for the issuer certificates

Combinations: 3 = TrustedCertificates + TrustedCrls, 12 = IssuerCertificates + IssuerCrls, 15 = all.

Step 2 — Interpret the response

{
  "success": true,
  "execution": "TrustList operation completed successfully",
  "error": "",
  "gds_time": "2026-03-30T14:22:05.000Z",
  "gds_maxtrustlistsize": 65536,
  "result": {
    "TrustedCertificates": [
      "MIIBxTCCAW+gAwIBAgIUABC...base64...==",
      "MIIBxTCCAW+gAwIBAgIUDEF...base64...=="
    ],
    "TrustedCrls": [
      "MIIBGzANBgkqhkiG9w0BAQE...base64...=="
    ],
    "IssuerCertificates": [
      "MIICpDCCAYwCCQDhyFf...base64...=="
    ],
    "IssuerCrls": []
  }
}

Response fields

Field	Description
success	true if the retrieval was successful
execution	Status message of the operation
error	Error message if success: false, otherwise empty
gds_time	ISO 8601 timestamp of the retrieval from the GDS device
gds_maxtrustlistsize	Maximum trust list size in bytes
result.TrustedCertificates	Array of PEM-encoded X.509 certificates (Base64)
result.TrustedCrls	Array of PEM-encoded CRLs (Base64)
result.IssuerCertificates	Array of PEM-encoded CA certificates (Base64)
result.IssuerCrls	Array of PEM-encoded CRLs for issuers

What the entries mean

• TrustedCertificates: Certificates the device trusts directly. Clients connecting to this device must present one of these certificates or a certificate issued by an IssuerCertificate.
• TrustedCrls: Revocation lists for the certificates in TrustedCertificates. The device checks these lists to reject revoked certificates.
• IssuerCertificates: CA certificates needed to verify certificate chains. The device trusts certificates issued by these CAs.
• IssuerCrls: Revocation lists for the CA certificates in IssuerCertificates.

Step 3 — Decode a certificate from Base64 (optional)

The entries in result.* are DER-encoded X.509 certificates as Base64 strings. For analysis:

echo "MIIBxTCCAW+gAwIBAgIUABC...==" | base64 -d | openssl x509 -inform DER -text -noout

Summary

POST /gds/monitor/trustlist   → retrieve trust list
trustlist bitmask             → select components (1/2/4/8 or combined)
result.*                      → PEM-encoded certificates and CRLs

Next steps

• Renewing a certificate manually — renew certificate after trust list analysis
• POST /gds/monitor/trustlist — API Reference

Troubleshooting

Symptom	Possible cause	Solution
"success": false	Device unreachable or no GDS service	Check IP/port, verify GDS service on device
Authentication error	GDS credentials missing or incorrect	Pass username/password directly in the request
Empty arrays in result	No entries in the requested component	Use a different bitmask combination, check GDS configuration on device
gds_maxtrustlistsize exceeded	Trust list too large	Remove expired certificates from the device's trust list