Managing Certificates

Manual for the Certificates page: the Trusted, Own and Revoked Certificates of an installation and the certificates a central system delivers to its Edge Nodes.

Updated 14 min read
On this page (7 sections)
  1. Overview
  2. Trusted Certificates
  3. Own Certificates
  4. Revoked Certificates
  5. Certificates Delivered to Edge Nodes
  6. HTTPS in a Docker Container
  7. Config API and MCP

The Certificates page holds the certificates an EnvisionSCADA installation uses for its encrypted connections. Open it from the side menu with Configuration > Certificates. The page is available to Administrators only.

The page contains three lists:

  • Trusted Certificates: public certificates this installation trusts in addition to the certificates of the operating system.
  • Revoked Certificates: certificates this installation refuses although they are valid and issued by a trusted authority.
  • Own Certificates: certificates with their private key that this installation presents to others.

This article describes how to manage existing certificates. To create a certificate authority or a server certificate with the Certificate Generator, see the Certificates article.

The Trusted Certificates and the Revoked Certificates are configuration: they are stored in the project and replicated to the standby node of a redundant pair, and they can only be changed on the primary node. The Own Certificates are kept per node, outside the project.

Each list has a Source column. This installation marks an entry made on this installation; Central marks an entry received from the central system. On a central system, the Distribute to Edge Nodes column sends an entry to every Edge Node at its next check-in.

Trusted Certificates

A Trusted Certificate is the root or intermediate certificate of a plant certificate authority, or a self-signed server certificate. Add one when EnvisionSCADA connects to a server whose certificate is signed by an authority the operating system does not know, for example on a Docker node, which only trusts the authorities of the container.

The Trusted Certificates are used for the link of an Edge Node to its central system, the redundancy partner, MQTT Clients and MQTT Publishers, Active Directory, S7Plus devices in Trusted CA mode, Kafka and OPC UA. A server certificate is accepted when the operating system accepts it, or when the only objection is the chain and the chain ends at a Trusted Certificate. A certificate that is not issued for the address of the server is never accepted.

The MQTT Broker also uses this list for its client certificate login. A broker user with Authentication set to Certificate, or Certificate and password, logs in on the TLS port with a client certificate. The broker accepts that certificate only when it is within its validity dates and is in the Trusted Certificates or issued by an authority in them. The authorities of the operating system do not count for the broker. See the MQTT Broker article.

ColumnDescription
NameName of the entry, unique on this installation.
SubjectSubject of the first certificate of the entry. When the entry holds more certificates, for example a root and an intermediate certificate, their number follows as (+1).
IssuerIssuer of the first certificate.
Valid UntilExpiry date, with the days left or Expired. Shows Revoked when the certificate is in the Revoked Certificates: it no longer counts as trusted.
SourceThis installation, or Central for an entry received from the central system. An entry from Central cannot be deleted or distributed further.
Distribute to Edge NodesOn a central system: sends the certificate to every Edge Node at its check-in, so the Edge Nodes trust what this authority signs. Off for a new entry.
ActionsDelete removes the entry after a confirmation.

Press Add above the list to open the Add Trusted Certificate dialog. Select a file or paste the PEM text, enter a Name, and press Create. A binary (DER) .crt or .cer file is converted to PEM text when it is selected.

An entry cannot be edited. To replace a certificate, delete the entry and add the new certificate. A deleted entry no longer counts from the next connection on. The link to the central system and the redundancy partner channel renew their connections every 5 minutes, so an open connection keeps working for at most that long.

FieldDescriptionExample
NameName of the entry. Required, at most 100 characters.PlantRootCA
Certificate File (.crt, .cer, .pem)The certificate file. Fills Certificate (PEM), and Name when it is empty.
Certificate (PEM)The public certificate as PEM text. Several certificates can follow each other, for example a root and an intermediate certificate. A private key is refused.-----BEGIN CERTIFICATE-----
A connection with Allow Untrusted Certificates enabled checks no certificate at all, and therefore ignores the Trusted Certificates and the Revoked Certificates.

