Manual Security Management - Beckhoff€¦ · Foreword Security Management Version: 1.55 1 Foreword 1.1Notes on the documentation This description is only intended for the use of

Manual

Security Management

TwinCAT 3

1.52018-03-26

Version:Date:

Table of contents

Security Management 3Version: 1.5

Table of contents1 Foreword .................................................................................................................................................... 5

1.1 Notes on the documentation........................................................................................................... 51.2 Safety instructions .......................................................................................................................... 6

2 Introduction................................................................................................................................................ 7

3 OEM certificates ...................................................................................................................................... 113.1 Requesting and installing OEM certificates .................................................................................. 123.2 Extending an OEM certificate ....................................................................................................... 14

4 User databases (user DBs)..................................................................................................................... 154.1 Creating a user database ............................................................................................................ 154.2 Linking the user database to a project ......................................................................................... 204.3 Distribution of user databases ..................................................................................................... 21

5 Protection of the OEM application software ......................................................................................... 235.1 User access authorizations........................................................................................................... 23

5.1.1 Creation and edition of users and user groups ................................................................ 245.1.2 Customizing the rights of user groups ............................................................................. 265.1.3 Creating and editing access authorization groups (Object Protection Level) .................. 285.1.4 Assigning access rights in the project .............................................................................. 315.1.5 Logging in and selecting a user account.......................................................................... 32

5.2 Encryption..................................................................................................................................... 335.2.1 Encrypt source code ........................................................................................................ 345.2.2 Encrypting custom libraries ............................................................................................. 345.2.3 Encrypting the project file................................................................................................. 355.2.4 Encrypting the boot project .............................................................................................. 365.2.5 Displaying the object protection status ............................................................................ 37

5.3 Signing files (protection against unauthorized changes) ............................................................. 375.4 OEM application licenses ............................................................................................................. 38

5.4.1 Creating OEM application licenses .................................................................................. 395.4.2 Querying the OEM application license in a PLC application............................................ 465.4.3 Storing OEM application licenses on a dongle ................................................................ 49

5.5 Displaying an overview of the project's security management settings ........................................ 49

Table of contents

Security Management4 Version: 1.5

Foreword


1 Foreword

1.1 Notes on the documentationThis description is only intended for the use of trained specialists in control and automation engineering whoare familiar with the applicable national standards.It is essential that the documentation and the following notes and explanations are followed when installingand commissioning the components. It is the duty of the technical personnel to use the documentation published at the respective time of eachinstallation and commissioning.

The responsible staff must ensure that the application or use of the products described satisfy all therequirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly underdevelopment.We reserve the right to revise and change the documentation at any time and without prior announcement.No claims for the modification of products that have already been supplied may be made on the basis of thedata, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE®, XFC® and XTS® are registeredtrademarks of and licensed by Beckhoff Automation GmbH.Other designations used in this publication may be trademarks whose use by third parties for their ownpurposes could violate the rights of the owners.

Patent Pending

The EtherCAT Technology is covered, including but not limited to the following patent applications andpatents:EP1590927, EP1789857, DE102004044764, DE102007017835with corresponding applications or registrations in various other countries.

The TwinCAT Technology is covered, including but not limited to the following patent applications andpatents:EP0851348, US6167425 with corresponding applications or registrations in various other countries.

EtherCAT® is registered trademark and patented technology, licensed by Beckhoff Automation GmbH,Germany

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.The reproduction, distribution and utilization of this document as well as the communication of its contents toothers without express authorization are prohibited.Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of apatent, utility model or design.

Foreword


1.2 Safety instructions

Safety regulations

Please note the following safety instructions and explanations!Product-specific safety instructions can be found on following pages or in the areas mounting, wiring,commissioning etc.

Exclusion of liability

All the components are supplied in particular hardware and software configurations appropriate for theapplication. Modifications to hardware or software configurations other than those described in thedocumentation are not permitted, and nullify the liability of Beckhoff Automation GmbH & Co. KG.

Personnel qualification

This description is only intended for trained specialists in control, automation and drive engineering who arefamiliar with the applicable national standards.

Description of symbols

In this documentation the following symbols are used with an accompanying safety instruction or note. Thesafety instructions must be read carefully and followed without fail!

DANGER

Serious risk of injury!Failure to follow the safety instructions associated with this symbol directly endangers thelife and health of persons.

WARNING

Risk of injury!Failure to follow the safety instructions associated with this symbol endangers the life andhealth of persons.

CAUTION

Personal injuries!Failure to follow the safety instructions associated with this symbol can lead to injuries topersons.

Attention

Damage to the environment or devicesFailure to follow the instructions associated with this symbol can lead to damage to the en-vironment or equipment.

Note

Tip or pointerThis symbol indicates information that contributes to better understanding.

