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, Integer Constant Encryption and Reference Obfuscation functions by "hardening" them against attack by deobfuscators. Additional parameters are added to the methods that make use of String Encryption, Integer Constant Encryption and/or 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.

How to use the Method Parameter Change functionality

The Method Parameter Changes functionality will only be used if
  • The obfuscate statement has its methodParameterChanges parameter set to flowObfuscate OR
  • The obfuscate statement has its methodParameterChanges parameter set to either normal or random and
    • Its encryptStringLiterals parameter set to enhanced and/or
    • Its encryptIntegerConstants parameter set to normal or aggressive 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 flowObfuscate setting is the same as the random setting but a special kind of Flow Obfuscation may be applied at a possible 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.

The effectiveness of the Method Parameter Changes functionality can be significantly increased if you also use the ZKM Script classInitializationOrder statement to specify pairs of your classes where you guarantee that the first class in the pair will definitely always be initialized at runtime before the second class under all circumstances. The Method Parameter Changes functionality can make use of this information to make it and the transformations that make use of it less vulnerable to being reversed.

Use of the classInitializationOrder statement is highly recommended if you are going to use the Method Parameter Changes functionality but only if you are prepared to carefully analyze and test the initialization order of your classes. It is better to specify six class pairs that you are certain of than a larger number that might be wrong.

Which methods will have their parameters changed

Method selection occurs in stages. As mentioned above, if the methodParameterChanges parameter is set to either normal or random, a method will be considered as a candidate for having its parameter list changed if it makes use of enhanced String Encryption and/or Reference Obfuscation. If the methodParameterChanges parameter is set to flowObfuscate, a method will be considered as a candidate for having its parameter list changed if
  • It makes use of enhanced String Encryption or
  • It makes use of Reference Obfuscation or
  • It has significant control flow that could allow flow 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 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
Zelix KlassMaster - Java Obfuscator