Einrichtung der Treibersignierung

Aus MATLAB® oder Simulink® generierte TwinCAT-Objekte basieren, wie auch TwinCAT C++-Objekte, auf einem tmx-Treiber (TwinCAT Module Executable). Diese Treiber müssen mit einem OEM-Zertifikat Level 2 signiert werden, damit der Treiber in der TwinCAT-Laufzeit auf dem Laufzeit-PC geladen werden kann.

Für Beckhoff RT-Linux® ist keine Treiber-Signierung erforderlich. Für alle andere Plattformen ist dies zwingend notwendig.

Unter folgenden Links finden Sie eine ausführliche Dokumentation zur Erstellung eines OEM-Zertifikats zur Treibersignierung:

Das Wichtigste in Kürze:

Einrichtung für den Einsatz in MATLAB® oder Simulink®

Die Signierung der tmx-Treiber kann von dem Target for MATLAB® oder Simulink® übernommen werden. Hierzu müssen drei Schritte durchgeführt werden:

Sie haben ein Zertifikat erstellt (gegensigniert oder nicht gegensigniert).
1. Das Passwort für das Zertifikat muss hinterlegt werden.
2. Das Zertifikat muss ausgewählt werden.
Sie können dann das Target for Simulink® oder MATLAB® nutzen, um signierte TcCOM Module zu generieren.
3. Auf dem Laufzeit System muss das Zertifikat als vertrauenswürdig hinzugefügt werden.
Sie können dann die mit dem Target for Simulink® oder MATLAB® generierten und signierten Module in TwinCAT ausführen.

Schritt 1 und 2 müssen auf dem Engineering-System und Schritt 3 auf dem Laufzeit-System durchgeführt werden. Die drei Schritte sind in den folgenden Abschnitten näher beschrieben.

Information zum Dialog "Software Protection"

Ab TwinCAT 3.1 Build 4026.14 (Workload: TwinCAT Standard 4026.14) steht in Visual Studio der Dialog Menu bar > TwinCAT > Software Protection… zur Verfügung. Dieser Dialog vereinfacht das Erstellen von OEM-Zertifikaten, das Setzen eines systemweiten Default-Zertifikats sowie das Hinterlegen des Zertifikatspassworts für den aktuellen Windows‑User. Wenn Sie diese Oberfläche nutzen können, ist dies die empfohlene und komfortabelste Methode.

Einrichtung der Treibersignierung 1:

In der obigen Übersicht befinden sich beispielhaft zwei Zertifikate.

Das erste Zertifikat „TestSign123“ ist nicht von Beckhoff gegensigniert, deshalb wird es im Status als invalid klassifiziert. Nicht gegensignierte Zertifikate können dennoch zum Signieren genutzt werden. Das Zielsystem ist dann in den Testmodus zu versetzen – siehe Abschnitt Verhalten der TwinCAT-Laufzeit.

Das zweite Zertifikat „TmxSignCertFaxxxBx“ ist hingegen gegensigniert und damit als valid klassifiziert.

Beide Zertifikate eignen sich zum Signieren von tmx-Dateien, wie unter Permissions zu sehen ist. In der Spalte „TMX Signing“ ist mit Default vermerkt, wenn ein Zertifikat als systemweites Default-Zertifikat festgelegt ist. Der Vermerk PW Stored zeigt an, dass das Passwort des Zertifikats für den angemeldeten Windows Nutzer verfügbar/hinterlegt ist.

Einrichtung der Treibersignierung 2:

Der Dialog "Software Protection" ist erst ab TwinCAT Build 4026.14 verfügbar

Wenn Sie eine ältere TwinCAT-Version einsetzen (vor Build 4026.14) oder die GUI nicht verwenden möchten, steht das Kommandozeilen-Tool TcSignTool als vollwertige Alternative zur Verfügung. Das Programm finden Sie hier:

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

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

Schritt 1: Passwort für die Treibersignierung hinterlegen (erforderlich)

Das Passwort eines Zertifikats darf aus Sicherheitsgründen nicht im Projekt oder Quellcode im Simulink®-Modell oder im MATLAB®-Code eingetragen werden. Die Passwörter werden obfuskiert in der Registry des Windows-Betriebssystems abgelegt. Dadurch ist das Passwort zu einem bestimmten Zertifikat im Betriebssystem (für den Current User) bekannt und wird automatisch verwendet.

