"Obfuscate Options" Window

Contents:

Overview

The Zelix KlassMasterTM "Obfuscate" tool renames classes, fields and methods to make your bytecode smaller and to reduce the meaningfulness of source code produced by a decompiler. It can also obfuscate the control flow and encrypt the String literals in your bytecode to give added protection against decompilation. However, flow obfuscation and String encryption will slightly increase your bytecode size and slightly slow your bytecode.

Options to use
Objective Name obfuscation Flow obfuscation String encryption
Mimimum bytecode size yes no no
Balance between size
and protection
yes yes no
Maximum protection yes yes yes

"Use input change log file" box

Select this box if you want Zelix KlassMaster to use an input change log. Zelix KlassMaster will use the name mappings in the input change log as a definitive guide when renaming package, class, field and method names. It can be very useful to have Zelix KlassMaster rename your classes, fields and methods to match the previous release if you intend to distribute only the changed portion of your application in the form of a patch.

"Use input change log file" field

You can enter the name of the input change log into this field. If you enter an unqualified file name then Zelix KlassMaster will look for it in the folder from which Zelix KlassMaster was started. You can also enter a relative or absolute path.

Use input change log file ". . ." button

Click this button to open a file selection dialog to find and select the input change log that you wish to use. The selected file name will appear in the "use input change log file" field.

"Produce a change log file" box

Select this box if you want Zelix KlassMaster to produce a change log. The change log will record the mappings of original package, class, field and method names to new obfuscated names. It is highly recommended that you select this option and keep the change log produced in a safe place. You will need it to translate stack traces produced by your obfuscated bytecode using the Stack Trace Translate tool. You can also use it as an input change log to ensure compatible renaming in future releases.

"Produce a change log file" field

You can enter the name of the output change log into this field. If you enter an unqualified file name then Zelix KlassMaster will create it in the folder from which Zelix KlassMaster was started. You can also enter a relative or absolute path.

If the specified file already exists then it will be overwritten. Note that you should keep the change log produced when you obfuscate your final release in a safe place.

Produce a change log file ". . ." button

Click this button to open a file selection dialog to find and select an output change log that you wish to overwrite. The selected file name will appear in the "Produce a change log file" field.

"Obfuscate control flow" list

This list determines whether Zelix KlassMaster will obfuscate the control flow of your methods. Flow obfuscation can provide extra protection against decompilation. You should see the Zelix KlassMaster documentation for more detail.

List item Explanation
none Select this setting if you don't want to use flow obfuscation.
light Select this setting if your classes must run in the widest variety of JVMs. "Light" flow obfuscation works around a number of JIT compiler bugs that can cause some flow obfuscated bytecode to fail.
normal This setting performs a more thorough obfuscation than the "light" setting. However, it increases the risk that your bytecode will not run on some buggy JIT compilers.
aggressive This setting performs a more thorough obfuscation than the "light" and "normal" settings. However, it increases the risk that your bytecode will not run on some buggy JIT compilers.

"Exception ofuscation"

This list determines whether Zelix KlassMaster will perform a kind of flow obfuscation which involves exceptions.

List item Explanation
none This setting instructs Zelix KlassMaster to not perform Exception obfuscation.
light This setting instructs Zelix KlassMaster to perform Exception obfuscation.
heavy This setting instructs Zelix KlassMaster to perform Exception obfuscation in a more aggressive fashion.

"Encrypt String literals" list

This list determines whether Zelix KlassMaster will encrypt the String literals in your classes. String encryption can provide extra protection against decompilation. Zelix KlassMaster changes the values of your String literals to equivalent encrypted values and then adds a decrypt method to each affected class to decrypt the literal at runtime. You should see the Zelix KlassMaster documentation for more detail.

List item Explanation
none Select this setting if you don't want to use String encryption.
normal Select this setting if you want Zelix KlassMaster to encrypt your String literals in the most basic fashion. This setting will leave String literals in interfaces unencrytpted.
aggressive This setting encrypts your String literals as with the "normal" setting but Zelix KlassMaster will attempt to use a more sophisticated approach that allows the encryption of Strings in interfaces.
flow obfuscate This setting encrypts your String literals as with the "aggressive" setting but it will also add a flow obfuscated version of the special decrypt instructions to your classes. As with the "aggressive" setting, in interfaces with many String literals, the Constant Value Attributes associated with the interface "static" String fields may be cleared.
enhanced This setting encrypts your String literals as with the "flow obfuscate" setting but provides enhanced encryption.

If you use "enhanced" String Encryption then you should also consider selecting "normal" or "random" in the "Method parameter changes" list so that it is harder to reverse.

"Mixed case class names" list

