Zelix KlassMaster - Documentation

ProGuard Configuration File Translation Tutorial

This tutorial is divided into the following sections:

The Problem

The ProGuard obfuscator is an open source tool. Being open source and freely available, it is often the first obfuscator that a developer might use. However, ProGuard has only limited features. For example, it does not provide Flow Obfuscation, Exception Obfuscation, AutoReflection™ or String Encryption.

So the situation can arise where a ProGuard user may wish to migrate to Zelix KlassMaster™. This means that they need to translate their existing ProGuard configuration files to ZKM Script.

Also, ProGuard has been built into a number of build environments which have not provided an alternative, generic obfuscator interface. The Android™ Development Tool plugin (ADT) for Eclipse is an example of such a tool. So it would be convenient if a developer wishing to use Zelix KlassMaster™ rather than ProGuard could do a transparent swap.

The Solution

Zelix KlassMaster™ provides broad support for ProGuard configuration files. It does this by translating ProGuard configuration files into ZKM Script on the fly. So you can execute a ProGuard configuration file using Zelix KlassMaster™ just as you would if it was a ZKM Script file.

Incidentally, you can also translate a ProGuard configuration file into ZKM Script using the ProGuard Configuration File Translation Tool.

Output Files

Zelix KlassMaster™'s log files to do not map cleanly to ProGuard's output files. See the table directly below.

Zelix KlassMaster™ file Closest ProGuard file Comment
ZKM_PG_log.txt none This special a log file which Zelix KlassMaster™ uses to write messages relating to the translation of a ProGuard configuration file. It will always be named "ZKM_PG_log.txt". It will be written to the directory specified by the ZKM_DEFAULT_DIR configuration option if it has been set or otherwise the directory specified by the user.dir property in the System properties.
ZKM_log.txt seeds.txt ProGuard has no direct equivalent of Zelix KlassMaster™'s log file. However, a verbose "ZKM_log.txt" file does contain the details of what is matched by the various exclusion statements.

In the context of ProGuard configuration file translation, the name and location of this log file will be set by the ProGuard -printseeds option if it exists. Otherwise, it will be named "ZKM_log.txt" and it will be written to the default directory.
ZKM_TrimLog.txt usage.txt Lists used classes, fields and methods that have been trimmed

In the context of ProGuard configuration file translation, the name and location of this log file will be set by the ProGuard -printusage option if it exists. Otherwise, it will be named "ZKM_TrimLog.txt" and it will be written to the default directory.
ChangeLog.txt mapping.txt Lists the mapping of old class, field and method names to obfuscated names

In the context of ProGuard configuration file translation, the name and location of this log file will be set by the ProGuard -printmapping option if it exists. Otherwise, it will be named "ChangeLog.txt" and it will be written to the default directory.

In the context of ProGuard configuration file translation, the default directory is determined in the following fashion. It has the value of
  • The ZKM_DEFAULT_DIR configuration option if it has been set or otherwise,
  • The -basedirectory option in the ProGuard configuration if it has been set or otherwise,
  • The directory specified by the first encountered -printseeds, -printmapping or -printusage option in the ProGuard configuration if it any have been set or otherwise,
  • The directory specified by the user.dir property in the System properties.

Compatibility

As mentioned above, Zelix KlassMaster™ provides broad support for ProGuard configuration files. However, it doesn't support all ProGuard configuration options. When Zelix KlassMaster™ encounters one of the following options it will simply ignore them after reporting a warning. Similarly, if Zelix KlassMaster™ encounters some aspect of a supported ProGuard option which it doesn't FULLY support then it will again report a warning.

Not supported
-adaptclassstrings
-adaptresourcefilecontents
-adaptresourcefilenames
-allowaccessmodification
-assumenosideeffects
-classobfuscationdictionary
-dontnote
-dontoptimize
-dontskipnonpubliclibraryclasses
-skipnonpubliclibraryclassmembers
-dontwarn
-dump
-forceprocessing
-ignorewarnings
-keepdirectories
-mergeinterfacesaggressively
-obfuscationdictionary
-optimizationpasses
-optimizations
-packageobfuscationdictionary
-skipnonpubliclibraryclasses
-target
-useuniqueclassmembernames

Not directly supported
-microedition
-printconfiguration
-renamesourcefileattribute
-whyareyoukeeping

Customizing Certain Statements

Zelix KlassMaster™ will construct a ZKM Script based upon the ProGuard configuration options which it is given. However, this will give you just basic trimming and obfuscation without using any of Zelix KlassMaster's special obfuscation features. You will often want to customize certain constructed ZKM Script statements with an alternative statement or to add extra ZKM Script statements for which there is no ProGuard equivalent.

You can do this by putting the customizing or additional ZKM Script statements into a file named "ZKMScript.txt". Zelix KlassMaster™ will only process the following statements in the "ZKMScript.txt" file. All others will be ignored.
If a customizing classpath statement is found then all paths that it specifies will be appended to the end of the classpath specified by the ProGuard configuration. In all other cases, the customizing statement will override any equivalent configuration in the ProGuard configuration.

Zelix KlassMaster™ will look for the "ZKMScript.txt" file in the following directories.
  • In the directory specified by the ZKM_DEFAULT_DIR configuration option if it has been set,
  • In the directory specified by the -basedirectory option in the ProGuard configuration if it has been set,
  • In the directory specified by the first encountered -printseeds, -printmapping or -printusage option in the ProGuard configuration if it any have been set,
  • Finally, in the directory specified by the user.dir property in the System properties.

Zelix KlassMaster™ adds the following three convenience properties to the System properties that you are able to use as system variables in your customizing ZKM Script statements in addition to the System user.dir property.

