DexGuard Introduction

Introduction

DexGuard is a bytecode shrinker, optimizer, obfuscator, and converter for Android. The shrinking step detects and removes unused classes, fields, methods, and attributes. The optimization step analyzes and optimizes the bytecode of the methods. The obfuscation step renames the remaining classes, fields, and methods using short meaningless names. These first steps make the code base smaller, more efficient, and harder to reverse-engineer. The final conversion step translates the Java bytecode (*.class) to Dalvik bytecode for Android (classes.dex).

Input code

Shrunk code

Optim. code

- shrink → - optimize → - obfuscate → Obfusc. code - convert → Output code

Platform libraries ------------------------------- (unchanged) -------------------------------→ Platform libraries

DexGuard first reads the input code (jars, aars, wars, ears, zips, apks, or directories, containing Java class files). The input code includes any library projects and third-party libraries. DexGuard then subsequently shrinks, optimizes, obfuscates, and converts the code. You can optionally let DexGuard perform multiple optimization passes. DexGuard packages the processed output code in output archives (jars, aars, wars, ears, zips, apks, or directories, containing Dalvik bytecode). DexGuard can optionally sign and align these archives, removing the need for external tools. The input may contain resource files, whose names and contents can optionally be updated to reflect the obfuscated class names.

DexGuard requires the platform libraries (jars, aars, wars, ears, zips, apks, or directories) to properly process the code. For the standard Android platform, this is simply android.jar.

tip The Ant build process and the Eclipse build process of DexGuard automatically set the proper input and the proper libraries for you. You only need to consider them if you create your own build process.

Entry points

In order to determine which code has to be preserved and which code can be discarded or obfuscated, DexGuard has to know the entry points to your code. These entry points are typically classes defining activities, intentions, etc.

In the shrinking step, DexGuard starts from these seeds and recursively determines which classes and class members are used. All other classes and class members are discarded.
In the optimization step, DexGuard further optimizes the code. Among other optimizations, classes and methods that are not entry points can be made private, static, or final, unused parameters can be removed, and some methods may be inlined.
In the obfuscation step, DexGuard renames classes and class members that are not entry points. In this entire process, keeping the entry points ensures that they can still be accessed by their original names.
The conversion step is the only step that doesn't have to know the entry points.

The Usage section of this manual describes the necessary -keep options and the Examples section provides plenty of examples.

tip The Ant build process and the Eclipse build process of DexGuard automatically set the most common entry points for you. You only need to consider them if you create your own build process, or if your code uses reflection, as discussed below.

Reflection

Reflection and introspection present particular problems for any automatic processing of code. In DexGuard, classes or class members in your code that are created or invoked dynamically (that is, by name) have to be specified as entry points too. For example, Class.forName() constructs may refer to any class at run-time. It is generally impossible to compute which classes have to be preserved (with their original names), since the class names might be read from a configuration file, for instance. You therefore have to specify them in your DexGuard configuration, with the same simple -keep options.

However, DexGuard will already detect and handle the following cases for you:

Class.forName("SomeClass")
SomeClass.class
SomeClass.class.getField("someField")
SomeClass.class.getDeclaredField("someField")
SomeClass.class.getMethod("someMethod", null)
SomeClass.class.getMethod("someMethod", new Class[] { A.class,... })
SomeClass.class.getDeclaredMethod("someMethod", null)
SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class,... })
AtomicIntegerFieldUpdater.newUpdater(SomeClass.class, "someField")
AtomicLongFieldUpdater.newUpdater(SomeClass.class, "someField")
AtomicReferenceFieldUpdater.newUpdater(SomeClass.class, SomeType.class, "someField")

The names of the classes and class members may of course be different, but the constructs should be literally the same for DexGuard to recognize them. The referenced classes and class members are preserved in the shrinking phase, and the string arguments are properly updated in the obfuscation phase.

Furthermore, DexGuard will offer some suggestions if keeping some classes or class members appears necessary. For example, DexGuard will note constructs like "(SomeClass)Class.forName(variable).newInstance()". These might be an indication that the class or interface SomeClass and/or its implementations may need to be preserved. You can then adapt your configuration accordingly.

For proper results, you should at least be somewhat familiar with the code that you are processing. Obfuscating code that performs a lot of reflection may require trial and error, especially without the necessary information about the internals of the code.

Input code
		Shrunk code
				Optim. code
	- shrink →		- optimize →		- obfuscate →	Obfusc. code	- convert →	Output code
Platform libraries	------------------------------- (unchanged) -------------------------------→							Platform libraries