This list determines whether Zelix KlassMaster will use mixed case when it obfuscates your class names. If your classes will ever be stored outside of an archive file in a file system which is not case sensitive (e.g. Linux) then you should not choose to have mixed case class names. Otherwise classes may be overwritten.

List item Explanation
true Select this setting if you want to allow mixed case class names.
false Select this setting if you do not want to allow mixed case class names.
if only in archive Select this setting if you want to allow mixed case names only for classes which have been opened only from an archive.

"Collapse packages" box

Select this box if you want Zelix KlassMaster to recursively collapse subpackages into their superpackages. Effectively, classes in subpackages will be moved into their superpackages. By reducing the overall length of the package names, this option reduces the length of fully qualified class names and therefore reduces the size of the bytecode.

Packages whose names have been excluded from being changed are never collapsed. So packages with excluded superpackages will be collapsed into the nearest excluded superpackage. If a package has no excluded superpackage then it will be collapsed into the package specified in the "Default name" field that appears to the immediate right of the "Collapse packages" box. If the the "Default name" field is empty then packages with no excluded superpackage will be collapsed into the Java default package "" (which is no package at all).

Remember that one of the purposes served by package names is to ensure that fully qualified class names are unique. If you collapse your packages into the Java default package (ie. no package) then Zelix KlassMaster will ensure that your class names are unique within your application. However, you must be sure that there will be no runtime name clashes with other default package classes in the runtime classpath.

Take as an example the following set of packages.
com
com.mycompany
com.mycompany.package1
com.mycompany.package2
com.yourcompany
com.yourcompany.package1

If you
1. select the "Collapse packages" box
2. exclude the com.mycompany package name from being excluded
3. enter foo into the "Default name" field

then the packages will be collapsed as follows
com=>com
com.mycompany=>com.mycompany
com.mycompany.package1=>com.mycompany
com.mycompany.package2=>com.mycompany
com.yourcompany=>foo
com.yourcompany.package1=>foo

giving the result
com
com.mycompany
foo

Typically you would only collapse the package structure if your obfuscated classes were self contained. The following settings are typical for the different application types.
Application type Ok to collapse packages?
Non-extensible library No
Extensible framework No
J2ME MIDlet Yes
Self contained application or applet Yes

"Default name" field

This field specifies the name of the package into which your existing packages will be collapsed by default if you have selected the "Collapse packages" box. Packages will only be collapsed into the specified package if they do not have a superpackge that has been excluded from being renamed. If the "Default name" field is empty then the packages will be collapsed into the Java default package "" (which is no package at all). Please see the help on "Collapse packages" box above for more detail on the collapse package functionality.

"Aggressive method renaming" box

If you select this option, Zelix KlassMaster will rename your methods more aggressively. The resulting bytecode will run without problem but you may have difficulties compiling Java source against your obfuscated bytecode.

Select this option only if your application is stand-alone and self-contained. Do not select this option if your classes make up an extensible framework or a class library.

"Randomize obfuscation" box

If you select this box then Zelix KlassMaster will attempt to generate new obfuscated names in a random fashion. By default, if the opened classes are unchanged, Zelix KlassMaster will generate the same obfuscated names. Do not select this box if you would like your classes to be obfuscated with some consistentency each time.

"Keep inner class information" list

This list determines what Zelix KlassMaster will do with any Inner Class attributes that may be present in your bytecode. It is these Inner Class attributes that make one class the inner class of another.
List Item Explanation
true Keeps all inner class information
false Deletes all inner class information
if name not obfuscated Keeps inner class information in any classes that are not name obfuscated

Generally, Inner Class attributes are not used at runtime so, removing them can reduce your bytecode size. However, Inner Class attributes are used by some debuggers and by compilers. If you need to compile other classes against your obfuscated inner classes then you should select true or if name not obfuscated.

"Keep generics information" list

This list determines what Zelix KlassMaster will do with any generics information that may be present in your bytecode. (Genericity was introduced with the JDK 1.5.0.)
List Item Explanation
true Keeps all generics information
false Deletes all generics information

Generally, generics information is not used at runtime so it can be removed. Removing it can reduce your bytecode size. However, generics information is used by some debuggers and by compilers. If you need to compile other classes against your obfuscated classes then you should select true.

"Local variables table" list

This list determines what Zelix KlassMaster will do with your local variable names. Local variable names are optionally stored as debugging information in your class files. Note that the names that you give to your method parameters are local variable names.

