Example Code

ExamplePrograms · ‎07-18-2008

Description

Overview

Adding licensing to a LabVIEW Real-Time application can protect a deployed application from being copied and run on another similar or identical set of hardware without obtaining a license from the vendor or distributor of the application. Most modern day applications running on desktop computers are protected by a license key which is necessary to either install the application or run it in its normal operational mode. Many vendors use license keys to determine if an application runs in demo mode or is fully functional. License keys may also be used to differentiate between different versions of an application or to enable/disable specific features. This behavior can be added to a LabVIEW Real-Time application using the reference design and attached example code described in this tutorial. There are many different options for adding licensing to a LabVIEW application and this article describes only one possible method for this purpose. This article only addresses the technical aspect of creating license keys and using them to protect a deployed application. It does not address the legal aspects of defining and enforcing a licensing policy for your application.

rt_app_license_102.zip contains the reference examples for this tutorial, which can be installed by unzipping the file into an empty folder on your hard drive.

The reference examples use the CompactRIO Information (CRI) component, which must be installed on your system before opening the reference examples. If you use the reference examples in rt_app_license_102.zip you must install the CRI component separately.

rt_app_license_102_install.zip contains a Windows installer which will install the reference examples and the CRI component in the LabVIEW directory on your hard drive. Unzip the ZIP file in an empty folder and run setup.exe. If you run this installer you do not need to download and unzip rt_app_license_102.zip.

Feedback and Comments

Please provide feedback, comments or questions to this reference design using the associated discussion forum.

Purpose

The purpose of adding licensing to a LabVIEW Real-Time application for the context of this article is to protect the deployed application from being run on another set of hardware without the knowledge and permission of the application developer or vendor. Obtaining permission to run an application on a new target usually consists of obtaining or purchasing a new license and associated license key which unlocks the application on the new hardware target.

The reference examples included with this article as well as the discussion in the article focus on adding licensing to a CompactRIO-based LabVIEW Real-time application. This reference design can be applied to other LabVIEW Real-Time targets as well as other LabVIEW targets with some modifications. The main modification will be in the manner of creating a unique system ID for a specific hardware target. In the case of CompactRIO we use the controller, backplane, as well as module serial numbers. For other targets you may use the serial number or Ethernet MAC address of a given target to create a unique system ID.

Choosing a License Model

The license model defines how the license key is generated based on particular characteristics of the target hardware. One simple example of a license model is to base the license key on the serial number of the controller. In this case the application will run if the controller has the serial number matching the license key provided. If the controller serial number does not match the license key, the application will not run.

If the hardware target includes additional components such as a CompactRIO backplane, and CompactRIO modules you may choose to lock the application not only to the controller, but also to these additional components of the system. In this case the license key can be linked to the serial numbers of all these components of the hardware target. In this case all components with the correct serial numbers must be in place to run the application.

The unique characteristics of the hardware target (e.g. serial number) is called the system ID for the purpose of this article.

One example of a more complex license model is to base the license key on the serial numbers of multiple system components, but only require some of these components to be present when running the licensed application. This would allow the application user to replace some of the system components, in case a repair is required, without needing to acquire a new application license key. The number of components linked to the license key that must be present in order to run the application is defined by the developer as part of the license model.

Application Licensing Process

Adding licensing (creating and using a license key) to a LabVIEW Real-Time application consists of the following steps:

Create a unique system ID for each deployed hardware target
Create a license key based on the system ID
Store the license key on the hardware target
Verify the license key during application startup

Create a unique system ID for each deployed hardware target

In order to create a license key for a specific hardware target we first must create a unique system ID. The system ID is a number or string which uniquely identifies a specific hardware target based on the physical hardware itself. The licensed application is locked to the hardware target using the license key which is linked to the system ID. The system ID can be a number such as the serial number of the target, or a value which is a combination of each of the system component's serial numbers. Another source for a system ID can be the MAC (Media Access Control) address stored in every Ethernet interface chipset. The reference example uses the CompactRIO Information (CRI) SW component, which can be download from Developer Zone, to retrieve these different pieces of information from a CompactRIO system.

Figure 1: Block diagram showing the process of creating the license key

CompactRIO Controller, Backplane, and Modules Information

Using functions from the CompactRIO Information (CRI) component we can retrieve relevant information about the controller and other hardware of a CompactRIO system.

RT_Get_Info

Figure 2: Retrieving the cRIO controller and backplane information

RT_Modules_Get_Info

Figure 3: Retrieving cRIO modules information from a cRIO-9101 backplane

The CompactRIO Information (CRI) component includes a variety of VIs to retrieve information from a local CompactRIO system as well as a CompactRIO system connected over the network.

Example System IDs

Following is one possible example of generating a system ID for a four-slot CompactRIO system using these VIs. In this example the serial numbers for all six system components are added together. While this is not a truly unique value for a given CompactRIO system, it is unlikely that after replacing one or more system components, the sum of all the serial numbers will be the same as when the license key was generated.

Figure 4: Generating a system ID using serial numbers

There are many other possible ways to generate a system ID using these and other system characteristics.

Create a license key based on the system ID

Once a system ID has been created, we derive a license key from the system ID. The license key is a unique string which is linked to the system ID using an encryption algorithm. The goal is to create a string which can be verified against the system ID but can not be easily generated by the user for a different hardware target in order to disallow using the application on a different set of hardware.

There is a wide range of possible encryption algorithms that can be used for this purpose.

Encryption