Own Certificates

An Own Certificate is a certificate with its private key that this installation presents to others. It is used as:

  • The client certificate of an MQTT Client, MQTT Publisher, Kafka or OPC UA device.
  • The server certificate of the MQTT Broker and the OPC UA Server.
  • The Client Certificate Name of Active Directory, presented to the LDAP server on an encrypted connection when it asks for a client certificate. See the Active Directory article.
  • The Client Certificate Name of a PostgreSQL or MySQL database connection, presented to a database server that asks for a client certificate. See the Database Connections article.
  • The HTTPS certificate of the web server in a Docker container.

A connection finds its certificate by the name of the entry or by its subject, as entered in the certificate name field of the connection. EnvisionSCADA also searches the Windows certificate store under Local Computer / Personal (Docker: the files in /app/certs/tls). When several certificates match, the one with a private key that is valid today and expires last is used.

ColumnDescription
NameName of the entry. A connection can name its certificate by this name.
SubjectSubject of the certificate. The number of intermediate certificates in the file follows as (+1).
Issued ForThe names the certificate is issued for.
Valid UntilExpiry date, with the days left or Expired. Shows Revoked when the certificate is in the Revoked Certificates.
SourceThis installation, or Central for a certificate delivered by the central system.
Use for HTTPSDocker only: the certificate the web server presents on HTTPS. On Windows the box is disabled, because the HTTPS certificate is set in IIS.
ActionsDelete removes the entry after a confirmation.

Press Add above the list to open the Add Own Certificate dialog. Select a .pfx or .p12 file and enter its Password, or paste the certificate and its private key as PEM text, then press Save. The password is used once to read the file and is not stored. The file may be at most 1 MB.

Adding a certificate under the name of an existing entry replaces it, which is how a certificate is renewed. Connections use the new certificate from their next connect; a running device or the MQTT Broker is not restarted for it.

FieldDescription
NameName of the entry. Filled from the file name when it is empty.
Certificate File (.pfx, .p12, .pem)File with the certificate and its private key.
PasswordPassword of the .pfx or .p12 file, or of an encrypted private key.
Use for HTTPSDocker only. Makes this the certificate of the web server. See HTTPS in a Docker Container below.
Certificate (PEM)The certificate and its private key as PEM text, as an alternative to a file.

The Own Certificates stay on the node: they are kept outside the project, are not replicated, exported or deployed, and each node of a redundant pair holds its own. They can therefore also be changed on a standby node. The page never shows the content or the private key of an Own Certificate. A certificate in the Revoked Certificates cannot be added.

Deleting an entry asks for a confirmation. Connections that present the certificate lose it at their next connect. An entry with Source Central is managed on the central system and cannot be deleted or replaced on the node.

EnvisionSCADA checks the expiry of the Own and Trusted Certificates every hour and publishes the result in the system variables below, so a project can raise an alarm on them. When a certificate expires within 30 days, a warning is written to the System Log once a day.

VariableDescription
SYSTEM.CertificateDaysLeftDays until the first Own or Trusted Certificate of this installation expires. Empty when the installation holds none.
SYSTEM.CertificateExpiringName of that certificate.

Revoked Certificates

A Revoked Certificate is refused by this installation although it is within its dates and issued by a trusted authority. Revoke a certificate that was replaced, or one whose private key may be in other hands, for example the certificate of a station that was stolen or decommissioned.

A revoked certificate is refused on the link to the central system, by the redundancy partner, by MQTT Clients and MQTT Publishers, by Active Directory and by S7Plus devices, and as client certificate on the MQTT Broker. It is also left out of the Trusted Certificates and the Own Certificates of the installation.

A revocation applies from the next connection. The one exception is the MQTT Broker: it closes the open sessions that logged in with the revoked certificate at once. The link to the central system and the redundancy partner channel keep an open connection for at most 5 minutes. An S7Plus, MQTT or Kafka connection that is open stays open until it reconnects.

Revoking the certificate of a certificate authority refuses every certificate it issued. For Kafka and OPC UA only a revoked authority is refused: a revoked server certificate under a trusted authority is still accepted there, because those connections check the chain themselves.

