Encrypting and/or Signing the Boot Application

Know-how protection and copy protection of the download code and the boot application are best achieved with certificate-based encryption. Signing can be used to make sure that only applications from trusted sources are downloaded to the PLC.

If necessary, you can have a suitable certificate created immediately by the encryption wizard of the CODESYS Security Agent.

Note

Also the CODESYS project itself (i.e., the source code of the application) can also be encrypted with a certificate which only specific users receive. For more information about certificates, see: Certificates for CODESYS and PLC

Tip

For general information about certificates in the CODESYS Development System environment, see: Certificates for CODESYS and PLC

Encrypting an application with a certificate

To make sure that the boot application data is transferred in an unreadable form, you should encrypt it using certificate-based encryption. License-based encryption (dongle) is no longer recommended.

Note: In case you want to download the application to different controllers, you will need the suitable certificate for each controller.

Requirement: You have a project with an application.

In the device tree, select the application.
In the context menu, click Properties.
The Properties – <application name> dialog opens.
Click the Security tab.
For Protection, select the Encryption with certificates option.
Note
If the Enforce encryption of downloads, online changes and boot applications option is selected on the Users tab in the Security Level area of the Security Screen view, then the Encryption with certificates option is already permanently set.
The Certificates for encryption dialog field is enabled.
If you already have a valid certificate for application encryption on your computer, but this has not yet been entered in the table, then click the button. If you do not yet have a certificate, continue with Step 7.
The Certificate Selection dialog opens for selecting a certificate from the local Windows Certificate Store.
In the lower area, select a certificate and add it to the upper area by clicking the button. Click OK to confirm.
The certificate is shown in the Certificates for encryption field of the Security dialog.
If you do not yet have a valid certificate, then you can immediately generate one. In the Properties dialog of the application, click the Encryption Wizard button. In the Encryption Wizard dialog, click the Start button.
The Encryption Wizard prompts you to enter the Key length (bit) and Validity period (days).
Now the application can only be read by the controller with the specified certificate.
Note: To sign the boot application: In the Properties dialog, select the Digitally sign application code option and complete Steps 1–13 of the "Signing the boot application only with a certificate (no encryption)" instructions below.

Signing the boot application only with a certificate (no encryption)

When you select the Sign with certificate / Digitally sign application code option in the Properties of the application, the application is not encrypted, but the signature is used to ensure ownership and integrity.

Requirement: You need a certificate for digital signatures, which you assign to a user profile on the Users tab of the Security Screen. If you do not yet have such a certificate to select in the dialog, then first see the instructions: Configuring a certificate for the digital signature in a user profile. If you already have a suitable certificate, then complete the following steps:

On the User tab, double-click the certificate for the Digital Signature.
The Certificate dialog opens.
On the Details tab, click the Copy to file button.
The Certificate Export Wizard starts.
In the Export Private Key prompt, select the No, do not export the private key option.
For Export File Format, select the DER encoded binary X.509 (.CER) option.
In the next step, select a file name and the location for the certificate.
After the Finish step, a message displays that the export was successful.
After successful export to CODESYS, double-click the controller in the device tree to open the device editor and select the Files tab for the file transfer.
Select the Path cert/import in the right side of the Runtime dialog.
On the left side of the dialog for Host, select the path in the file system where you saved the exported certificate and selected the certificate.
Click the button.
The certificate is copied to the cert/import folder.
Click the PLC Shell tab.
In the input line of the tab, type in the cert-import trusted <file name.cer> command and press the Enter key. Note that the file name is specified with the .cer extension; otherwise the certificate is not imported successfully.
The certificate is created on the controller under Trusted. With this certificate, the controller can test the integrity of the boot application.
In the status bar, double-click the button to open the Security Screen view.
On the Users tab, make sure that the Enforce encryption of downloads, online changes, and boot applications protection option is not selected.
In the device tree, select the application object and in the context menu open the Properties – -application name- dialog and then Security tab. Select the Sign with certificate option. The Properties dialog opens. Alternatively, this dialog could also be accessed in the Security Screen view of the Project tab. Double-click there in the lower part of the window on the entry for the application.
Note: If the Enforce signing of downloads, online changes and boot applications option which applies to all projects is selected on the Security Screen view, then the Sign with certificate option is already selected.
Now the controller can check the integrity of the application. You will be able to transfer the application to the controller only if the certificate used for signing is valid.

Encrypting the download, online change, and boot application

If the CODESYS Security Agent is installed, then the Security Screen view includes an additional Devices tab. This allows for the configuration of certificates for the encrypted communication with controllers. In this case, see the help for CODESYS Security Agent: CODESYS Security Agent.

Alternative via the PLC Shell:

If the CODESYS Security Agent is not available to you, then you can proceed as follows by means of the PLC shell of the device editor:

In order to use certificates on the controller for the encryption of downloads, online changes, and boot applications, these certificates first have to be generated on the controller and loaded from the controller and installed in the Windows Certificate Store.

Requirement: You are connected to the controller.

In the device tree, double-click the controller to open the device editor , and select the PLC Shell tab.
The tab is displayed with an empty window. Below that is a command line.
Type a question mark (?) in the command line and press the Enter key.
All commands are listed in the display window.
In the command line, type in the cert-getapplist command.
All used certificates are listed with information about components and availability with certificates.
If no certificate is available for the CmpApp component, then type in the command cert-genselfsigned <number of the component in the applist>. If a suitable certificate is already available, then continue to Step 6.
Click the Log tab and then click the refresh button ().
The display shows whether or not the certificate was generated successfully.
On the PLC Shell tab, type in the command cert-getcertlist and press the Enter key.
Your own certificates are listed that can be used for encryption. The Number and Key usage(s) information is useful in the next step.
Number: The number is specified as a parameter in the next step.
Key usage(s): Data encryption: The certificate is on the controller for download, online change, and boot application.
Export the required certificate by typing in the command cert-export own 0 and press the Enter key. 0 is the Number of the certificate with Key usage(s):Data encryption.
The display shows that the certificate has been exported to a cert directory.
In the device editor, click the Files tab.
In the right part of the dialog in Runtime, click the refresh button ().
The list of files and directories is refreshed.
Open the cert folder in the list and then the export subfolder.
In the left part of the dialog in Host, open the directory where the certificate of the controller will be loaded.
In the right part of the dialog, select the certificate that you have exported and click .
The certificate is copied to the selected directory.
In the file explorer, go to the directory where the certificate was copied and double-click the certificate.
The Certificate dialog opens and shows the information about this certificate.
On the General tab, click Install Certificate.
The Certificate Import Wizard starts.
In the Certificate Storage dialog, for Certificate Import Wizard, select the Store all certificates in the following store option and then select the Controller Certificates folder.
The controller certificate is imported into the Windows Certificate Store in the Controller Certificates folder. Now the certificate is available for the encryption of boot applications, downloads, and online changes.
In the status bar, double-click the button to open the Security Screen.
If you want that downloads, online changes, and boot applications of your project are always encrypted, then select the Enforce encryption of downloads, online changes and boot applications option in the Security level group on the User tab.
Open the Project tab and double-click the application in the Encryption of boot application, download and online change area.
The properties dialog of the application opens.
Select the Security tab. In the Protection list box, select Encryption with certificates and click .
Note: If the Enforce encryption of downloads, online changes and boot applications option which applies to all projects is selected on the Security Screen, then Encryption with certificates is already selected.
In the Certificate Selection dialog, select the respective certificate from the Controller Certificates folder and click the button.
Click OK to confirm the dialog.
The certificate is displayed in the properties dialog.
Confirm the properties dialog of the application.
The certificate is shown on the Project tab of the Security Screen in the Encryption of boot application, download and online change group.
The boot application, download, and online change are encrypted.

Deleting a certificate for the encryption of boot application, download and, online change

Requirement: The CODESYS Security Agent add-on product is installed. A certificate with the information "Encrypted Application" is already installed on your computer.

In the Security Screen view, on the Project tab, in the bottom view, click the entry for the application.
The Properties dialog for the application opens with the Encryption tab.
For Encryption Technology, select Encryption with certificates. In the Certificates field, click the button.
In the Certificate Selection dialog, delete the certificate as described above.
Click OK to close the Certificate Selection dialog.
The certificate is no longer displayed in the Properties dialog.

Encryption with a dongle

Important

Encryption with a dongle is no longer classified as a secure encryption method.

Encryption by means of a certificates is recommended instead.

Requirements: You have a project with an application that you want to download to the controller as an encrypted boot application. A security key for license management is connected to your computer.

In the device tree, select the application.
In the context menu, click Properties.
The Properties – <application name> dialog opens.
Click the Security tab.
For Encryption Technology, select the Simple Encryption option and specify the Product code that you received from the hardware manufacturer for the controller. Depending on the controller, it is protected either by a security key (firm code is shown automatically) or by an integrated Wibu SD card, for example.
Click the Online → Login command and download the application.
If the matching security key and/or valid license is available, then you can download the application to the controller. By default, a boot application is automatically created at this time in the controller directory. The default setting is defined in the application Properties, in the Boot Application category.
Log back out, change the application, and log in.
You are prompted to perform an online change. The dialog provides the option of updating the boot application on the PLC. If the security key and license match, then you can log in. If not, then you receive a corresponding message.