Im Dialog Software Protection:

1. Markieren Sie das Zertifikat, für welches Sie das zugehörige Passwort hinterlegen möchten.
2. Wählen Sie die Checkbox „Store Password for Current User“ aus.
Es öffnet sich ein Fenster.
3. Geben Sie in dem Fenster das entsprechende Passwort, das Sie beim Erstellen des Zertifikats ausgewählt haben, ein.
Das Passwort ist hinterlegt. Wenn es erfolgreich überprüft und eingetragen wurde, erscheint der Vermerk „PW Stored“ unter „TMX Signing“.

Alternative ohne Dialog Software Protection mittels TcSignTool über die Kommandozeile:

Die Kommandozeile ist mit Nutzerrechten (nicht Administrator!) geöffnet.
1. Wechseln Sie in das Verzeichnis des TcSignTools:
Build 4026: C:\Program Files (x86)\Beckhoff\TwinCAT\3.1\SDK\Bin
Build 4024: C:\TwinCAT\3.1\SDK\Bin
2. Legen Sie mit dem nachfolgenden Aufruf das Passwort für das Zertifikat ab.
Das Passwort ist dann hinterlegt.
tcsigntool grant /f "C:\TwinCAT\3.1\CustomConfig\Certificates\MyCertificate.tccert" /p MyPassword

Die Ablage des obfuskierten Passworts erfolgt in der Registry unter: HKEY_CURRENT_USER\SOFTWARE\Beckhoff\TcSignTool\

Mit folgendem Aufruf kann das Passwort gelöscht werden:

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

Schritt 2: Zertifikat für die Treibersignierung auswählen

Für die Auswahl der Zertifikate gibt es folgende Varianten:

Variante

Beschreibung

Vorteil

Nachteil

Empfohlen für

Default-Zertifikat Systemweit

Ein Zertifikat wird standardmäßig für alle Signierungsvorgänge (auch in TwinCAT) genutzt

Einfach

Gilt für alle Projekte (kann lokal überschrieben werden)

Standard

Default-Zertifikat nur für MATLAB®

Ein Zertifikat wird standardmäßig für alle Signierungsvorgänge in MATLAB® genutzt

Spezifisch für MATLAB® oder Simulink®

Überschreibt Systemweites Zertifikat

Zertifikat wird nicht automatisch für TwinCAT C++ genutzt

MATLAB® oder Simulink® only Builds

Zertifikat pro Build

Das Zertifikat wird im Simulink®-Modell oder MATLAB®-Code angegeben und nur für dieses Build genutzt.

Flexibel

Überschreibt Default-Zertifikate

Muss jedes Mal gesetzt werden

Einzelprojekte

Nachträgliche Signierung

Build ohne Zertifikat und anschließende Signierung mittels TcSignTool

Kein Zertifikat beim Build nötig

Zusätzlicher (manueller) Schritt

CI/CD

Variante 1: Default-Zertifikat Systemweit

Sie können ein Default-Zertifikat setzen, welches immer für Target for MATLAB® und Target for Simulink® (und TwinCAT C++) genutzt wird, sofern Sie kein anderes Zertifikat explizit angeben.

Im Dialog Software Protection:

1. Markieren Sie das Zertifikat, welches Sie als Standard festlegen möchten.
2. Wählen Sie „Set as System Default“.
Das Zertifikat ist als systemweites Default-Zertifikat hinterlegt. Wenn es erfolgreich eingetragen wurde, erscheint der Vermerk „Default“ in der Spalte „TMX Signing“.

Alternative ohne Dialog Software Protection:

Für diese Variante können Sie alternativ auch händisch eine Windows-Umgebungsvariable anlegen. Legen Sie eine neue Umgebungsvariable unter User > Variables an mit:

Variable: TcSignTwinCatCertName

Value: Full-Path des Zertifikats

Variante 2: Default-Zertifikat nur für MATLAB®

Sie können in Ihrer MATLAB®-Umgebung ein Default-Zertifikat setzen, welches immer für das Target for MATLAB® und das Target for Simulink® (nicht TwinCAT C++) genutzt wird, sofern Sie kein anderes Zertifikat explizit angeben.