The MQTT Broker closes the session of a revoked client certificate at the moment the entry is saved. Every other connection refuses the certificate from its next connection.

An entry made from the certificate refuses that certificate, also a copy with the same issuer and serial number. A renewal has another serial number and is accepted. An entry made from a thumbprint alone refuses only the certificate with exactly that thumbprint and shows Thumbprint only in the Subject column. On a central system, a thumbprint of a certificate it no longer delivers to an Edge Node gives a complete entry, with the name, subject, issuer and expiry of that certificate.

ColumnDescription
NameName of the entry.
SubjectSubject of the revoked certificate, or Thumbprint only followed by the thumbprint for an entry made from a thumbprint.
ReasonWhy the certificate was revoked.
Revoked OnDate and time of the revocation, followed by the user who revoked it.
SourceThis installation, or Central for an entry received from the central system.
Distribute to Edge NodesOn a central system: sends the entry to every Edge Node at its check-in.
ActionsDelete removes the entry after a confirmation.

Press Add above the list to open the Revoke Certificate dialog. Select or paste the public certificate, or enter its SHA-1 thumbprint when the file is not at hand, for example a thumbprint taken from the MQTT broker log. Then press Revoke.

FieldDescriptionExample
NameName of the entry. Optional: when it is empty, the entry takes the common name of the certificate, or Thumbprint followed by the first 8 characters of the thumbprint. At most 100 characters.LS601
Certificate File (.crt, .cer, .pem)The public certificate file. Fills Certificate (PEM).
Certificate (PEM)The public certificate as PEM text. Exactly one certificate.-----BEGIN CERTIFICATE-----
Certificate ThumbprintSHA-1 thumbprint of the certificate: 40 hexadecimal characters. Required when no certificate is given. With a certificate it must be the thumbprint of that certificate.
ReasonFree text, at most 500 characters. Shown in the list and kept in the audit trail.Station decommissioned

EnvisionSCADA refuses the revocation of:

  • A certificate that is already revoked.
  • A certificate this installation uses itself: an Own Certificate, or on Windows a certificate with its private key in the certificate store of the computer.
  • The certificate of an authority that issued a certificate this installation uses itself. Every installation that holds the entry would refuse this installation from then on.
  • On a central system, a certificate it still delivers to an Edge Node. Replace or delete it on the Edge Nodes page first, then revoke it.

Deleting an entry asks for a confirmation. The certificate is accepted again from the next connection.

On a central system, an entry with Distribute to Edge Nodes is sent to every Edge Node at its check-in, so every Edge Node refuses the certificate. The box is set for a new entry. An Edge Node accepts the list only over an https link to the central system that does not allow untrusted certificates. It stores the entries with Source Central and removes the ones the central system no longer sends.

An Edge Node can delete an entry received from the central system. This is the way back when a revocation cut the Edge Node off from the central system. The entry returns with the next check-in for as long as the central system lists it.

Certificates Delivered to Edge Nodes

A central system can deliver certificates with their private key to its Edge Nodes, for example the certificates the IT department issued for each station. This is done on the Edge Nodes page of the central system, not on the Certificates page. For linking Edge Nodes to a central system, see the Fleet Deployment article.

The Certificates column of the Edge Nodes page is shown to Administrators. It shows Add for a node without certificates, or the number of certificates followed by Delivered or Pending. Click it to open the dialog of that node, titled Certificates for followed by the node name.

Field or columnDescription
StatusDelivered when the Edge Node holds the current set, Pending until its next check-in, or Pending on the standby node for the standby of a redundant Edge Node.
NameName of the certificate on the Edge Node. A connection on the Edge Node names its certificate by it.
SubjectSubject of the certificate, with the names it is issued for.
Valid UntilExpiry date, with the days left or Expired.
Use for HTTPSThe certificate the web server of a Docker Edge Node presents on HTTPS. When it is set here, the HTTPS certificate cannot be changed on the Edge Node.
Certificate File (.pfx, .p12, .pem)File with the certificate and its private key.
PasswordPassword of the file.