Introduction


2 IntroductionThe TwinCAT 3 Security Management provides TwinCAT 3 Engineering with functions for protecting theOEM application software on Beckhoff IPCs:

• Know-how protection through encryption of source code and boot file• Copy protection through the application of TwinCAT 3 license technology for the OEM application

software. (Requires a Beckhoff IPC/EPC!)• Definition of user groups with configurable source code access limitations

Using the TwinCAT 3 license technology also enables the OEM to generate licenses for functional expansionof its application software and to market them. (Requires a Beckhoff IPC/EPC!)

Note

TwinCAT 3.1 build 4022The functionalities described above require TwinCAT 3.1 build 4022 or higher.

Note

Operating system Windows 7 or higherWindows 7 (or its embedded version) or higher is required for utilizing the full functionalityof the TwinCAT 3 Security Management. Windows XP and Windows CE (Windows Embed-ded Compact) support neither encryption of the boot file nor OEM licenses.

An OEM certificate [} 11] signed by Beckhoff is required for utilizing the TwinCAT 3 Security Management.The OEM certificate secures the user database (user DB) [} 15] through signing. The user DB is a centralitem of the TwinCAT 3 Security Management, which controls access to the components of the OEMapplication.

If a project is linked to a specific user DB by an authorized user, it can subsequently only be opened inconjunction with this user DB.

Introduction


The User access authorizations [} 23] are controlled via “Object Protection Groups” within the user DB. Inthe following sample these are called “Development” and “Public”. The users “John Smith” and “Guest” wereassigned to these groups. Each group is assigned rights. The assignments are pooled in “Object ProtectionLevels”, which can then be assigned to the project components in TwinCAT 3 Engineering.

This means that at first, the access rights are specified within TwinCAT 3 Engineering. The source codehowever can still be accessed via the operating system level. The corresponding files therefore have to beadditionally encrypted at the file level.

Introduction


Note

Encryption always with Object Protection LevelTo protect a project component against unauthorized access, it must be assigned an Ob-ject Protection Level in TwinCAT 3 Engineering, and it must be encrypted at operating sys-tem level. Although encryption without setting the correct Object Protection Level encryptsthe corresponding file at operating system level, it would still allow access in TwinCAT 3Engineering. Conversely, although setting a correct Object Protection Level would specifythe access in TwinCAT 3 Engineering, access to the source code via the operating systemlevel would still be possible.

The key used for the encryption is secured in the user database. The corresponding user database musttherefore always be available on the Engineering computer. (Directory: C:\Twincat\3.1\CustomConfig\userDBs)

Security Management console

A central Security Management console is available for configuration of the general functions.

1. Activate the "TwinCAT XAE Security" toolbar in View > Toolbars.

Introduction


ð The “TwinCAT XAE Security” toolbar appears in the toolbar area.

2. Click on "Security Management" next to the dropdown list. Alternatively, the "Security Management"command can be found in the "TwinCAT" menu.

ð The Security Management console opens. The TwinCAT 3 Security Management can be configured viathe console.

Hints about configuration can be found in the following sections:

• OEM certificates [} 11]

• User databases (user DBs) [} 15]

• Protection of the OEM application software [} 23]

OEM certificates


3 OEM certificatesThe use of the TwinCAT 3 Security Management functions is based on an OEM certificate signed byBeckhoff.

An OEM can create an “OEM Certificate Request File” in the Security Management and email it to Beckhoffat [email protected].

Beckhoff will check the application, sign the file and return the OEM certificate to the email address fromwhich the request was sent.

The OEM key contained in the certificate can then be used for the various TwinCAT 3 Security Managementfunctions:

• Creating a user database (user DB) for user access control• Creating OEM application license description files• Issuing (signing) of OEM application licenses

NOTE! Use a secure PC for activities that require handling of the private key password, in order toprevent password sniffing.

Validity of the OEM certificate

For reasons of security, the validity of the OEM certificate is limited to two years.

OEM certificates


The OEM may apply for an extension of the certificate before the two years have expired, in order to be ableto continue working without interruption. (See section "Extending an OEM certificate [} 14]")

What happens if the certificate has expired?

The following functions are no longer available with an invalid (expired) OEM certificate:

• Creating a user database• Creating OEM application license description files• Issuing (signing) of OEM application licenses

The user database remains valid, and the administrator can continue to modify/adapt the database. It is nolonger possible to create a new user database.

3.1 Requesting and installing OEM certificatesü The Security Management console [} 9] is open.1. Select the "Certificates" tab.2. Click on "Create New OEM Certificate".

OEM certificates


ð The "Create OEM Certificate" input window opens.

3. Enter the required data for an “OEM Certificate Request File”:• Enter an "OEM Name". You can choose the name of the OEM name. It should have a clear link to your