Öffnen Sie den Common Settings-Dialog mit TwinCAT.ModuleGenerator.Settings.Edit (MATLAB Command line) und tragen Sie das gewünschte Default-Zertifikat ein unter Build > Certificate name for TwinCAT signing. Dieses Zertifikat wird in Ihrem User-Verzeichnis als Default gespeichert und von allen MATLAB® -Versionen auf Ihrem System als Standard genutzt.

Variante 3: Zertifikat pro Build

Sie können für jeden Build-Vorgang ein Zertifikat explizit benennen. Für diese Variante müssen Sie keine weiteren Einstellungen vorab treffen (jedoch auch hier im Vorfeld das Passwort hinterlegen). Sie können vor jedem Build-Vorgang ein Zertifikat Ihrer Wahl für genau diesen Build-Vorgang definieren.

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

Target for MATLAB®: Property SignTwinCatCertName

Variante 4: Nachträgliche Signierung

Sie können ohne Zertifikat bauen und nachträglich mit dem TcSignTool signieren. Hier muss das Passwort nicht während des Build Prozesses bekannt sein (während der anschließenden Signierung muss das Passwort bekannt sein).

Das TcSignTool ist ein Kommandozeilen-Programm. Öffnen Sie bspw. das Command Prompt und führen Sie tcsigntool sign /? aus, um die Hilfe angezeigt zu bekommen. Das Programm finden Sie hier:

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

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

Einrichtung der Treibersignierung 3:

TcSignTool aus MATLAB® bedienen

Aus MATLAB® kann das Tool mit dem Befehl system() oder mit ! aufgerufen werden.

Beispielaufruf zur Signierung eines tmx-Treibers für 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"

Schritt 3: Verhalten der TwinCAT-Laufzeit

Wird ein aus MATLAB® oder Simulink® erstelltes TwinCAT-Objekt mit signiertem Treiber in einer TwinCAT-Solution genutzt und mit Activate Configuration auf ein Zielsystem geladen, ist Folgendes zu beachten:

Testmodus für nicht gegensignierte Zertifikate

Wenn Sie ein nicht-gegensigniertes OEM-Zertifikat zur Signierung nutzen, müssen Sie Ihr Zielsystem in den Test-Modus versetzen. Führen Sie dazu den folgenden Befehl als Administrator auf dem Zielsystem aus:

bcdedit /set testsigning yes

Bitte beachten Sie, dass der Testmodus die Zertifikatsprüfung deaktiviert und nur in Entwicklungsumgebungen genutzt werden sollte.

Wenn Sie ein gegensigniertes OEM-Zertifikat nutzen, ist dieser Schritt nicht notwendig.

Whitelist für Zertifikate auf Zielsystemen

Jede TwinCAT-Laufzeit (XAR) hat eine eigene Whitelist an vertrauenswürdigen Zertifikaten.

Verhalten bei TwinCAT Build 4026

Das TwinCAT-XAE prüft, ob alle Zertifikate, die zur Aktivierung der Konfiguration notwendig sind, auf dem Laufzeit-System in der Whitelist stehen. Ist dies nicht der Fall, erscheint ein Pop-Up-Fenster. Sie können dort die Whitelist-Einträge setzen.

Verhalten bei TwinCAT Build 4024

Ist das Zertifikat, welches zur Signierung genutzt wurde, nicht in dieser Whitelist enthalten, wird der Treiber nicht geladen. Im TwinCAT Engineering (XAE) wird eine entsprechende Fehlermeldung ausgegeben.

Einrichtung der Treibersignierung 4:

Die Fehlermeldung enthält die Anweisung, ein Registry File, welches auf dem Zielsystem automatisch erstellt wurde, auf dem Zielsystem als Administrator auszuführen. Dieser Vorgang fügt das genutzte Zertifikat der Whitelist hinzu.

Einrichtung der Treibersignierung 5:

Registry File ist nur vom OEM-Zertifikat abhängig

Das Registry File kann ebenso auf weiteren Zielsystemen genutzt werden. Es enthält nur Informationen über das genutzte OEM-Zertifikat und ist nicht zielsystemabhängig.