The encryption used in the reference example is a version of the Hill Cipher which uses a simple matrix multiplication and a license key matrix. The matrix multiplication converts the input string into a different output string which can not be easily decrypted without knowing key matrix. The Hill Cipher is not considered to be a very strong encryption algorithm and is only one possible option to be used in generating a license key. You can easily replace the encryption subVI in the reference example with your own encryption tool. More information on the Hill Cipher can be found in various online references.

The encryption VI provided with the reference example converts the system ID using the Hill Cipher and a 3x3 key matrix (Encryption Key). The key matrix is the key to unlocking the license key. Therefore the key matrix value should be changed before using the reference example in a real world application. Not all 3x3 matrices are valid for use as a key matrix. The Hill Cipher Encryption VI will tell you if the chosen matrix is invalid. If it is invalid, try other values for your key matrix.

Figure 5: Encryption of the system ID into the license key

The encryption VI provides two versions of the license key. The default algorithm returns a stream of bytes which can have any value between 0 and 255. Therefore these bytes may not represent printable characters and may not be easily stored in a text file or passed along using other mechanism such as e-mail. In order to simplify the process of storing and transferring the license key the VI provides a hexadecimal version of the encrypted string made up of the ASCII representation of the hexadecimal value of each of the byte values in the original string. This string will be stored in a file as the license key.

Store the license key on the hardware target

The reference example stores the license key in a simple INI file on the CompactRIO controller hard drive.

Figure 6: Storing the license key in an INI file on the CompactRIO controller

If the license key and file are generated away from the actual CompactRIO system then the license file must be copied to the CompactRIO system when the application is deployed to the controller.

Verify the license key during application startup

When the deployed application is starting up it will need to verify the license key and based on the result of the verification process adjust its behavior according to the license model. If the license key is verified correctly the application will run in its normal, but if the key is not verified it may not run at all or run in an evaluation mode.

The reference example provide a basic verification VI that is added before the actual application.

Figure 7: Adding the license key verification to an application

There are two different methods to verify a license key. The first and preferred method is to recreate the license key on the target system and is described in this section. The second method consists of decrypting the license key and is described in the section 'Enabling Features Based on the License Key'.

The more basic and more secure method to verify the license key is to run the same algorithm as is used to create the license key on the target system and then compare the new license key with the license key stored in the license file. If the two match then the license key is verified and the application may run.

Figure 8: Block diagram to verify the license key stored in the file on the system

The previous diagram shows that this process is almost identical to the process of generating the license key. Instead of writing the license file however, the license file is read and compared to the newly generated license key.

Figure 9: Reading the license file and comparing the license key

This method of verifying the license key works well if we do not need any partial information from the license key such as information about enabling or disabling individual features or the individual serial numbers of system components. For licensing models that require more detailed information about the license key, the key itself must be decrypted as describe in a later section.

Generating a License Key Remotely

In some cases it is desirable to generate a license key separate from the target system which will be running the embedded application. This may be the case in an automated deployment system where an embedded application is deployed to many target systems in an automatic fashion. In this cases the deployment system will generate the license file as part of the deployment process without a user manually running a VI on the target to generate the license key and license file.

Another use case requiring a remotely generated license key may be a customer replacing part of her target system, such as the CompactRIO backplane, and now needing to receive a new license key to continue running the application.

To generate the license key for a remote target, the target system ID must be retrieved, provided to the application generating the license key, and then the license key file is returned to the target.

Retrieve and store the system ID
Send the system ID file to the license generator
Create a license key from the system ID
Return the license key file

The reference design includes several examples for this purpose.

The Get Remote System ID example can be used in the first scenario described above where the application or user has networked access to the target CompactRIO system. In this case a VI from the CompactRIO Information component is used to retrieve the system ID from the networked target system. The example stores the system ID in a file similar to the license key. The system ID could also be used directly to generate the license key and file. The license file would be written back to the target system using an FTP client.

For the second scenario the Get System ID example can be used to retrieve the system ID and store it in a file. This file can be e-mailed by the customer to the application vendor who can generate the license key file and send it back to the customer. Generating a license key from a system ID file is shown in the Create License Key from SystemID example.

Enabling Features Based on the License Key

More advanced licensing models may place more requirements on the licensing process. One such example is provided in the reference design for adding and enabling application features using the license key. This example uses the controller serial number as a basic system ID and then adds Boolean values (True/False) for eight features than can be enabled or disabled. The eight Booleans are converted into an integer and then represented by a hexadecimal string. The new system ID consists of the serial number and these eight Boolean values. Generating the license key from this system ID will encode the feature selections in the license key.

Figure 10: Generating a system ID with eight Boolean features

The license key is generated, stored, and distributed in the same manner as before.

Decrypting a License Key

In this type of license model it is necessary to decrypt the actual license key stored on the target system. The Hill Cipher Encryption VI provided with the reference design includes the code to decrypt a license key using the original key matrix. Running this algorithm returns the original system ID provided during the license key generation process.

Figure 11: Verifying a license key using decryption

After decrypting the license key and receiving the system ID we parse the system ID to extract the controller serial number and features selections. The controller serial number from the license key is compared to the target system serial number to verify the license. The features selection can then be used to enable and disable features in the application.

Figure 12: Decrypting the license key and returning the serial number and feature selections

The method shown in this example can be used to store any type of information in the license key such as version information, user name, etc. We can also store the individual serial numbers of the system components (controller, backplane, modules). During the verification process the individual serial numbers can be used to allow the application to run based on a partial set of valid serial numbers being present.

Using the concepts and code components shown in the examples and reference design you can add licensing to your LabVIEW Real-Time application in many different ways and can customize the licensing model and licensing process.