Integrity check for automation projects

Available from firmware release 2022.6 with a corresponding PLCnext Engineer release

In addition to other measures of Industrial cyber security with PLCnext Technology, the integrity of the PLCnext Engineer project on the PLCnext Control device can be checked before loading. This way you would detect any tampering with your data en route or on the controller.

From ﬁrmware and PLCnext Engineer releases 2022.6, project integrity is checked by means of hash value veriﬁcation for the unaltered state of binary data (see Project integrity check below).
From ﬁrmware and PLCnext Engineer releases 2025.0, this feature has been extended by two levels of signature verification (see Extended project integrity check) .

Note: While this feature detects tampering of binaries and configuration files at the controller, there is another feature which detects tampering of the project sources at the engineering PC. For details to the latter feature, see Project integrity check.

Project integrity check

Available from firmware releases 2022.6 to 2024.6 with corresponding PLCnext Engineer releases

In PLCnext Engineer projects basing on a FDCML for firmware releases from 2022.6, the project integrity check by means of hash values is enabled by default. This feature encompasses the following aspects of the project:

Code, including PLCnext Engineer libraries, binary code from Simulink and C++ libraries
Configuration files, e.g. for fieldbuses, ESM, OPC UA®
PLCnext Engineer HMI files

The hash value is sent to the controller together with the project files. The check takes place on the controller during the Load() transition from PlcState.Ready to PlcState.Stop. On the controller the hash value is also calculated and compared with those of PLCnext Engineer. If different, changes during transmission from PLCnext Engineer to the controller are detected.

You can configure the following modes in the configuration file:

Disabled: No check is performed. The PLCnext Engineer project is loaded in any case and the controller is started.
Warning: The PLCnext Engineer project is checked. In case of an integrity breach the project continues loading and the controller changes to PlcState.Run. A notification is sent. This mode is enabled by default, but when the Security Profile is activated, the mode is switched to Error.
Error: The PLCnext Engineer project is checked. In case of an integrity breach the project is prevented to be loaded and the controller remains in PlcState.Ready. A notification is sent. This mode is enabled by default if the Security Profile is active.

Note: If the integrity check is active (i.e., the IntegrityCheck mode is set to Warning or Error), any project is checked while loading. This means that an integrity breach is also detected for projects on the controller that have been created with a PLCnext Engineer version prior to 2022.6 and lacking the hash value.
In that case a notification will report: Manifest file'PCWE.manifest.config' does not exist.

Configuration

The response to an integrity breach detected by the firmware can be configured via the configuration file /opt/plcnext/config/Plc/Domain/ProjectManager.plc.config. Up to firmware release 2024.6, this file can be edited by the Linux® admin user (root rights are not necessary). From firmware release 2025.0, the Web‑based Management (WBM 2) provides a dedicated page for configuration (see Extended project integrity check).

By default, the configuration file is structured as follows (showing the default settings):

<?xml version="1.0" encoding="UTF-8"?>
<PlcDomainConfigurationDocument
   xmlns="http://www.phoenixcontact.com/schema/plcdomainconfig"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.phoenixcontact.com/schema/plcdomainconfig"
   schemaVersion="1.0">
   
   <ProjectManagerConfig>
     <IntegrityCheck mode="Warning" />
     <!-- Possible modes: "Disabled", "Warning", "Error" -->
   </ProjectManagerConfig>
     
</PlcDomainConfigurationDocument>

This example shows the project integrity check configured for the Error mode:

<?xml version="1.0" encoding="UTF-8"?>
<PlcDomainConfigurationDocument
   xmlns="http://www.phoenixcontact.com/schema/plcdomainconfig"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.phoenixcontact.com/schema/plcdomainconfig"
   schemaVersion="1.0">
   
   <ProjectManagerConfig>
     <IntegrityCheck mode="Error" />
     <!-- Possible modes: "Disabled", "Warning", "Error" -->
   </ProjectManagerConfig>
     
</PlcDomainConfigurationDocument>

Detected project integrity breach

When a project integrity breach is detected, a security notification is written to the security log providing details (Security.Arp.Plc.Domain.PlcManager.ProjectIntegrityFail).

Extended project integrity check

Available from firmware release 2025.0 with a corresponding PLCnext Engineer release

The project integrity check is extended by these features:

Two levels of signature verification are available.
The hash value check can be based on the ASiCManifest file.
The checking now encompasses programs and sources for both standard and safety-related PLCnext Engineer projects that are downloaded to the controller.
The configuration can be done via WBM 2 (which is recommended).

The integrity check on the controller side works as follows:

Every time you're changing something in the automation project in PLCnext Engineer the hash values and signature that depend on those hash values are renewed. The changes are transferred to the controller together with the project data.

On PLCnext Control devices with firmware release ≥2025.0 this feature is an option but enabled by default on the basic level. Checking the project integrity is based on either the hash value of the project package or on a digital signature derived from hash values of the data.

Applying the signature (if chosen, see level of signature verification) can be done by means of PLCnext Engineer ≥2025.0. Managing this feature on the controller is done via the Web-based Management 2 (WBM 2) from firmware release ≥2025.0.

Note: As of now, this extended integrity check is integrated in PLCnext Engineer only for project downloads by means of the Write and start project command. Other means to distribute an automation project together with the signature, such as downloading it to the controller from the PLCnext Store, via WBM 2 or the Device and Update Management (DaUM), will be implemented in PLCnext Engineer later. Manual handling is possible but not recommended.

