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 allowMethodParameterChanges parameter set to true and
    • Its encryptStringLiterals parameter set to enhanced and/or
    • Its obfuscateReferences parameter set to normal.

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.
 
Documentation Table of Contents