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

There are four possible variants for signing tmx drivers.

1. 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.
2. You can set a default certificate on an engineering PC that is always used for Target for MATLAB^® and Target for Simulink^® unless you explicitly specify a different certificate.
3. You can explicitly name a certificate for each build operation.
4. You can build without a certificate and sign afterwards with the TcSignTool.

For Variant 1 use a Windows environment variable. Create a new environment variable at User > Variables with:

Variable: TcSignTwinCatCertName

Value: Name of the desired certificate
(Available certificates are located at TwinCAT\3.1\CustomConfig\Certificates).

For variant 2 open the above Common Settings dialog with TwinCAT.ModuleGenerator.Settings.Edit and name the default certificate 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.

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

For variant 4 you can use the TcSignTool. The TcSignTool is a command line program located in the path C:\TwinCAT\3.x\sdk\Bin\. With tcsigntool /? or tcsigntool sign /? you get help how to use the tool concretely.

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"

For variants 1 to 3, the associated password must be stored in the system in addition to specifying the certificate with the TcSignTool. 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 passwords belonging to your certificates encrypted in the registry of the Windows operating system.

The storage of the password is carried out with the following parameters:

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

The password is deleted with the following parameters:

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

The unencrypted password is stored under: HKEY_CURRENT_USER\SOFTWARE\Beckhoff\TcSignTool\

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

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.