Prerequisites

Before starting the setup procedure, decide how you want to proceed in these regards:

Which base for timestamps?

Two timestamps can be relevant during the integrity check:

One timestamp is set during signing the automation project on the engineering computer; the time derives from the system time of the engineering computer.
Another timestamp is set when the signed project was seen by the Time Stamp Authority (TSA) server; the time derives from the system time of the TSA server and is set by PLCnext Engineer.

Before implementing the integrity check feature with a Signing certificate, setting up a time server is recommended to make sure the time setting on the engineering computer is always accurate.

Tip: Both the TSA server and the NTP server are available as external resources; e.g. the digicert® provides a trusted RFC3161 timestamp server under the URL http://timestamp.digicert.com, and the TSA certificate chain for downloading. On the contrary, both server types can be set up on premise to avoid security issues of accessing a server via the Internet.

Which level of signature verification?

Basic level: only hash value verification (this is the default setting)
For verifying that the computed hash value of the project package file is still the same, no Signing certificate is necessary. See Checking project integrity for more details.

Advanced level: signature verification
The root CA certificate from the certificate chain in the Signing certificate must be present in the Trust Store named Code Signing on the PLCnext Control device.

Highest level: signature verification with long-term signatures
The root CA certificate from the certificate chain in the Signing certificate must be present in the Trust Store named Code Signing on the PLCnext Control device, and in addition only signatures that contain a signed timestamp are accepted.

For that, the Time Stamping Authority (TSA) calculates another hash value from the project signature and the TSA's current timestamp. For this level of verification, the corresponding root CA certificate of the TSA must also be present in the Trust Store named Code Signing on the controller, but the controller doesn't need access to the TSA server.

Note: The certificates in this context must meet the requirements for generating ASiC-E containers, with signatures according to CAdES in RFC 5652 Cryptographic Message Syntax (CMS). See the respective standards for electronic signatures of the European Telecommunications Standards Institute (ETSI).
Especially the directives for code-signing certificates must be met, as described by the CA/Browser Forum in Baseline Requirements for the Issuance and Management of Trusted Code Signing Certificates, Version 3.0.0, Section 7 CERTIFICATE, CRL, AND OCSP PROFILES.

Which reaction to a suspected integrity breach?

Load nevertheless and just warn:
The project continues loading and the PLC goes into PlcState.Run, a  Warning notification is displayed (this is the default setting).
Don't load and throw an error:
The project stops loading and the PLC remains in PlcState.Ready, an  Error notification is displayed. This way, the binary data wouldn't even be loaded into the memory.

Setting up the project integrity with signature check

Prepare a signing certificate
1. Generate a certificate via an official Public Key Infrastructure (PKI); you'll need the path to the .pem file later in step 2.
2. Save the certificate chain and private key as a PKCS#12 container file (suffix *.pfx or *.p12) which is secured by a password. You'll need the path to this certificate file and its password at the last task in step 3.
3. From the PKCS#12 file, extract the root CA certficate (show hintshow hint) and save that .pem file separately.
  
  Tip: Extracting parts from the PKCS#12 container can be done by means of the XCA tool,
  or with an openSSL command, e.g. openssl pkcs12 -nokeys -in store.pfx -info > chain.pem.
Prepare the controller
1. Enter the Web‑based Management of the controller; see WBM2.
2. Optional, but recommended: Open the Configuration → Date & Time page and set up a time server for the controller; see System time.
3. Open the Security → Certificate management page:
  1. By means of the Certificate management WBM 2 page, download the .pem file of the root CA certificate into the Code Signing Trust Store on the controller.
  2. If you chose signature verification with long-term signatures, then put the .pem file of the TSA root CA certificate into the Code Signing Trust Store on the controller, too.
4. Open the Security → Project integrity page and set up the Project integrity check:
  1. At Integrity check mode, adapt the reaction to a suspected integrity breach to your needs (details see Prerequisites).
  2. At Signature verification, adapt the verification level to your needs (details see Prerequisites).
  3. Save & apply the changes made on this WBM 2 page.
    ↪ From there, the device cannot receive an automation project out of PLCnext Engineer until the tasks in step 3 are done.
Prepare the automation project
1. In PLCnext Engineer, open (or create) a project from a template ≥2025.0 for your controller.
2. Double-click the controller node to show the editor in the center panel.
3. Click the Package Signing editor tab (show hintshow hint) and perform the steps for Creating a digital signature and add the time server settings.
  
  Note: If the Package Signing editor tab doesn't show then your PLCnext Engineer project is not generated from a ≥2025.0 template. For updating a project to the current template, proceed as if you were replacing a device.
Use the integrity check continuously with your automation project
1. When opening the PLCnext Engineer project on your computer you'll always have to enter the password for the certificate container.
2. After changing something in your automation project in PLCnext Engineer, save all changes.
3. Connect to the controller and issue a Write and start project command.
  ↪ The project with the current timestamp is signed with the Signing certificate implemented in the former steps.
  ↪ The project is transmitted to the controller and the integrity of the binary data is checked by means of the certificate.
  ↪ If something suspicious has happened then an error or at least a warning is displayed.

Note: If you later make changes to the settings for the integrity check on the controller, then a project change must also take place so that the signature is renewed, too.