company.• Enter a "Unique Name". As the name suggests, the OEM Unique Name must be a unique name, on

the base of which the certificate can be identified unambiguously worldwide, e.g. the URL of yourcompany website or your email address.

• Enter the required functions for your certificate. Tick the corresponding check boxes under "Certificatefor".The minimum requirement is "Sign database key"; without it, you cannot create a user database. The"Sign license request" function is optional.

• The "Issue Date" and "Expire Date" fields are filled in automatically and should not be changed. NOTE! Note the expiry date of your certificate and make sure you request an extension for yourcertificate in good time before it expires. (See section "Extending an OEM certificate [} 14]")

4. Once you have completed all the fields, click "Start" and choose a directory to save the file.ð A dialog for selecting a password for the OEM private key opens.

5. Enter a password for the OEM private key, confirm the password by repeating it and close the dialogwith "OK".

ð The file is saved.6. Your request for a Beckhoff OEM certificate must be authorized by your local Beckhoff contact. Please

email the generated file to your local Beckhoff contact and ask them to authorize your request andforward it internally to [email protected].

7. Once you have received the signed certificate, save it on your Engineering system in directory C:\twincat\3.1\customconfig\certificates.

ð After a restart of TwinCAT Engineering the certificate appears in the Security Management consoleunder the “Certificates” tab. NOTE! Check whether the certificate is shown as "valid".

Note

Do not forget the password!Beckhoff is unable to recover or reset your password. If you forget or lose the password foryour OEM certificate, you can no longer use it and have to request a new OEM certificate.

mailto:[email protected]

OEM certificates


3.2 Extending an OEM certificateTo extend an OEM certificate, please send the existing certificate before it expires [email protected] with a request to sign the certificate again, thereby extending it.


User databases (user DBs)


4 User databases (user DBs)

4.1 Creating a user databaseü User database can only be created or edited if no project is open. Close any open projects.

ü The Security Management console [} 9] is opened.1. Select your OEM certificate in the "Certificates" tab.2. Then click on "Create New User DB".

ð The "Create new User DB" dialog opens.



3. Select the first entry ("Database File") and enter a filename for the database to be created. NOTE! The database must be stored in the folder C:\TwinCAT\3.1\CustomConfig\UserDBs.



4. Enter a name for the database ("Database Name"). This name is used in the program to display theselected database.



5. Enter a "Database Unique Name", which allows unambiguous identification of this database within yourcompany.



6. Enter a name and password for the database administrator. NOTE! The "Database Admin" createdhere is used exclusively for signing the database. This "Database Admin" cannot be used forlogging in or for changes to the database. In order to make changes to the database, at least onedatabase user must belong to the administrator group.

7. Check whether "Database Template" and "OEM Certificate File" contain (valid) entries.8. Click "OK".

ð The database is saved. A dialog opens with a prompt to enter the password for the OEM private key,with which the database has to be signed before it can be used.

9. Enter the password for the OEM private key and confirm the dialog with "OK".

ð A further dialog opens with the question whether the database should be enabled.



10. Confirm the dialog with "OK".

11. Finally, in the "Database" tab of the Security Management console, select the newly created databaseas the working database and confirm with "OK".

ð The database is created and enabled.

In this window you can select a different database, if required.

Working with a user database can be disabled by selecting "None". The functions of the TwinCAT 3 SecurityManagement are then no longer available. An exception is the function "OEM Application License":

• OEM Application Licenses can still be signed, as this function only requires a valid OEM certificate, notan active user database.

• Encryption and decryption is no longer possible, since the encryption key is stored in the userdatabase.

• Projects associated with this user DB can no longer be opened.

4.2 Linking the user database to a projectInitially, a project must be manually linked to a user database. The linking to the database is then stored inthe project.

ü A user database has been created and enabled. A TwinCAT project is opened.1. In the TwinCAT project, double-click the SYSTEM node to open the system settings.2. Open the "Settings" tab.



3. In the "User Database" section, check the "Connect with current user database" check box.

4. Click "Apply" to take over the setting.ð The project is linked to the user database. The "Security" section is displayed under "Properties" for each

project component.

4.3 Distribution of user databasesNote the following when working with user DBs:

• In the current TwinCAT 3 version the user DB must always be stored in directory C:\TwinCAT\3.1\CustomConfig\UserDBs.

• A user DB can be freely copied and pasted at the file level.• When a user DB is created a one-to-one user DB key is generated, which identifies this database

unambiguously.



• When a project is linked to a user DB, it can only be opened with a user DB with the same filenameand the same user DB key.

