License Event Handling in Protected Applications

CodeMeter Protection Suite enables simple encryption of applications, but what happens if a license is missing? With the CPSEvents interface, error messages can be customized, and additional functions like license selection or error handling can be integrated.

Thanks to the various AxProtector tools within CodeMeter Protection Suite, encrypting an application is quick and easy; even beginners can do it in just a few minutes. Technically, everything runs smoothly as long as the required license for your application is available. The application starts as usual, perhaps with a slight delay, but the user doesn’t notice any difference. But what happens if the license is not available?

In that case, a CodeMeter error message will appear. However, this message often differs from the usual application error messages, which may cause confusion for users. Clarity and a consistent appearance are crucial to ensure that CodeMeter is recognized as an integral part of the delivered software.

For many years, Wibu-Systems has offered the UserMessage interface for all versions of AxProtector. This allows error messages to be displayed in different languages by simply modifying .ini files. A custom background graphic can also be added, ensuring that the error message visually fits the design of your application.

As an alternative to the standard UserMessage library, which is limited to displaying on Windows, there is the option to create your own DLL. This enables you to integrate additional functionalities, such as displaying all available licenses on the network for user selection or assigning licenses to the same CmContainer for applications with multiple components.

CPSEvents in AxProtector NC

The new generation of AxProtector tools, marked with “NC” for “Native Core,” uses a similar but modernized mechanism. In this case, CodeMeter Protection Suite Runtime (CPSRT) handles license verification and decryption within a tamper-resistant environment. This enables protection for scripting languages and also provides optimized management of multiple concurrently running protected applications.

In CPSRT, all error handling is centrally managed. If an error occurs, CPSRT calls the corresponding CPSEvents library via the CPSEvents interface. Here again, you have two options:

Complete Package

Wibu-Systems provides a ready-made CPSEvents library that displays graphical dialogs across platforms. These dialogs are rendered as HTML pages using a minimal browser (Webview). On Linux, the libraries libgtk-3 and libwebkit2gtk-4 must be installed on the system to enjoy this functionality.

Graphical Customization

In the YAML configuration file for encrypting the application, you specify a path to a separate YAML configuration file for dialog customization. In this file, you can modify the appearance by specifying your own CSS definition file and adjust all texts through definitions. Additionally, you can replace the logo with your own, essentially making all the changes necessary to ensure that the dialog looks exactly as your customers are accustomed to from your applications.

Secure Delivery

At the time of encryption, the standard CPSEvents library is placed alongside your encrypted application, with a filename that includes your Firm Code at the end. This ensures that CPSEvents libraries are uniquely associated with each software vendor and do not interfere with each other during runtime.

The configuration you create is embedded into the protected application, making it tamper-proof. During runtime, CPSRT loads the corresponding CPSEvents library and transmits these configuration settings.

Custom Solution

As a second option, you can, similar to the previous UserMessage library, create your own CPSEvents library. The interface is openly documented, allowing you to integrate custom functionalities for error handling or license management. You implement this library on all the platforms you support, and you can execute your own code during error handling or before license allocation.

Using the function CpsGetLicenseAccess-Filter, you receive a list of licenses relevant to the current request. AxProtector manages access via so-called LicenseLists, which can contain multiple licenses. Your library receives this list, enabling you to influence the license selection. For example, you can ensure that a specific DLL uses the same CmContainer as the loading application by storing the serial number and setting the filter accordingly. CPSRT evaluates these filters and attempts to allocate the license according to your specifications.

Events

After each successful license allocation, the CpsOnEvent function informs you of the event LicenseAccessed and provides detailed information about the allocated license. You can use this information for further license queries, such as using it as a filter parameter for additional LicenseLists, as described above. You can even deny access to a license if certain criteria are not met.

Other event types in the CpsOnEvent function include LicensingError, Tampering-Detected, and AccessFilterError. For instance, in the case of a licensing error, you can display a dialog allowing the user to retry the license request.

For applications without user interaction, you can write a CPSEvents library that automatically attempts to allocate a license again after a specific waiting period or sends alternative system responses. Alternatively, you can implement a callback and use the dialogs in your programming language.

Secure Data Transfer

Even with a custom-made CPSEvents library, application-specific data can be embedded and passed to the CPSEvents library at runtime. During the encryption process, you specify a file as UserData. This data is stored as a binary blob within the encrypted application and is then passed to the CPSEvents library at runtime. This allows you to include application-specific data when using a CPSEvents library.

The integrity protection of AxProtector NC prevents tampering and the replacement of the CPSEvents library. If this protection is disabled in certain cases, it can be selectively activated just for the CPSEvents library.

With the new mechanisms in AxProtector NC and the CPSEvents interface, CodeMeter Protection Suite offers a flexible and secure way to seamlessly integrate error and license management into your application. You retain full control over the design and functionality of error messages while ensuring that license management works smoothly.

KEYnote 48 - Edition Fall/Winter 2024