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 an OEM certificate level 2, so that it 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.

• General documentation on OEM certificates
• Application-related documentation for tmx 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)).
• All drivers (for 32-bit and for 64-bit operating systems) must be signed.
• 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).

Use of an OEM level 2 certificate for driver signing

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

Handling of the certificate

There are four possible variants for signing tmx drivers.

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

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

For this variant, you use a Windows environment variable. Create a new environment variable at User > Variables with:

Variable: TcSignTwinCatCertName

Value: Name of the desired certificate

Available certificates can be found at TwinCAT\3.1\CustomConfig\Certificates.

Variant 2: System-wide default certificate for TE14xx

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 mentioned above with TwinCAT.ModuleGenerator.Settings.Edit 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. For Variant 4 you can use the TcSignTool.

The TcSignTool is a command line program located in the path ..\TwinCAT\3.1\sdk\Bin\. For example, open the command prompt and execute tcsigntool sign /? to display the help.

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"

Handling the certificate password

The password is only entered directly at Variant 4 of the certificate handling. For Variants 1 to 3, the associated password must be entered in addition to the certificate. For security reasons, the password should not be entered in the source code in the Simulink^® model or in the MATLAB^® code. With the TcSignTool you can store obfuscated passwords belonging to your certificates 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 corresponding user) and is used automatically.

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

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:

Each TwinCAT runtime (XAR) has its own white list of trusted certificates. If the certificate used for signing is not included in this white list, 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 white list.

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.

If you use a non-countersigned OEM certificate for signing, you must also put 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.