• Modifications of the content of a user DB do not affect the user DB key (this key is only generated onceat the time when the user DB is created). In principle, you can therefore work with several differentversions of a user DB. Sample: The “in-house” version of a user DB contains other user accounts thanthe version supplied to the end customers on the control computer. The end customer can only see aspecified selection of the available user accounts. You can severely restrict the available accessoptions on the delivered machine, compared with the “in-house” development environment.

• Once a user DB has been created, the OEM certificate is no longer required for working with the userDB.

• Changes to the user DB must be signed by an administrator of the user DB. The corresponding queryappears automatically on exiting the Security Management console after changes to the user DB.

Protection of the OEM application software


5 Protection of the OEM application software

Note


Note


5.1 User access authorizationsIn TwinCAT 3 Engineering, access rights are always assigned to groups, not individual users. Users can beassigned to one or several groups and inherit the corresponding access rights. A new group can be amember of an existing group and inherit its rights.

In order to simplify the assignment of access rights of all groups for a particular object in TwinCAT 3Engineering, they are organized in "Object Protection Levels". An Object Protection Level forms a matrix ofthe existing groups and the available rights for a TwinCAT 3 object. For each individual group you can defineits rights at this specific Object Protection Level. Finally, the Object Protection Level is assigned to an objectin TwinCAT 3 Engineering. This enables convenient assignment of a collection of group-specific rights to anobject in TwinCAT 3 Engineering, without the need to define each object individually for every group. Theavailable rights are: "View", "Delete", "Modify" and "Add / Remove Children".



5.1.1 Creation and edition of users and user groups

Note

At least one user with administrator rightsIn order to make changes to the database, at least one database user must belong to theadministrator group. Therefore, always create at least one user with administrator rights.The "Database Admin" defined when the user DB is created is used exclusively for signingthe database. This account cannot be used for logging in or for changes to the database.

Creating and editing users

In the "Users" tab of the Security Management console you can change the settings for existing users andcreate new users.

ü User database can only be created or edited if no project is open. Close any open projects.

ü The Security Management console [} 9] is opened.1. Select the "Users" tab.

2. Click "Add" to add a new user.ð The "Edit User Credentials" dialog opens.

3. Specify a name for the user and assign the user to a user group by ticking the corresponding check box("Groups").

4. For a Windows account the authentication can be done automatically via Windows. For all other usersyou have to specify a user-specific password. Click on "Change Password".ð A dialog box for setting a password opens.

5. Assign a password for the user and confirm the password by repeating it.



6. Close the dialog with "OK".

ð The new user appears in the overview.7. To edit an entry, select the user in the list and click "Edit".8. Close the "Edit User Credentials" dialog with "OK".ð A new user has been created in the system.

NOTE! All changes that were made are not finalized and valid until the user database is saved andsigned.

Creating and editing user groups

In the "Groups" tab of the Security Management console you can change the settings for existing usergroups and create new user groups.

ü The Security Management console [} 9] is opened.



1. Select the "Groups" tab.

2. Click "Add" to create a new group.ð The "Edit User Group" dialog opens.

3. Enter a name ("Name") for the group.4. If the group is to inherit the rights of another group, select the corresponding group in the "Groups"

section.5. Close the dialog with "OK".

ð The new group appears in the overview.6. To edit an entry, select the user group in the list and click "Edit".7. Close the "Edit User Group" dialog with "OK".ð A new user group has been created in the system.


In the "Rights [} 26]" tab you can assign rights to user groups. Further information can be found in section"Customizing the rights of user groups [} 26]".

5.1.2 Customizing the rights of user groups

Note

TwinCAT 3.1 Build 4022 or higherThe functionality described below requires TwinCAT 3.1 Build 4022 or higher.



The rights assigned to the user groups can be managed in the "Rights" tab of the Security Managementconsole.


ü The Security Management console [} 9] is opened.1. Select the "Rights" tab.2. In the "UserGroups" column select the row with the desired right and click the "Grant" button.

ð The "Grant Right to User Groups" dialog opens.



3. Use the check boxes to select which user groups should have this right.

4. Click "OK".ð The changes are applied (temporarily).


5.1.3 Creating and editing access authorization groups (ObjectProtection Level)


ü The Security Management console [} 9] is opened.1. Select the "Object Protection" tab.2. Click "Add".

ð The "Edit Object Protection Level" dialog opens.



3. Assign the individual user rights, by ticking the respective check boxes, for all the groups defined underSecurity Management for this specific Object Protection Level.

The following sample shows the definition of the "Public" Object Protection Level:

• The "Guest" user group can read a TwinCAT object that is assigned this Object Protection Level butcannot change it.

• The "Service" user group can read and modify a TwinCAT object that is assigned this Object ProtectionLevel but cannot delete it.



• The "Developers" user group has full access.

