Working with the SecurityFramework

For PLCnext Technology Toolchain 2025.0 and newer

The PLCnext Engineer software suite has a new security feature implemented from its 2025.0 releases which provides an option to check libraries for trusted signatures. This feature can also be addressed with libraries developed by means of an IDE: The PLCnext Technology Toolchain now contains the SecurityFramework to verify or add those signatures by means of PLCnext CLI, the Visual Studio® extension, or the Eclipse® add-in.

Installing the SecurityFramework

The SecurityFramework.Cli.exe is installed next to the plcncli.exe and is then available in a terminal session. 

Under Linux®, this tool is named SecurityFramework.Cli. With the Windows® installation, the path is set automatically. But when installing the Linux® version the path must be set manually (see Installing the toolchain).

For standalone use just call SecurityFramework.Cli.exe --help from the command line.

Adding a signature to a PLCnext Engineer library

Adding a signature by means of PLCnext CLI

Adding a signature to C++ PLCnext Engineer libraries

To add a signature via command line, the plcncli deploy command needs additional parameters:

1. Add the --sign parameter to activate signing in general.
2. Add a private key, a certificate and optionally a certificate chain from a signing authority.
   This can be done by either adding a PKCS#12 archive file with --pkcs12 <path-to-pkcs12>,
   or by providing all the separate parameters:
   • private key: --privatekey <path-to-privatekey.pem>
   • certificate: --signingcertificate <path-to-certficate.pem>(or the respective *.crt file)
   • (optional) certificate chain files: --certificatechain <path-to-certificate-chain.pem>,<path-to-further-files.pem> (or the respective *.crt files; further files are separated by comma)
3. (optional): Add a--password <your-private-key-password> parameter.
   If not set, the command line will request the password when required.
4. Either add --notimestamp if the signature can be just CAdES-B,
   or add --timestamp for a CAdES-T signature. 
   If you want to sign with CAdES-T, an additional timestamp configuration file is necessary and the --timestampconfiguration <path-to- timestampConfiguration.json> parameter needs to be set.

Adding a signature to C# PLCnext Engineer libraries

To add a signature via command line, the PLCnextSettings.xml file in the Properties directory needs additional parameters:

1. Set <Sign>true</Sign> to activate signing in general.
2. Add a private key, a certificate and optionally a certificate chain from a signing authority.
   This can be done by either adding a PKCS#12 archive file with <Pkcs12>certificate.pfx</Pkcs>,
   or by providing all the separate parameters:
   • private key: <PrivateKey>private.pem</PrivateKey>
   • certificate: <SigningCertificate>cert.pem</SigningCertficate>(or the respective *.crt file)
   • (optional) certificate chain files:
     <CertificateChain>
  <File>C:\Users\xxxx\yyyy\plcnext_firmware_signing_ca_development.crt</File>
  <File>C:\Users\xxxx\yyyy\plcnext_firmware_signing_ca_release.crt</File>
</CertificateChain>
3. Either add <NoTimestamp>true</NoTimestamp> if the signature can be just CAdES-B,
   or add <Timestamp>true</Timestamp> for a CAdES-T signature. 
   If you want to sign with CAdES-T, an additional timestamp configuration file is necessary, so add <TimestampConfiguration>timestampConfiguration.json</TimestampConfiguration>.
4. Start building in the command line via msbuild or dotnet msbuild. 
   For the password of the PKCS#12 file or the private key, there are two options:
   • Setting the value of the following environment variable engineeringlibrarybuilder_signing_pw_{0} where {0} is replaced with the project name and the value is the password.
   • Adding the password as a MSBuild parameter,  e. g. dotnet msbuild -p:EngineeringLibraryBuilderSigningPassword=mypassword
      

Adding a signature by means of Visual Studio®

• To configure the signing of a library in Visual Studio®, right click on your project in the Solution Explorer, select PLCnext Technology → Project Configuration.
  
• Switch to the Signing tab and make your choices:
  • Signing can be activated or deactivated; to use a signature with your project, tick the Sign Library mark.
  • There are two options to provide the necessary files:
    • The first option is a PKCS#12 Container, this contains a public and a private key to sign and a (derived) certificate of the issuing certificate authority.
    • The second option is to provide these files in the PEM format file by file.
  • Both the PKCS#12 container or the private key file in PEM format can be protected by a Password....
    This password is stored for the user per project and will be protected by the default Visual Studio® mechanism.
  • The last option is to add a timestamp configuration file for a CAdES-T signature.

Adding a signature by means of Eclipse®

• To configure the signing of a library in Eclipse®, open the project properties, select PLCnext Technology → PLCnext Signing. 
  
