Setting up driver signing

Create an OEM certificate level 2

TwinCAT objects generated from MATLAB^® or Simulink^® are based on a tmx driver (TwinCAT Module Executable), as are TwinCAT C++ objects. These drivers must be signed with a OEM certificate level 2 so that the driver can be loaded on the runtime PC during the TwinCAT runtime.

See the following links for detailed documentation on how to create an OEM certificate for driver signing:

The most important facts in brief:

You can create your own certificate. To do this, go to Visual Studio at:
Menu bar > TwinCAT > Software Protection...

You need an OEM certificate Crypto Version 2 (option: Sign TwinCAT C++ executables (*.tmx)).
You will be prompted to create a password for your certificate.

Drivers can also be created without signing and signed afterwards.
For testing purposes in the development phase, a non-countersigned certificate is sufficient.
Countersigned certificates can be ordered free of charge from Beckhoff (TC0008).

Set up OEM certificate level 2 under Software Protection

	TwinCAT Build 4026: Requirement for the setup dialog The following information on Software Protection only applies to TwinCAT 3.1 Build 4026. At least the TwinCAT Standard 4026.14 workload is required. If you are working with older versions, please continue reading “Setting up OEM certificate level 2 for driver signing without the Software Protection dialog” in the section below.

In the Software Protection interface (Menu bar > TwinCAT > Software Protection...) you can both create certificates (Create New...) and:

Set a certificate as the system-wide default certificate for signing tmx files (optional).
For each certificate, store the corresponding password for the logged-in Windows user (required).

The overview above contains two certificates as examples.

The first certificate "TestSign123" is not countersigned by Beckhoff, therefore it is classified as invalid in the status. Certificates that are not countersigned can still be used for signing. The target system must then be set into the test mode - see section Behavior of the TwinCAT runtime. The "TmxSignCertFaxxxBx" certificate, on the other hand, is countersigned and therefore classified as valid. Both certificates are suitable for signing tmx files, as can be seen under Permissions. In the "TMX Signing" column, "Default" indicates whether a certificate is set as the system-wide default certificate. The note "PW Stored" indicates that the password of the certificate is available/stored for the Windows user logged in.

Set certificate as system-wide default certificate (optional)

You can set a default certificate on an engineering PC, which is always used for TwinCAT C++, Target for MATLAB^®, Target for Simulink^®, etc., unless you explicitly specify a different certificate.

Select the certificate you want to use as the default certificate from the list in the Software Protection dialog and select the "Set as System Default" checkbox.

An environment variable with the name TcSignTwinCatCertName is then created. In Windows, environment variables are made known when a process is started. Therefore, restart MATLAB^® if you are already running the process.

Further options for using certificates can be found later in this chapter.

Store password for a certificate (required)

For security reasons, the password of a certificate must not be entered in the project or source code in the Simulink^® model or in the MATLAB^® code. With "Store Password for Current User" you store the corresponding passwords for your certificates on your system.

The passwords are stored obfuscated in the registry of the Windows operating system. This means that the password for a specific certificate is known in the operating system (for the Current User) and is used automatically.

Select the certificate for which you want to store the corresponding password in the Software Protection dialog. Select "Store Password for Current User". You will be asked to enter your password. If it has been successfully checked and entered, the note "PW Stored" appears under "TMX Signing".

An alternative variant for storing a password is the command prompt with the TcSignTool (C:\Program Files (x86)\Beckhoff\TwinCAT\3.1\SDK\Bin).

The password is stored with the following call:

tcsigntool grant /f "C:\TwinCAT\3.1\CustomConfig\Certificates\MyCertificate.tccert" /p MyPassword

The obfuscated password is stored in the registry under: HKEY_CURRENT_USER\SOFTWARE\Beckhoff\TcSignTool\

The password is deleted with the following call:

tcsigntool grant /f "C:\TwinCAT\3.1\CustomConfig\Certificates\MyCertificate.tccert" /r

Set up OEM certificate level 2 for driver signing without the Software Protection dialog

To sign tmx files, you need a certificate and a password associated with the certificate.

	Available certificates can be found at: Build 4026: C:\ProgramData\Beckhoff\TwinCAT\3.1\CustomConfig\Certificates Build 4024: C:\TwinCAT\3.1\CustomConfig\Certificates

Handling of the certificate

There are four possible variants for signing tmx drivers.

Variant 1: System-wide default certificate for TwinCAT C++ and TE14xx

This variant is identical to the path via "Software Protection" > "Set as System Default".

Alternatively, you can also create a Windows environment variable manually for this variant. Create a new environment variable at User > Variables with:

Variable: TcSignTwinCatCertName

Value: Full path of the certificate

Variant 2: System-wide default certificate for MATLAB^®

You can set a default certificate in your MATLAB^® environment, which is always used for Target for MATLAB^® and Target for Simulink^® (not TwinCAT C++), unless you explicitly specify a different certificate.

Open the Common Settings dialog with TwinCAT.ModuleGenerator.Settings.Edit (MATLAB® Command line) and enter the desired default certificate under Build > Certificate name for TwinCAT signing. This certificate is stored in your user directory as default and is used by all MATLAB^® versions on your system as default.

Variant 3: Certificate in the configuration of the Simulink^® model

You can explicitly name a certificate for each build operation. For Variant 3 you do not have to make any further settings in advance. Before each build process, you can define a certificate of your choice for precisely this build process.

Target for Simulink^®: TC Build > Certificate for TwinCAT signing

Target for MATLAB^®: Property SignTwinCatCertName

Variant 4: Build without certificate and sign later with TcSignTool

You can build without a certificate and sign afterwards with the TcSignTool.

The TcSignTool is a command line program. For example, open the command prompt and execute tcsigntool sign /? to display the help. The program can be found here:

Build 4026: C:\Program Files (x86)\Beckhoff\TwinCAT\3.1\SDK\Bin

Build 4024: C:\TwinCAT\3.1\SDK\Bin

	Operating TcSignTool from MATLAB^® From MATLAB^®, the tool can be started with the command `system()` or with `!`.

Sample call for signing a tmx driver for TwinCAT:


TcSignTool sign /f "C:\TwinCAT\3.1\CustomConfig\Certificates\ MyCertificate.tccert" /p MyPassword "C:\TwinCAT\3.1\Repository\TE140x Module Vendor\ModulName\0.0.0.1\TwinCAT RT (x64)\MyDriver.tmx"

Behavior of the TwinCAT runtime

If a TwinCAT object created from MATLAB^® or Simulink^® with a signed driver is used in a TwinCAT Solution and loaded onto a target system with Activate Configuration, the following must be observed:

Test mode for non-countersigned certificates

If you use a non-countersigned OEM certificate for signing, you must set your target system into test mode. To do this, run the following command as an administrator on the target system:

bcdedit /set testsigning yes

If you are using a countersigned OEM certificate, this step is not necessary.

Whitelist for certificates on target systems

Each TwinCAT runtime (XAR) has its own whitelist of trusted certificates.

Behavior with TwinCAT Build 4026

The TwinCAT-XAE checks whether all certificates required to activate the configuration are in the whitelist on the runtime system. If this is not the case, a pop-up window appears. You can set the whitelist entries there.

Behavior with TwinCAT Build 4024

If the certificate used for signing is not included in this whitelist, the driver will not be loaded. A corresponding error message is output in TwinCAT Engineering (XAE).

The error message contains the instruction to execute a registry file, which was automatically created on the target system, on the target system as administrator. This process adds the used certificate to the whitelist.

	Registry file is only dependent on the OEM certificate The registry file can also be used on other target systems. It only contains information about the OEM certificate used and is not target system dependent.