PROGUARD_LOG_DIR The absolute directory specified by the ProGuard -printseeds, --printusage or -printmapping command if present. Otherwise it will the directory specified by the ProGuard -basedirectory command if present. Otherwise it will the directory specified by the System user.dir property.
ZKM_LOG_DIR Same as PROGUARD_LOG_DIR except that the ZKM_DEFAULT_DIR System property if it is present will take precedence over the ProGuard -basedirectory command if present.
PROGUARD_SAVE_DIR The absolute directory specified by the first ProGuard -outjars command if any are present.

Example ZKMScript with customizing statements

The contents of a basic example ZKMScript file appears below. It contains just a ZKM Script obfuscate statement. It specifies light flow and exception obfuscation with relatively safe settings and that Strings should be encrypted. Note that it makes use of the PROGUARD_LOG_DIR System property mentioned above.
//Start ZKMScript.txt with customizing statements
obfuscate   keepGenericsInfo=false
            keepInnerClassInfo=false
            methodParameters=keepVisibleIfNotObfuscated 
            changeLogFileOut="%PROGUARD_LOG_DIR%\ChangeLog.txt"
            obfuscateFlow=light
            encryptStringLiterals=flowObfuscate
            exceptionObfuscation=light 
            autoReflectionHandling=none 
            obfuscateReferences=none
            randomize=true 
            preverify=false
            mixedCaseClassNames=false
            keepBalancedLocks=true
            ;
//End ZKMScript.txt
		 

How to use Zelix KlassMaster™ in an environment expecting ProGuard

If the environment calls ProGuard through a batch or shell script file then you could directly edit that file to point to Zelix KlassMaster™ instead. That is, a reference in the file to proguard.jar could simply be replaced with a reference to ZKM.jar. Of course, you should back up the file before editing it and you would need to ensure that ZKM.jar can be found.

For example

call java -jar proguard.jar %*

would become

call java -jar ZKM.jar %*

Another option in the same scenario would be to replace the original proguard.jar with a dummy version which simply calls Zelix KlassMaster™. For example, you could replace proguard.jar with proguardStub.jar. Again, you should back up the original proguard.jar before replacing it and you would need to ensure that ZKM.jar is in the the same directory as proguardStub.jar.

If you need to replace ProGuard in an Apache Ant build XML then, as mentioned above, you could replace the reference to proguard.jar with proguardStub.jar. You can also simply change the reference to proguard.ant.ProguardTask to com.zelix.ZKM_PG_Task but note that com.zelix.ZKM_PG_Task does not support the more complicated and verbose XML configuration. Again you would need to ensure that ZKM.jar is in the classpath so that com.zelix.ZKM_PG_Task can be found.

In either case, you should back up the original build XML before editing it,

How to use Zelix KlassMaster™ with the Android™ Development Tool

The Eclipse ADT plugin calls ProGuard via the <SDK>\tools\proguard\bin\proguard.bat file in Windows™ or the <SDK>/tools/proguard/bin/proguard.sh file in Linux. These files can be directly edited to specify ZKM.jar rather than proguard.jar.

How to use Zelix KlassMaster™ with the Android™ Studio

The Android™ Studio downloads ProGuard via Maven and it stores that ProGuard files in the <Android Studio>\gradle\m2repository\net\sf\proguard\proguard-base\<proGuardVersion> directory. So if the studio is using ProGuard 5.1 it will be in a directory named <Android Studio>\gradle\m2repository\net\sf\proguard\proguard-base\5.1. To use Zelix KlassMaster™ rather than ProGuard in this scenario you
  • Rename the original <Android Studio>\gradle\m2repository\net\sf\proguard\proguard-base\5.1\proguard-base-5.1.jar JAR file just so that you have it backed up,
  • Download the proguardStub.jar JAR to <Android Studio>\gradle\m2repository\net\sf\proguard\proguard-base\5.1 and rename it to proguard-base-5.1.jar
  • Put your ZKM.jar JAR file into the <Android Studio>\gradle\m2repository\net\sf\proguard\proguard-base\5.1 directory.

Obviously, if your installation of Android Studio uses a different version of ProGuard then you would need to use the corresponding directory names and JAR file name.

How to translate a ProGuard configuration file to a ZKM Script file

The com.zelix.ZKMProGuardTranslate class appears in the Zelix KlassMaster™ JAR file distribution. It provides a command line alternative to the ProGuard Configuration Translate tool GUI tool. It is used as follows to translate a ProGuard configuration file into ZKM Script format.

java com.zelix.ZKMProGuardTranslate <proguardConfigFileName> <outputFileName>

How to translate a Zelix KlassMaster™ change log into ProGuard mapping file format

The com.zelix.ZKMChangeLogConvert class appears in the Zelix KlassMaster™ JAR file distribution. It provides a command line tool to translate a Zelix KlassMaster™ change log into ProGuard mapping file format. This can be useful when a third party tool supports only the ProGuard mapping file format. The usage is as follows.

java com.zelix.ZKMChangeLogConvert <changeLogFileName> <outputFileName>

Troubleshooting

In the context of translating a ProGuard configuration, if you are having problems then the first place to look is in the ZKM_PG_log.txt file. As mentioned above, it will be written to the directory specified by the ZKM_DEFAULT_DIR configuration option if it has been set or otherwise the directory specified by the user.dir property in the System properties. The ZKM_PG_log.txt file will show
  • The full ProGuard configuration that is to be translated,
  • The detail of any messages and warnings,
  • The default directory for subsequent processing,
  • The name and the location of the Zelix KlassMaster™ log file.
You can then look in the Zelix KlassMaster™ log file named in the ZKM_PG_log.txt file to see if there are any further warning and error messages.
 
Documentation Table of Contents