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)
Using this method means that each patch is as small as possible. However,
the user's classpath can become polluted by a long series of patch files
which must be given in the correct order.
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.
| 
