Advanced Issues - RetroGuard Documentation

In this section we discuss some advanced topics on incremental obfuscation and patching, using RetroGuard and RGpatch.

Patch Sequences

One method of providing patches is to include in each patch only those changes which have occurred since the last patch was issued. The sequence of major release and patch Jar names might be:

jtool-1.0.jar (2.2Mb)
jtool-patch-1.0-1.1.jar (7Kb)
jtool-patch-1.1-1.2.jar (4Kb)
jtool-patch-1.2-1.3.jar (17Kb)
jtool-patch-1.3-1.4.jar (11Kb)

jtool-2.0.jar (3.4Mb)
jtool-patch-2.0-2.1.jar (22Kb)
jtool-patch-2.1-2.2.jar (13Kb)


An alternative technique is to have each patch contain all changes since the last major release. The user has only the most recent patch file in their classpath, but each patch becomes larger than the last. A typical sequence of major release and patch Jar names might then be:

jtool-1.0.jar (2.2Mb)
jtool-patch-1.0-1.1.jar (7Kb)
jtool-patch-1.0-1.2.jar (11Kb)
jtool-patch-1.0-1.3.jar (28Kb)
jtool-patch-1.0-1.4.jar (39Kb)

jtool-2.0.jar (3.4Mb)
jtool-patch-2.0-2.1.jar (22Kb)
jtool-patch-2.0-2.2.jar (35Kb)


Whichever method suits your project, it is clear that a very careful accounting must be kept of code changes, obfuscation log-files and shipped versions of your software. A robust and flexible version control system such as CVS (available as free software from CVS Home) is recommended for this purpose.

In addition, it is recommended that a comprehensive suite of automated tests are developed for your product. This is always desirable, but is particularly helpful in testing patches. The suite can be used to exercise the unobfuscated, the obfuscated, and the patched versions of the product prior to shipping. Clearly, results should be identical in each case.

Addition Entry Points

A patch can be used to introduce one or more new entry points into your product. This will, as usual, require the listing of these entry points in the RGS file used during obfuscation. Since the log-file from the prior version is used as the RGS script file during incremental obfuscation, the additional .class, .method, .field or .attribute entries should be placed in the log-file before obfuscation.

The existing entries in the log-file should not, under any circumstances, be edited or removed: to do so would cause corruption of the generated patch file. In addition, any new entry points (methods which are to be left unobfuscated) must have been introduced to the code since the previous version. It is not possible to change an existing method from being obfuscated in one version to being unobfuscated in the next.

Inner Classes

Since inner classes have privileged access to their outer classes, a patch containing a class must also contain all of its inner classes. The RGpatch utility takes care of this automatically - inner class names in the LISTFILE are ignored, while the listing of an outer class causes all of its inner classes to be copied to the patch Jar also.