Zelix KlassMaster - Documentation

Long Constant Encryption Tutorial

This tutorial is divided into the following sections:

Introduction

When you use Zelix KlassMaster™'s Long Encryption functionality, it will replace long constants in your bytecode with lightly encrypted equivalents and add instructions to your bytecode that will decrypt those longs back to the originals at runtime. Note that because the encryption "key" must be available at runtime, Long Encryption cannot be 100% irreversible. Don't rely on it to protect highly sensitive data.

Example

Method decompiled 

long method0() {
   return 127L;
}

Method Long Constant Encrypted with Method Parameter Changing then decompiled 

private static final long a = o.a(425868181624802497L, 7792344439649777418L, MethodHandles.lookup().lookupClass()).a(188318979481983L);
long method0(long var1) {
  var1 ^= a;
  return true.g(14977, 1548317666104588234L ^ var1);
}

How to use Long Encryption functionality

You switch on the Long Encryption functionality by setting the encryptLongConstants parameter of the obfuscate statement to a value other than none. The allowable settings are none and normal. It will default to none.

When the setting is normal, Zelix KlassMaster will encrypt your long constants in the following basic fashion. Any long fields which are directly initialized with a value other than 0 or 1 will have their initialization values encrypted. Also, if there is a reference in a method to a long constant other than 0 or 1 then that long value will be encrypted.

You can override the exclusion of 0 and 1 field values by setting the ZKM_LONG_ENCRYPT_LOW_VALUE_FIELDS configuration option to true.

You can manage which long constants are encrypted by using the longEncryptionExclude and longEncryptionUnexclude statements. You can use the longEncryptionExclude statement to exclude long fields from have their values encrypted or complete classes from any long encryption. The longEncryptionUnexclude statement can be used to remove fields or classes from the set of excluded objects specified by an longEncryptionExclude statement

Also, when used in conjunction with the Method Parameter Changes functionality, the Long Constants Encryption functionality may make use of the invokedynamic instruction and the DES encryption algorithm if your bytecode is Java 7 or better (Java 8 or better for interfaces).

If you don't want the invokedynamic and DES algorithm to be used then you can set the ZKM_LONG_ENCRYPT_INDY configuration option to false. If you don't want just the DES algorithm to be used then you can set the ZKM_LONG_ENCRYPT_DES configuration option to false.

The compatibility of Zelix KlassMaster™'s Long Encryption functionality depends upon the compiler that generated the bytecode. We have found no problems with any of the Oracle, OpenJDK or IBM compilers that we have tested.

Interaction with Method Parameter Changes

Zelix KlassMaster™'s Method Parameter Changes functionality can significantly "harden" the long encryption from attack. The downside is that the Method Parameter Changes functionality can interlink your classes such 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. It is a trade-off between protection and flexibility.
 
Documentation Table of Contents
Zelix KlassMaster - Java Obfuscator