In the following sample only the "Developers" user group has access to the TwinCAT object. The otheruser groups have no rights at all.

4. Confirm the dialog with "OK".ð The Object Protection Level with the user rights is created in the system and displayed in the

overview of the "Object Protection" tab in the Security Management console.5. Assign the required user rights for further user groups in an Object Protection Level accordingly.6. To edit an Object Protection Level, select the corresponding column and click "Edit".

7. To remove an Object Protection Level, click "Remove".8. To change the position of the selected Object Protection Level in the overview, click on "Move up" or

"Move down".




5.1.4 Assigning access rights in the projectThe created Object Protection Levels [} 28] can easily be assigned to TwinCAT objects, e.g. a PLC project.

ü The access authorization groups are defined.ü The project is linked to a user database.1. Select the PLC object in the PLC project tree in the Solution Explorer.

ð The "Properties" view is updated. (If the "Properties" view is not opened, select the "PropertiesWindow" in the "View" menu to open it.)

2. Select the required Object Protection Level from the drop-down list of the "ObjectProtection" property inthe "Security" category.

3. In addition, set the value of the "Encryption" property to "TRUE" via the dropdown list. NOTE! Thissetting is important for preventing access to the source code, e.g. via the operating system level.

ð The PLC project can now be accessed by the user groups, which were specified in the Object ProtectionLevel. Save the PLC project to apply the settings.

"Public" Object Protection Level sample:

• The "Guests" user group has read access to the PLC project.



• The "Developers" user group has full access.

(No access rights were defined for the other user groups, since they are not used in the sampleproject.)

The access rights specified in the root of the PLC project are automatically passed on in the PLC project treeto all sub-elements of the SPS object, if they have the properties "Object Protection Level" and "Encryption".

Alternatively, the "Object Protection Level" and the encryption can be assigned individually for each sub-element. This can be set in the sub-element properties.

Here too you must set the "Encryption" property for the object to prevent access to the source code via theoperating system level, for example.

5.1.5 Logging in and selecting a user accountA user account can conveniently be selected via the selection box in the Security Management toolbar.

ü You have opened the Security Management toolbar [} 9].1. Select the user account from the dropdown list.

2. If the user login requires a password, a dialog for entering the password opens. Enter the password. Ifthe authentication takes place via the Windows user account, no password is requested, since theauthentication was already dealt with at the Windows login stage.



ð The selected user account is displayed in the Security Management toolbar.

Depending on the user account rights, certain TwinCAT menu items may be greyed out and thereforedisabled.

5.2 Encryption

Note


Note


TwinCAT 3 uses 256-bit AES-encryption with private and public key.

Following objects can be encrypted in TwinCAT:

• Source code [} 34]

• Custom libraries [} 34]

• Project file [} 35]

• Boot project [} 36]

The key used for the encryption is secured in the user database. The corresponding user database musttherefore always be available on the Engineering computer. (Directory: C:\Twincat\3.1\CustomConfig\userDBs)



5.2.1 Encrypt source codeAccess to encrypted objects is controlled via the Object Protection Level. In addition to the encryption, youtherefore always have to set the required Object Protection Level for the TwinCAT 3 object. The ObjectProtection Level and encryption can be assigned conveniently in the properties of the respective TwinCATobject, e.g. a PLC project. The project must be linked to the user database. Encryption and the specificationof the Object Protection Level is described in section "Assigning access rights in the project [} 31]". Save theproject to apply the settings.

5.2.2 Encrypting custom librariesUsers can organize their own source code in the form of custom libraries. The components of these customlibraries can be encrypted and provided with access rights with the same mechanisms as the other usersource code.

If the current project is linked to a user database, you can select how you want to save it when you save thecustom library. For non-compiled libraries (i.e. libraries in the source code), select the file type "EncryptedLibrary files".



See also Linking the user database to a project [} 20]

5.2.3 Encrypting the project fileEncryption of the project file is set via the TwinCAT project node.

ü The project is linked to a user database.1. Select the TwinCAT project node in the project tree in the Solution Explorer.2. Select the command "Encrypt Project File" in the context menu.



ð In the "Properties" view, set the value of the "EncryptFile" property in the "Security" category toTRUE.

ð The project file is encrypted. It contains information on the components of the solution. The encryptionsetting only applies to the project file itself. The encryption is not inherited to the components containedin the project. The encryption must be set individually for all (main) components of the project.

5.2.4 Encrypting the boot project

Note


The encryption of the boot project is set (on the target-system) in the root node of the PLC project.

ü The project is linked to a user database.1. Double-click the PLC project object in the PLC project tree in the Solution Explorer.

ð The PLC project settings open in an editor.2. Select "Encrypt boot project" in the "Project" tab in the dropdown list for the "Encryption" setting.