List item Explanation
delete Select this setting if you want all local variable name information to be deleted. This option reduces the size of bytecode.
keep Select this setting if you want all local variable name information to be retained. This option is not recommended and is provided only for those rare cases where it may temporarily make debugging easier.
obfuscate Select this setting if you want all local variable name information to be retained in an obfuscated form (e.g. "a"). Obfuscated local variable names will typically take up less space than meaningful variable names but they will take up more space than would otherwise be the case.
keep visible method parameters Select this setting if you want the method parameter variable names of public and protected methods to be retained. Many IDE's will preview a method's signature including its parameter names which is why you may want to retain them.
keep visible parameters if name not obfuscated Select this setting if you want the method parameter variable names of public and protected methods to be retained but only if
  1. the name of the method is not obfuscated and
  2. the names of the containing class and package are not obfuscated.
keep parameters if name not obfuscated Select this setting if you want the method parameter variable names of methods to be retained (regardless of their access level) but only if
  1. the name of the method is not obfuscated and
  2. the names of the containing class and package are not obfuscated.
Many IDE's will preview a method's signature including its parameter names which is why you may want to retain them. The keep visible parameters if name not obfuscated and keep parameters if name not obfuscated options assume that you would only want to do this for methods which have not been affected by Name Obfuscation.

"Line number tables"

This list determines what Zelix KlassMaster will do to the Line Number tables that may exist within your bytecode. Line Number tables are optional structures that hold debugging information. They allow the JVM to determine which source file line number is associated with any particular compiled instruction. This information is used to display line numbers in stack traces.

List item Explanation
delete This setting instructs Zelix KlassMaster to delete all Line Number table information. It reduces the size of bytecode that contains Line Number tables but it means that stack traces produced by the bytecode cannot contain line numbers.
scramble This setting instructs Zelix KlassMaster to scramble all Line Number table information. There is no size reduction but the JVM will be able to produce stack traces containing line numbers. However, because the line numbers will be scrambled, you would have to use a tool like the inbuilt Zelix KlassMaster Change Log Translate tool to convert them back to the original line numbers. Most importantly, it would be very difficult for a decompiler to make use of the scrambled line number information to improve the quality of the source code it produces.
keep This setting instructs Zelix KlassMaster to keep all Line Number table information in its original form. There is no size reduction and there is a risk that the original line number information could be used by a decompiler to improve the quality of the source code it produces. However, any stack trace line numbers will map directly to the original source code.

"Obfuscate References" box

Select this box if you want Zelix KlassMaster to obfuscate certain field and/or method references by replacing them with Reflection API calls. This is called Reference Obfuscation. If you select this box then you will be asked to specify which field and/or method references you want to have obscured.

If you elect to use Reference Obfuscation then you should also consider selecing "normal" or "random" in the "Method parameter changes" list so that it is harder to reverse.

"Auto reflection handling" box

Select this box if you want Zelix KlassMaster to automatically handle Reflection API calls.

If you get warning messages saying that an "AutoReflection hash is vulnerable to brute force attack" then you should consider using the ZKM Script interface rather than the GUI. The ZKM Script "accessedByReflection" and/or "accessedByReflectionExclude" statements allow you to specify which classes, fields and methods should be mapped by AutoReflection.

"Method parameter changes" list

Select "normal", "random" or "flowObfuscate" from this list if you want to allow Zelix KlassMaster to add special additional parameters to some of your methods. This option is only relevant if you are also using "enhanced" String Encryption or Reference Obfuscation.

If you allow Zelix KlassMaster to add additional method parameters then it can make its "enhanced" String Encryption and Reference Obfuscation much more difficult to reverse. See "Encrypt String literals" list and "Obfuscate References" box above.

The disadvantage is that it interlinks your classes such that the obfuscated application must be released as a whole and will not be suitable for "patching" with changed subsets of the classes.

List item Explanation
none This setting instructs Zelix KlassMaster to not change any method parameters.
normal This setting instructs Zelix KlassMaster to change any method parameters in a standard fashion.
random Same as "normal" but the additional parameters will be of a more random type and will be in a more random position but there may be a slight runtime performance cost.
flowObfuscate Same as "random" but Zelix KlassMaster will also attempt to obfuscate the flow in the changed methods making use of the changed parameters. This flow obfuscation would be in addition to any flow obfuscation specified in the "Obfuscate control flow" list.

"Keep balanced locks" box

Select this box if you want Zelix KlassMaster to maintain "structured locking". You should select this box if your classes will be used to generate bytecode for the Android ART verifier.

"Preverify" box

Select this box if you want Zelix KlassMaster to preverify your classes. If any of your classes are Java 6 or better then you should select this box unless you know that they will not be run on a JVM. You don't need to select this box if your classes will be used only to generate bytecode for Android.


© 2019 Zelix Pty Ltd