"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 decompliation. 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.

"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 effected 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. However, for runtime performance reasons, this more sophisticated approach will not be used in the case of interfaces with many (ie. 500 or more) String literals. In these cases the Constant Value Attributes associated with the interface "static" String fields will be cleared and Zelix KlassMaster will output a warning. The clearing of the fields is only a problem if the "static" String fields need to be accessed at runtime by classes outside of your application or if you need to compile other classes against your obfuscated classes.
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.

"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.

"Keep inner class information" box

Select this box if you wish Zelix KlassMaster to retain the special 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.

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 not select this option.

"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.


© 2003 Zelix Pty Ltd