Getting Started

Overview.

This document consists of the following sections.

Introduction,
The Processing Sequence,
Using the GUI,
Creating your first ZKM Script,
Executing your first ZKM Script and
Which obfuscation options to use.

Introduction.

This document assumes that you have Zelix KlassMaster™ installed successfully. If you do not yet have Zelix KlassMaster™ running then see the Installation document.

Zelix KlassMaster™ has two interfaces - the GUI interface and the command line ZKM Script interface. The GUI interface is provided as a way of quickly becoming familiar with the basic concepts of obfuscation and as a way of creating a simple ZKM Script. The ZKM Script interface is ultimately the preferred interface because it

is more suited to the task of repeated obfuscation than is the GUI interface,
is less prone to human error,
provides extra functionality that is not available through the GUI interface,
allows you to integrate the obfuscation step into an automated build process and
allows us to exchange ZKM Scripts with you which makes the support process much, much easier.

It is highly recommended that you open your classes for obfuscation using the same relative directory and/or archive structure that will be used at runtime. If you do this then your obfuscated application can be deployed in exactly the same way as the original, unobfuscated application.

The Processing Sequence.

The basic Zelix KlassMaster™ processing sequence is as follows.

Set the classpath that Zelix KlassMaster™ should use, (GUI | ZKM Script)
Open the classes that you wish to obfuscate, (GUI | ZKM Script)
Set your Trim exclusions, (GUI | ZKM Script)
Set your Trim options and perform the trimming, (GUI | ZKM Script)
Set your name obfuscation exclusions, (GUI | ZKM Script)
Set your obfuscation options and obfuscate, (GUI | ZKM Script)
Save your obfuscated classes. (GUI | ZKM Script)

Using the GUI.

You start the Zelix KlassMaster™ GUI by executing the Zelix KlassMaster™ JAR file without specifying a ZKM Script as the final command line option. As mentioned above, the GUI interface is provided as a way of quickly becoming familiar with the basic concepts of obfuscation and as a way of creating a simple ZKM Script.

When you are getting started, it is recommended that you use the Build Helper tool which is in the "Tools" menu. The Build Helper will guide you through the basic steps of trimming and/or obfuscating your classes.

It is highly recommended that you do not use the Trim function until you have your obfuscated application working. The Trim function can be more difficult to understand than obfuscation so it can help if you use it only when everything else is working. In the Build Helper, you can postpone the use of the Trim function by clicking on the

button on the Trim Exclusions and Trim Options windows.

Creating your first ZKM Script.

You can create a basic ZKM Script by using the GUI Build Helper or the ZKM Script Helper tools. (The difference between the two is that the Build Helper actually performs the class processing in the background before giving you the opportunity to save the corresponding ZKM Script.) At the end of the Build Helper process you will see the

button which will allow you to view and then save the equivalent ZKM Script.

Once your ZKM Script is saved as a text file, you are free to then edit it using any simple text editor. Note that you cannot open a saved ZKM Script within the GUI Build Helper or the ZKM Script Helper tools. This is because ZKM Scripts can become arbitrarily complex and because they can contain functionality which is not supported by the GUI.

First time users are sometimes initially puzzled by the ZKM Script exclusion syntax. This is because ZKM Script gives you very fine control over what is or isn't excluded. Therefore, it is highly recommended that you at least read the basic exclusions part of the ZKM Script Exclusions Tutorial before modifying your first ZKM Scripts. It actually isn't that complicated so it could save you a lot of trial and error.

Executing your first ZKM Script.

You can execute your saved ZKM Script from the command line or from within a build tool.

If you find yourself needing to debug your ZKM Script then you may find it helpful to run Zelix KlassMaster™ using the "-v" (ie. verbose) command line option. This will result in a great deal of extra information being written to the Zelix KlassMaster™ log file which is named ZKM_log.txt by default. This extra information will include

the effective exclude parameters (including the default exclusions) and
which classes, fields or methods were directly matched by a particular exclusion parameter.

Which obfuscation options to use.

Obfuscation of even a mildly complicated application is not trivial. For this reason it is highly recommended that you start by using minimal obfuscation. Once you have your minimally obfuscated application working satisfactorily then you can iteratively increase the level of obfuscation.

A safe way to start is by excluding all public classes and all public and protected fields and methods from Name Obfuscation. These are the recommended settings for an application which is an extensible framework but it is otherwise a relatively safe starting point for all applications. Using ZKM Script you can do this by using the following ZKM Script exclude statement.

exclude 
   public *.^* and  //exclude names of public classes & containing packages
   *.* public * and  //exclude public field names
   *.* protected * and  //exclude protected field names
   *.* public *(*) and  //exclude public method names
   *.* protected *(*)  //exclude protected method names
   ;

Also, as mentioned above, it is highly recommended that you do not use the Trim function until you have your obfuscated application working. Once your obfuscated application is working you will find that your ZKM Script exclude statement exclusion parameters will provide an excellent guide to the necessary ZKM Script trimExclude statement parameters.

Once you have your obfuscated application working satisfactorily, you should seriously consider using the Method Parameter Changes functionality. This functionality is essential if you wish reduce the risk of the String Encryption and Reference Obfuscation transformations being reversed. It also offers it own special form of Flow Obfuscation which is more difficult to reverse.

Otherwise, see the answer to FAQ question 14 for guidance on the other obfuscation settings.

Privacy

Refunds