The AxProtector option '-a' was used in the past to place the AxEngine at a previously reserved area during encryption.
This was necessary when the application did not provide enough space to accommodate the AxEngine.
Since AxProtector version 10.20 this option is no longer supported. An alternative way to still add the AxEngine to an application is described in KB-0322.
AxProtector offers various options for debugging protected applications.
AxProtector Option -cce
To examine a dump file of an encrypted application/dll compared to the original code, you should use the AxProtector -cce option when encrypting to preserve the storage addresses.
In most cases, using the AxProtector -cce option is sufficient.
AxProtector Option -ccn
The AxProtector Option -ccn is necessary to debug a protected application. For this purpose the "Structure Exception Handling" is switched off during debugging. For security reasons, however, you can only use the AxProtector option -ccn, if you have a corresponding license in your FSB (Firm Security Box). This license is available from Support on request.
Please make sure that all anti-debugger mechanisms are disabled when encrypting with AxProtector. Use the -cag0 option to do this.
For security reasons, you should only use an application encrypted with the -ccn option for tests in your company and never give it to third parties. To avoid this, we recommend not to use the -ccn option.
Using an encrypted "fat binary", i.e. an application that contains 32-bit and 64-bit components, can cause problems on macOS.
The application should be split for use/encryption to create "pure" 32-bit applications and pure 64-bit applications.
Wibu-Systems recommends to perform the encryption with AxProtector.
More precise: use the AxProtector GUI user interface to define the encryption parameters that will be used to call the actual AxProtectors.
Our AxProtectors are all pure command line programs.
For example, to automate the encryption process, you can export the encryption parameters to a file <ExportedFile> via the menu "File | Export" of the AxProtector GUi.
Then you can use the AxProtector @<ExportedFile>.wbc parameters to perform the encryption via command line, batch call, post build event in Visual Studio, etc.
The procedure for encrypting .NET assemblies or Java 'Jar' files is identical to AxProtectorNet.exe @<ExportedFile>.xml or java -jar AxProtector.jar @<ExportedFile>.xml.
You should make further changes to the encryption parameters in your AxProtector project via the AxProtector GUI and preferably test them with it.
Then you can simply export the encryption parameters again.
If you use the same options for different files, you can also customize the XML and delete the last two parameters regarding the source/destination file and add them to the command line:
-cas Specifies the size of the protected application to be encrypted. You enter the length in percent from 0 to 100%.
-# This option stands for automatic output to the AxProtector.log [//Documents and Settings\User] file.
-car30,3 Adds a runtime check to the automatic encryption.
-v Enables verbose mode.
-o Specifies the path and name of the encrypted target file.
Please proceed as follows:
1. Export the created AxProtector project.
You will receive a *.wbc file.
2. Edit the file, i.e. add functions or DLLs to be
[WIBU-SYSTEMS Control File]
3. Calling AxProtector with adjusted
AxProtector parameters of the *.wbc file, e.g.
If you want to create your own UserMessage.dll, you find the required information in the attached PDF document.
A simple example of a self-generated UserMessage.dll can be found for C++ as "UserMessage | UserMessageSimpleGUI" and for C# as "UserMessage | UserMessageSimple" since CodeMeter version 6.80 in our examples in the CodeMeter Software Development Kit (SDK).
If you want to use the UserMessage without *.ini files, we recommend that you use this example as a template.
The source code of the standard UserMessage.dll, which uses *.ini files, can also be found in our examples, for C++ as "UserMessage | UserMessage" and for C# as "UserMessage | UserMessage".
To customize the license error handling, please proceed as follows depending on your AxProtector:
AxProtector Windows & AxProtector .NET
1. Go to the "Error messages" tab in the AxProtectorGUI.
2a. In AxProtector Windows select the option "User Message DLL" and keep the default file name (-u: "UserMsg").
2b. In AxProtector .NET select the option "Inline messages" (-ui).
3. After encryption, the target directory of the encrypted application will also contain
UserMessage *.ini files for different languages.
4. Adjust and change the UserMessage.ini file:
5. Optionally, you can also adjust the retry behavior:
1. Select in AxProtectorGUI in the tab "Error messages" the option "User Message Class".
2. Enter class name 'com.wibu.xpm.MessageHandler' (-u: "com.wibu.xpm.MessageHandler").
To prevent the pop-up of the MessageBoxes in case of errors in AxProtector (e.g. no FSB found), please proceed as follows:
- Copy the two files UserMsgUs.dll and UserMessage.ini from the directory C:\Program Files (x86)\WIBU-SYSTEMS\AxProtector\Devkit\bin\UserMessage to the directory from which you are using AxProtector (default "C:\Program Files (x86)\WIBU-SYSTEMS\AxProtector\Devkit\bin)
- Open the UserMessage.ini configuration file
- Edit the following entries in the [Service] section
; Destination for log files - current user requires write privileges to that directory
; Gui=off should be set to disable message boxes and redirect error messages to log files
This activates the GUI interface and logging. No more graphical error messages are displayed.
Encrypting may produce arbitrary patterns, and, as a result, an anti-virus program may detect these as a potential virus.
You may check the settings of the anti-virus program. Eventually, very strict settings or additionally advanced options are the reason for the virus detection.
Moreover, you may declare the application an exception in the respective anti-virus program.
You may send your application to the respective anti-virus software vendor to allow the next update of the anti-virus program to skip the detection. However, the next application or a new version may be affected again.
Virus scanner evaluate applications according to specific behavior patterns or anomalities. Usually, a scoring system applies.
The details which behaviour patterns are detected, how these are weighted and what the threshold is when an application is regarded a virus is the secret of the anti-virus software vendor. Sure enough the protection mechanism used in encrypting add some points to the score, as confering with anti-virus software vendors shows. Viruses use exactly these mechanisms to mask themselves. This explains why thresholds are quickly reached and why protected applications, in particular, are often declared as false positives.
There are also possibilities to collect plus points in this scoring system, e.g. if the manufacturer signs an application with Authenticode, this has a positive effect. The risk of virus classification is thus significantly minimized, but there is no 100% guarantee of correct classification.
To test IP Protection (exclusive protection without licensing), you need an additional license in your Firm Security Box (FSB): 100021:1600. This license is available as a demo version on request from the sales team (email@example.com).
Further information about IP Protection can be found in the CodeMeter developers guide: "Automatic Software Protection using AxProtector (Tool of CodeMeter Protection Suite)| Advanced AxProtector Options |IP Protection - protecting know how ".
The options described under "Usage" are entered in the *.wbc file that is exported from the AxProtector GUI.
The appendix explains how the *.wbc file might look if the entire application is encrypted using IP Protection.
If the UserMessage dialog displays without an image, the following reasons may apply:
- The image file specified in the UserMessageXX.ini does not exist.
- The image used has the wrong dimensions. The image must be 160*385 pixels in size.
- The used image has a bit depth unequal to 24 bit.
To use WupiData, a HiddenData field without dependencies must be programmed into the CmContainer.
By default, a Product Item Option has dependencies whose values must be known so that the programming sequence for updating the Product Item Option can be calculated. The default dependencies are dsu (data, serial, update counter).
Therefore, a programming sequence can normally only be used to change exactly this Product Item Option in its current state in the target container. If the Firm Item in the target container is changed and the update counter increments, this programming sequence will no longer work.
By removing these dependencies AxProtector is able to pre-calculate a general valid programming sequence for the Hidden Data field target. This can then be imported at runtime to any CmContainer with any data. This makes it possible to write data at runtime.
The command line tool CmBoxPgm has a special option (-pwupidata) to program HiddenData for the use of WupiData which can be used:
Allocates <size> bytes of WUPI Data storage, initialized with the value <fill byte>.
Alternatively, you can also program with the Programming API (HIP). In this case, HiddenData must be explicitly programmed without dependencies. Programming without dependencies is currently not possible with CodeMeter License Central or CodeMeter License Editor.
When encrypting your application, you must then create a license list with the same Product Code and configure WupiData there. It is important that the same HiddenDataAccessCode (HDAC) is used for programming and encryption. If you omit this code when programming and encrypting, it is automatically stored in the background and should also be identical but unknown. If you set an HDAC explicitly, you can use it later to read HiddenData also via the CodeMeter Core API. If you only plan to use the WUPI API, this is not mandatory.
In the code you can then use the WUPI API functions WupiReadData and WupiWriteData to read or write data.
Note: The WUPI API only works after the code has been encrypted. Before that, the WupiEngine uses only a dummy implementation, so there are no errors.
Enclosed you will find a small example project for the use of WupiData.