ð The boot project is encrypted.



5.2.5 Displaying the object protection statusThe status of a TwinCAT object is indicated by the disk symbol in the object icon in the project tree.

To display the protection status of a TwinCAT object, the normal status display of the TwinCAT object isexpanded. The following table shows the symbols and their meaning.

TwinCAT object status symbols

Symbol MeaningNo changes

Unsaved changes

Signed

Encrypted

Rules:

1. Turquoise overrides blue2. Red overrides all other colours

5.3 Signing files (protection against unauthorizedchanges)

By signing project components (files), you ensure that individual components cannot be replaced withoutauthorization.



If the project is linked to a user database, you can set the signing in the properties of the respective projectcomponent. Select the project component in the Solution Explorer and set the value of the "Signed" propertyto TRUE in the "Properties" view.

NOTE! You should also sign the project file itself, since the information on which components mustbe signed is stored there.

5.4 OEM application licenses

Note

Beckhoff IPC/EPCThe functionalities relating to OEM application licenses described above require a BeckhoffIPC! IPCs with a platform level of 90 (or higher) are not supported.

Note

No TwinCAT 3 dongle supportCurrently it is not possible to use TwinCAT 3 dongles for OEM application licenses.(This feature is still under development.)

Note


Note


The TwinCAT 3 license technology is now also available for OEMs, to protect the respective OEMapplication against cloning through linking to hardware (Beckhoff IPC or TwinCAT dongle).

Using the same technology, an OEM can also issue so-called feature licenses for end customers to protectadditional program functions with the TwinCAT 3 license technology.

Generating and using TwinCAT 3 OEM application licenses only requires a TwinCAT 3 OEMcertificate, not a user DB.

For using TwinCAT 3 OEM application licenses, only the standard TwinCAT 3 Runtime is required on thecontrol computer. The operating system of the control computer must be Windows 7 or higher.



Licensing process

The licensing process is subdivided into the following steps:

1. Creating a general license description file.The license description file is used for describing and selecting a specific license type during the li-censing process. Among other information it contains a unique license ID, which is used to unambigu-ously identify the license type.

2. Creating a "License Request File" for the required target system.3. Signing the License Request File with the OEM certificate, thereby creating a License Response File

for the specified target system. This activates the corresponding OEM application license on the re-spective target system.

The details of the licensing process are described on the following pages.

5.4.1 Creating OEM application licensesThe following diagram provides a general overview of the licensing process:

The left part of the diagram (light grey box) illustrates the creation of a License Request Files for a TwinCAT3 license and its verification in the TwinCAT 3 Runtime.

The right part of the diagram (dark grey box) illustrates the licensing processes, which are handled by theBeckhoff license server.The issuing process of an OEM application license is handled by the OEM through signing with the OEMprivate key. In other words, the Beckhoff license server is not integrated in the OEM application licensegeneration process.



Note

OEM certificates should only be used in a secure environmentSince generating an OEM application license requires handling of the OEM certificate andits password, the process should only be carried out in an environment that is protectedagainst malicious software (protected PC), in order to prevent the password for the OEMprivate key being accessed by malicious software.

If the control computer and the Engineering computer are separate devices, the process flow looks asfollows:

The individual steps are described in the relevant subsections.

5.4.1.1 Preparing TwinCAT 3 Engineering

By default, TwinCAT 3 Engineering is not preconfigured for generating OEM licenses.

1. Create the following directories:• C:\TwinCAT\3.1\CustomConfig\Licenses• C:\TwinCAT\3.1\Components\Base\License

2. Copy the tool “CreateLicense.exe*” into the directory C:\TwinCAT\3.1\Components\Base\License. Thistool can be requested by sending an email to [email protected].

5.4.1.2 Creating a license description file for an OEM application license

The type parameters for a TwinCAT 3 license are specified in a license description file in XML format withthe extension “.tmc”.

A license description file contains:

• a one-to-one “License ID”, which makes the license type reliably identifiable• the one-to-one OEM ID (from the OEM certificate)• the OEM name• the name of the license type• the order number




• optionally an email address for receiving the License Request File

The OEM ID can be used to assign the license to a specific OEM. Only this OEM (with this OEM ID in itsOEM certificate) can sign the license with its OEM certificate, thereby making it valid.

An OEM license description file can be opened and modified with a suitable editor. Ensure that the XMLstructure is not damaged.

Creating a new OEM license description fileü The Security Management console [} 9] is open.1. In the "Certificates" tab, select the OEM certificate on the basis of which the OEM license description file

is to be created.2. Click on "Create Template License TMC File".

ð The "Create License TMC File" dialog opens.3. Enter the parameters for the OEM license description file:

