Zelix KlassMaster - Documentation

Method Parameter Changes Tutorial

This tutorial is divided into the following sections:

Overview

The Zelix KlassMaster™ Method Parameter Changes functionality supports the String Encryption and Reference Obfuscation functions by "hardening" them against attack. Additional parameters are added to methods that make use of String Encryption and Reference Obfuscation and these new parameters are used to pass decryption keys to the supported functions.

Where possible, extra parameters will also be added to calling methods such that the decryption keys will be passed through a chain of methods. The objective is to interlink the obfuscated methods and classes such that they must be attacked as a whole rather than as more manageable, individual units.

The downside is that it can become impractical to release changes to your obfuscated classes in the form of patches which are just a subset of your classes.

Note that this functionality is only available through the ZKM Script interface. It is not available through the GUI interface.

How to use Method Parameter Change functionality

The Method Parameter Changes functionality will only be used if
  • The obfuscate statement has its methodParameterChanges parameter set to either normal or random and
    • Its encryptStringLiterals parameter set to enhanced and/or
    • Its obfuscateReferences parameter set to normal.
The random setting will make the type and position of the additional parameters more random with a possible, slight cost to runtime performance. The obfuscate statement's allowMethodParameterChanges parameter is now deprecated. The old allowMethodParameterChanges=true setting is equivalent to methodParameterChanges=normal and the allowMethodParameterChanges=false setting is equivalent to methodParameterChanges=none.

Which methods will have their parameters changed

Method selection occurs in stages. As mentioned above, initially a method will be condsidered as a candidate for having its parameter list changed if it makes use of enhanced String Encryption and/or Reference Obfuscation. Methods with polymorphic relationships to such methods must also be included as candidates. The next stage is to repeatedly include as candidate methods those methods which call candidate methods.

The next stage is to apply exclusions to the candidate method set. You can tailor the candidate set of methods by using a preceding methodParameterChangesInclude or methodParameterChangesExclude statement. If a methodParameterChangesInclude statement appears by itself then the candidate set of methods can only be chosen from the set of methods that it specifies. If a methodParameterChangesExclude statement appears by itself then the candidate set of methods can only be chosen from the set of methods that don't match its specification.

If there is a methodParameterChangesInclude statement and a methodParameterChangesExclude statement then the methodParameterChangesInclude statement will be applied first against the set of all methods and then the methodParameterChangesExclude statement will be applied against the set of methods specified by the methodParameterChangesInclude statement.

If there is not an active, preceding methodParameterChangesInclude or methodParameterChangesExclude statement then by default all methods are considered to be possible candidates. However, there are some other restrictions that Zelix KlassMaster™ applies. For a start, there are some methods that cannot have their parameters changed. The public static void main(String[]) method is an example. All methods which are entry points into your application should not be changed. If you have a preceding trimExclude and/or trimUnexclude statements then Zelix KlassMaster™ will assume that they specifies the entry point methods for your application.

If there are no preceding trimExclude and/or trimUnexclude statements then Zelix KlassMaster™ will assume that any method that has not been name obfuscated and is in a class that has not been name obfuscated is a potential entry point into your application.

Similarly, methods which are accessed via Reflection should not have their parameters changed. If you have a preceding accessedByReflection and/or accessedByReflectionExclude statement then Zelix KlassMaster™ will assume that they specify the methods that are accessed by Reflection by your application.

Qualifications

As mentioned above, there are some methods which should not have their parameters changed. These include methods that
  • Are entry points into your application,
  • Are accessed via reflection and
  • Are expected by some framework which your application uses to have a specific signature. (E.g. getter or setter methods)
The above list is not exhaustive. If you use the Method Parameter Changes functionality then you need to understand the application that you are obfuscating and apply the appropriate exclusions where necessary. It is highly recommended that you start with only limited changes until you have everything working. You can then the iteratively broaden the changes.

In the case of large applications, the Method Parameter Changes functionality could introduce a delay in the start up time of the obfuscated application. This delay would typically be in the order of about 1 second or less. However, in the case of very large applications, this delay could become unreasonably large. In such a case, the "ZKM_METHOD_PARAM_CHANGING_LOOKUP=false" configuration option can be used to switch off the part of the functionality that could cause this delay. This would be at the cost of some protection but in such cases the very size of the obfuscated application itself provides a measure of protection against reverse engineering.
 
Documentation Table of Contents