Patch Example - RetroGuard Documentation
The generation of obfuscated patch files is easiest to understand through
an example. We consider the case where a company ships an initial
release (version 1.0) of its product, called "JTool", to its customers
through a website download.
To discourage reverse engineering of the product, the company obfuscates
their Jar file, called jtool-unobf-1.0.jar,
using RetroGuard. The script file used is called
jtool-1.0.rgs and contains a single entry
.class JTool public method which provides access to the
main method of the JTool Java application. The obfuscation command is:
java RetroGuard jtool-unobf-1.0.jar jtool-1.0.jar jtool-1.0.rgs
jtool-1.0.log
The company then posts the obfuscated Jar jtool-1.0.jar
to its website, where it is downloaded by customers. The log-file
jtool-1.0.log contains all of the obfuscation mappings,
and so is archived carefully and securely by the company. This log-file will
be vital during the creation of future patches to the software.
Several weeks later, a customer reports a problem with the JTool product.
It is found that fixing the problem requires only a small change to one
class and to an associated resource file. While it would be possible to
recompile and obfuscate the fixed software, and repost the whole Jar
to the website, this is not an attractive option for JTool's customers
because the whole Jar is several Mbytes in size and takes some time to
download.
A better alternative is to create a small patch file containing only the
modified class and resource. To do this, the whole JTool application is
first compiled and packaged into a Jar
jtool-unobf-1.1.jar.
The Jar is then incrementally obfuscated using the command:
java RetroGuard jtool-unobf-1.1.jar jtool-1.1.jar jtool-1.0.log
jtool-1.1.log
Notice that instead of using the script file jtool-1.0.rgs
as input to this obfuscation, we have used the log-file from the
original (v1.0) obfuscation process. This log-file was generated in an
extended form of the RGS script format, and contains the original entry from
jtool-1.0.rgs as well as all the name mappings from the
first obfuscation process. Obfuscating in this way means that the
v1.1 code can be binary compatible with the originally shipped
v1.0 code.
All that remains is to extract the modified class and resource from the
jtool-1.1.jar using the RGpatch utility. First a text file
jtool-patch-1.0-1.1.txt is created containing the
unobfuscated names of the modified class and resource:
COM/widgetco/MyClass.class
COM/widgetco/anImage.gif
The command to create the patch is then:
java RGpatch jtool-1.1.jar jtool-patch-1.0-1.1.jar jtool-1.1.log
jtool-patch-1.0-1.1.txt
This utility works in two stages: first the log-file
jtool-1.1.log is used to convert the entries in
jtool-patch-1.0-1.1.txt to obfuscated form;
these converted entries are then extracted from
jtool-1.1.jar and used to create the file
jtool-patch-1.0-1.1.jar.
Once again, the log-file jtool-1.1.log is archived
by the company for use in generating future patches to their software.
The patch file jtool-patch-1.0-1.1.jar (which is only
a few Kbytes in size), is posted to the website and downloaded by
JTool customers. These customers just insert the patch Jar ahead of the
original Jar in their classpaths, and run JTool as usual. So, if they
previously ran JTool using the command:
java -classpath jtool-1.0.jar JTool
they could now take advantage of the bug-fix by using the patch file:
java -classpath jtool-patch-1.0-1.1:jtool-1.0.jar JTool
(Note: a colon ':' is used to separate classpath entries in the example above.
This is correct on Unix systems - on Windows systems a semi-colon ';' should
be used instead.)
|