• Save the license description file in the folder C:\TwinCAT\3.1\CustomConfig\Licenses and restartTwinCAT 3 Engineering. NOTE! Only then will the license description file be recognized byTwinCAT 3.

• Enter a license name and license order number.



4. Restart TwinCAT 3 Engineering, so that the new license type is detected.ð The license description file has been created.



5.4.1.3 Creating License Request Files for an OEM application license1. Double-click on the "License" SYSTEM sub-node in the TwinCAT project tree to open the TwinCAT 3

license manager.

ð The license settings open in an editor.2. Open the "Manage Licenses" tab and scroll down.

ð The newly generated OEM license can be found at the end of the list.

3. Tick the check box for the license.4. Open the "Order Information" tab.

5. Optionally, you can select a TwinCAT 3 license dongle as license hardware under "System ID" (dashedline).

6. Select the respective OEM under "Provider". NOTE! Do not select "Beckhoff", which only appliesfor TwinCAT 3 licenses from Beckhoff.



ð The selected OEM license must show up as active (i.e. not greyed out) in the list at the bottom of thewindow. If the license is greyed out, an incorrect "Provider" was selected. Only the licenses shown as"active" are transferred to the License Request File.

7. Click on "Generate File" to generate the License Request File (extension: *.tclrq).ð The standard dialog for saving a file opens.

8. Select a storage location and confirm the dialog.9. If the OEM has specified an email address, and an email client is installed on the Engineering computer,

the system asks whether the License Request File should be emailed right away to the email addressspecified by the OEM.

10. If the OEM did not specify an email address, the License Request File cannot be sent by email and hasto be transferred by different means to the computer on which signing of the License Request File withthe OEM certificate (and therefore generation of the OEM license) should take place.

ð The License Request File for an OEM application license has been created.

5.4.1.4 Creating License Response Files for an OEM application license

Note

OEM certificates should only be used in a secure environmentSince generating an OEM application license requires handling of the OEM certificate andits password, the process should only be carried out in an environment that is protectedagainst malicious software (protected PC), in order to prevent the password for the OEMprivate key being accessed by malicious software.

Signing of a License Request File, and therefore generation of a License Response File, is done inTwinCAT Engineering in the Security Management console [} 9].



1. Select your OEM certificate in the "Certificates" tab.

2. Click on "Sign License Request File".ð An Explorer window opens.

3. Select the License Request File to be signed (extension: *.tclrq).ð A password dialog opens.

4. Enter the password and click "OK".ð The License Request File is signed, and the result is stored as a License Response File (extension:

*.tclrs). The License Response File now has to be transferred back to the Engineering PC or the controlcomputer.

5.4.1.5 Importing License Response Files for an OEM application license

The OEM application license is activated in the same way as a standard TwinCAT 3 license. The simplestway to activate a TwinCAT 3 License Response file in TwinCAT 3 is to import it via the TwinCAT 3 licensemanager. For more information, see "Licensing" in the "Import License Response Files" section.



5.4.2 Querying the OEM application license in a PLC application

Note

TwinCAT 3.1 Build 4022 or higher and PLC Lib: Tc2_Utilities Version 3.3.24.0This function requires TwinCAT 3.1 Build 4022.0 or higher and the PLC Lib: Tc2_UtilitiesVersion 3.3.24.0. The Tc2_Utilities library is part of the standard TwinCAT 3 installation.

When the TwinCAT 3 Runtime starts, TwinCAT 3 automatically checks for valid licenses. The result can beretrieved with function block FB_CheckLicense.

FB_CheckLicense

The function block determines the TwinCAT 3 license status for a given license ID.

VAR_INPUTVAR_INPUT bExecute : BOOL; tTimeout : TIME; sNetId : T_AmsNetId; stLicenseId : GUID;END_VAR

bExecute: The function block is activated by a positive edge at this input.

tTimeout: Timeout time that must not be exceeded when the command is executed.

sNetId: AmsNetId (AMS network identifier) of the TwinCAT computer whose license status is to be read(type: T_AmsNetId). If it is to be run on the local computer, an empty string can be entered.

stLicenseId: License ID (type: GUID)

VAR_OUTPUTVAR_OUTPUT bBusy : BOOL; bError : BOOL; nErrorId : UDINT; stCheckLicense : ST_CheckLicenseEND_VAR

bBusy: TRUE, as long as the function block is active.

bError: TRUE if an error occurs during command execution.

nErrorId: Supplies the ADS error number when the bError output is set.

stCheckLicense: Structure with license data (type: ST_CheckLicense [} 46])

STRUCT ST_CheckLicenseTYPE ST_CheckLicense :STRUCT stLicenseId : GUID; tExpirationTime : TIMESTRUCT; sExpirationTime : STRING(80); eResult : E_LicenseHResult; nCount : UDINT;END_STRUCTEND_TYPE