• Make your choices:
  • Signing can be activated or deactivated; to use a signature with your project, tick the Sign Library mark.
  • There are two options to provide the necessary files:
    • The first option is a PKCS#12 Container, this contains a public and a private key to sign and a (derived) certificate of the issuing certificate authority.
    • The second option is to provide the separate files in the PEM format.
  • Both the PKCS#12 container or the private key file in PEM format can be protected by a Password....
    This password is stored for the user per project and will be protected by the default Eclipse® mechanism.
  • Another option is to add a timestamp configuration file for a CAdES-T signature.

Verifying a signature by means of PLCnext CLI 

To verify a signature of a previously signed file (built by means of the PLCnext Technology Toolchain), proceed as follows.

• Unpack the *.pcwlx file and enter the resulting folder.
• Call this command (adapted to your storage locations, where necessary):

  SecurityFramework.Cli.exe verify --signature .\SignatureT.p7s --inputFile .\@IntegrityData@.xml --conformance Automatic --trustedCertificates .\codeSigningRootCa.pem

Note: In case of failures add -d to get detailed on-screen information, or -j log.txt to get a detailed logfile.

Reference

Certificate configuration for signing and verifying

To ensure proper validation of CA certificates and entity certificates, follow these guidelines:

CA Certificate Validation

• Certificate Version:
  • Ensure the certificate is X.509 version 3.
• Key Usage: The certificate must have the following key usages:
  • keyCertSign (Value 5): Allows the key to sign other certificates.
  • cRLSign (Value 6): Allows the key to sign certificate revocation lists (CRLs).
• Critical Key Usage: Ensure the Key Usage extension is marked as critical.
• Extended Key Usage Presence: If the certificate has the Extended Key Usage extension, validate against expected key purposes such as:
  • AnyExtendedKeyUsage (optional)
  • id_kp_serverAuth (optional)
  • id_kp_emailProtection (optional)
  • Depending on the usage of the certificate, check:
    • id_kp_codeSigning (mandatory) or
    • id_kp_timeStamping (mandatory)

Entity Certificate Validation

• Certificate Version: 
  • Ensure the certificate is X.509 version 3.
• Key Usage:
  • The certificate must have the key usage digitalSignature (Value 0); this allows the key to create digital signatures.
  • The certificate must not have the key usage keyCertSign (Value 5) or cRLSign (Value 6).
• Critical Key Usage: Ensure the key usage extension is marked as critical.
• Extended Key Usage: Validate against expected key purposes, such as:
  • AnyExtendedKeyUsage (optional)
  • id_kp_serverAuth (optional)
  • Depending on the usage of the certificate, check:
    • id_kp_codeSigning (mandatory) or
    • id_kp_timeStamping (mandatory)

Glossary & abbreviations for this topic 

• Signature Types:
  • CAdES-B: Basic signature that ensures the integrity and authenticity of the signed data. It does not include a timestamp.
  • CAdES-T: Timestamped signature that includes a timestamp from a trusted timestamp authority, providing proof that the signature existed at a specific time.
• Conformance: Defines the verification process based on signature type and timestamp. It includes:
  • Signed: Conformance check using the current UTC DateTime (CAdES-B signature Type).
  • SignedWithTimestamp: Conformance check using the provided timestamp (CAdES-T signature type).
  • Automatic: The system decides whether to use the provided timestamp's (if available), or defaults to the current UTC DateTime.
• Digest Algorithm: Cryptographic hash functions. Supported algorithms are:
  • SHA256
  • SHA384
  • SHA512
• Signature Algorithm: Digital signature methods. Supported algorithms are:
  • RSA
  • RSAPSS: an RSA variant with a probabilistic signature scheme
  • ECDSA: using elliptic curve cryptography

CAdES-T: Timestamp Configuration File 

The timestamp configuration file is needed, if the signature should be of type CAdES-T.

• All information necessary for accessing a time server must be put in this configuration file.
• The TimeStampServerCredentials are optional.
• The Proxy is optional, and – if not configured – the system defaults are used.

Example for a timestampConfiguration.json:

{
  "TimestampServer": "http://test.com",
  "TimeStampServerCredentials": {
    "UserName": "userName",
    "Password": "pwd",
    "Domain": "domain"
  },
  "Proxy": {
    "Address": "http://test.com:8080",
    "BypassOnLocal": true,
    "BypassList": [
      "bypass1",
      "bypass2"
    ],
    "Host": "test.com",
    "Port": 8080,
    "IsDefault": false,
    "ProxyCredentials": {
      "UserName": "proxyUserName",
      "Password": "proxyPwd",
      "Domain": "proxyDomain"
    }
  },
  "DigestAlgorithm": "SHA256",
  "SignatureAlgorithm": "Rsa"
}

 

 

• Published/reviewed: 2026-04-21  ✿  Revision 093 •