To add a certificate, select the Certificate File, enter its Name and Password, set Use for HTTPS when needed, and press Add. The Edge Node receives the certificate at its next check-in over an https Central URL and keeps it in its Own Certificates with Source Central. A certificate in the Revoked Certificates cannot be delivered.

To renew a certificate, add the new certificate under the same name: it replaces the previous one. To stop delivering a certificate, press Delete on its row. The Edge Node removes it at its next check-in.

A certificate that is replaced or deleted, and every certificate of an Edge Node that is deleted, is not revoked. It stays valid until it expires and can still be used, for example to log in to the MQTT Broker of the central system. After a replace or a delete, the dialog shows a note with the expiry date and the thumbprint of that certificate.

To refuse such a certificate sooner, revoke it in the Revoked Certificates of the central system by its thumbprint. The central system then takes the certificate it still holds for the entry, closes the MQTT Broker session that logged in with it, and sends the entry to every Edge Node. A certificate the central system still delivers cannot be revoked: replace or delete it first.

The certificate of a station that left the fleet, or was stolen, keeps working until it is revoked or expires. Revoke it in the Revoked Certificates.

The certificates the central system delivered and no longer delivers, that are still valid and not revoked, are listed as no longer delivered by the Config API and MCP (see below). A certificate leaves that list when it is revoked, has expired or is delivered again.

HTTPS in a Docker Container

In a Docker container, EnvisionSCADA can serve HTTPS with an Own Certificate. Set Use for HTTPS on one Own Certificate, or deliver one with Use for HTTPS from the central system. On Windows this does not apply: the HTTPS certificate is set in IIS.

When the container starts with a certificate marked Use for HTTPS, the web server also listens on HTTPS, on port 443 in the container or on the port in the environment variable ENVISION_HTTPS_PORT. Publish that port when the container is created. HTTP stays available on port 8080 and is not redirected to HTTPS.

Create the container with the HTTPS port published:
docker run -p 80:8080 -p 443:443 --name=envisionscada --restart=always --mount source=EnvisionVolume,target=/EnvisionVolume --mount source=EnvisionCerts,target=/app/certs sunforestsoftware/envisionscada:latest

The first certificate marked Use for HTTPS takes effect at the next start of the container. Until then the Own Certificates list shows a message that the web server starts listening on HTTPS at the next start. From then on, a renewed certificate is used from the next connection, without a restart.

Without a certificate marked Use for HTTPS, HTTPS can still be configured with the environment variables described in the Docker article.

Config API and MCP

The lists of the Certificates page are also available over the Config API, for Administrators, with the same checks and audit records as the page. Changes to the Trusted and Revoked Certificates are refused on a standby node.

PathMethodsDescription
/API/Config/TrustedCertificatesGET, POST, PUT, POST .../DeleteList, add and delete Trusted Certificates. PUT changes Distribute only.
/API/Config/RevokedCertificatesGET, POST, PUT, POST .../DeleteList, revoke (Certificate as PEM text or Thumbprint, optional Name and Reason, Distribute true by default) and delete entries. PUT changes Distribute only.
/API/Config/OwnCertificatesGET, POST, PUT .../Https, POST .../DeleteList, upload (multipart/form-data), delete and choose the HTTPS certificate. The answers never contain a certificate or a private key.
/API/Config/EdgeNodes/CertificatesGET, POST, PUT .../Https, POST .../DeleteOn a central system: the certificates per Edge Node and the list noLongerDelivered, upload, HTTPS choice and delete.

Over MCP, the Trusted Certificates and the Revoked Certificates are the config entities TrustedCertificates and RevokedCertificates. On a central system, the ManageFleetDeployment tool lists the certificates of the Edge Nodes, including the ones no longer delivered, with the action certificates, and changes them with setHttpsCertificate and deleteCertificates. Own Certificates and the upload of an Edge Node certificate have no MCP action, so a private key and its password never pass through an agent.

Something missing or wrong in this article? Contact us