Name DescriptionstLicenseId License IDtExpirationTime Expiry datesExpirationTime Expiry dateeResult License status (see E_LicenseHResult [} 47])nCount Number of instances for this license (0=unlimited)

ENUM E_LicenseHResultTYPE E_LicenseHResult :( //success E_LHR_LicenseOK : DINT := 0, E_LHR_LicenseOK_Pending : DINT := 16#203, E_LHR_LicenseOK_Demo : DINT := 16#254, E_LHR_LicenseOK_OEM : DINT := 16#255, //error E_LHR_LicenseNoFound : DINT := DWORD_TO_DINT(16#98110700+16#24), E_LHR_LicenseExpired : DINT := DWORD_TO_DINT(16#98110700+16#25), E_LHR_LicenseExceeded : DINT := DWORD_TO_DINT(16#98110700+16#26), E_LHR_LicenseInvalid : DINT := DWORD_TO_DINT(16#98110700+16#27), E_LHR_LicenseSystemIdInvalid : DINT := DWORD_TO_DINT(16#98110700+16#28), E_LHR_LicenseNoTimeLimit : DINT := DWORD_TO_DINT(16#98110700+16#29), E_LHR_LicenseTimeInFuture : DINT := DWORD_TO_DINT(16#98110700+16#2A), E_LHR_LicenseTimePeriodToLong : DINT := DWORD_TO_DINT(16#98110700+16#2B), E_LHR_DeviceException : DINT := DWORD_TO_DINT(16#98110700+16#2C), E_LHR_LicenseDuplicated : DINT := DWORD_TO_DINT(16#98110700+16#2D), E_LHR_SignatureInvalid : DINT := DWORD_TO_DINT(16#98110700+16#2E), E_LHR_CertificateInvalid : DINT := DWORD_TO_DINT(16#98110700+16#2F), E_LHR_LicenseOemNotFound : DINT := DWORD_TO_DINT(16#98110700+16#30), E_LHR_LicenseRestricted : DINT := DWORD_TO_DINT(16#98110700+16#31), E_LHR_LicenseDemoDenied : DINT := DWORD_TO_DINT(16#98110700+16#32), E_LHR_LicensePlatformLevelInv : DINT := DWORD_TO_DINT(16#98110700+16#33))DINT;END_TYPE

Value MeaningE_LHR_LicenseOK License is validE_LHR_LicenseOK_Pending Validation of the licensing device (e.g. License Key Terminal)

requiredE_LHR_LicenseOK_Demo Trial license is validE_LHR_LicenseOK_OEM OEM license is validE_LHR_LicenseNoFound Missing licenseE_LHR_LicenseExpired License expiredE_LHR_LicenseExceeded License has too few instancesE_LHR_LicenseInvalid License is invalidE_LHR_LicenseSystemIdInvalid Incorrect system ID for the licenseE_LHR_LicenseNoTimeLimit License not limited in timeE_LHR_LicenseTimeInFuture License problem: Time of issue is in the futureE_LHR_LicenseTimePeriodToLong License period too longE_LHR_DeviceException Exception at system startupE_LHR_LicenseDuplicated License data read multiple timesE_LHR_SignatureInvalid Invalid signatureE_LHR_CertificateInvalid Invalid certificateE_LHR_LicenseOemNotFound OEM license for unknown OEME_LHR_LicenseRestricted License invalid for the systemE_LHR_LicenseDemoDenied Trial license not allowedE_LHR_LicensePlatformLevelInv Invalid platform level for the license



Determining the license ID of the OEM license

The license ID of the OEM license can be obtained from the corresponding license description file or thelicense manager.

License description file:

"Manage Licenses" tab of the license manager:

Double-clicking on the row containing the license line opens a window showing the license properties,including the license ID:

The OEM can specify in their PLC application how the system should respond to the presence or absence ofthe OEM application license. Options include program termination or activation of an additional feature.



5.4.3 Storing OEM application licenses on a dongleThere are two options for storing an OEM application license on a license dongle, which are described in theTwinCAT 3 licensing section:

• Saving license files manually on the dongle• PLC function blocks relating to the storage function of the license dongles

5.5 Displaying an overview of the project's securitymanagement settings

You can display the security management settings of the project in the output window of the TwinCAT 3development environment.

Prerequisite for this functionality is TwinCAT 3.1 Build 4022.0.

Select the root node of the PLC project in the Solution Explorer, and select the command "Show SecuritySettings Overview" in the context menu.

The output window displays a summary of the project's current security settings.



Documents

Manual Security Management - Beckhoff€¦ · Foreword Security Management Version: 1.55 1 Foreword 1.1Notes on the documentation This description is only intended for the use of