Name Obfuscation Using yGuard

yGuard is a Java byte code obfuscator that can be used for effective name obfuscation of Java byte code. It is bundled with every yFiles distribution (see the yGuard README file), and is also freely available.

Since yGuard fulfills the obfuscation requirements of the yFiles license terms, it is a perfectly suited tool to protect the yFiles part of any yFiles-based application. (Of course, it is also the perfect tool to protect the entire application.)

yGuard is available as an Apache Ant task for easy integration into any Ant-based build process. Example A.2, “Using the yGuard Ant task” shows an Ant build file’s target that obfuscates the yFiles part of an application.

Note

The example uses yGuard 2.0 syntax.

Example A.2. Using the yGuard Ant task

<!– Obfuscates the yFiles part of an application (i.e., y.jar) and adjusts –>
<!– the non-yFiles part given by the application’s Jar file accordingly. –>
<target name=”obfuscate” depends=”jar”>
<!– yGuard Ant task. –>
<taskdef name=”yguard”
           classname=”com.yworks.yguard.YGuardTask”
           classpath=”${yGuardJar}”/>
<!– Integrated obfuscation and name adjustment… –>
<yguard>
    <!– Obfuscate the yFiles Jar. –>
    <inoutpair in=”${yJar}” out=”${yJarObf}”/>
    <!– While obfuscating, adjust the names of yFiles features in the –>
    <!– application’s Jar file. –>
    <inoutpair in=”${myAppJar}” out=”${myAppJarObf}”/>

    <!– …using the yGuard ‘rename’ task. –>
    <rename logfile=”${obfuscationLog}” replaceClassNameStrings=”true”>

      <property name=”obfuscation-prefix” value=”myprefix”/>
      <keep>
        <class classes=”private” methods=”private” fields=”private”>
          <patternset>
            <include name=”com.mycompany.myApp.**”/>
          </patternset>
        </class>
      </keep>

      <!– Adjust all occurences of now obfuscated names in plain-text –>
      <!– files, too. –>
      <!– For example, the names of property resource bundle files for –>
      <!– yFiles classes must be adjusted to reflect the yFiles class’s –>
      <!– obfuscated name. –>
      <adjust replaceName=”true”>
        <include name=”y/**/*.properties”/>
      </adjust>

    </rename>
</yguard>
</target>

For detailed explanations of yGuard’s Ant syntax, please see the yGuard manual.

Adjusting Names

Any code that makes use of yFiles features, or more specifically uses names of yFiles features, needs to be adjusted to their new names. This adjustment is automatically performed for all Jar files given to the yGuard obfuscation machinery using the <inoutpair> element.

Using yGuard’s <adjust> element (inside the <obfuscate> element), any additional plain-text files that are not processed by the obfuscation itself, e.g., resource files, can be adjusted in several ways, too. For example, a file’s path, its name, and also its content are subject to possible modifications.

Checking Obfuscation Success

During the obfuscation process, yGuard optionally generates a log file that contains all original names, their new obfuscated names, and also additional statistical information in XML-based syntax. The log file is an important document, since it shows the mapping of original to obfuscated names. To display the information nicely, yGuard offers a convenient reverse name look-up feature.

Example A.3, “yGuard’s command line syntax” shows the command line syntax to invoke yGuard’s reverse name look-up. Given a generated log file (or its GZip compressed variant), both the original class, method, and field names and their obfuscated counterparts are conveniently presented in a tree view, as depicted in Figure A.1, “yGuard’s reverse name look-up view”.

Example A.3. yGuard’s command line syntax

java -jar yguard.jar [yGuard_obfuscation_log_file.xml[.gz]]

Figure A.1. yGuard’s reverse name look-up view

To ensure that the yFiles API has been properly obfuscated, all public and protected class, method, and field names must be present in the tree view presented by yGuard’s reverse name look-up feature. In other words, all names of such features must have been replaced by new names that are distinctly different from their originals.

Tutorial Demo Code

For an example on how to obfuscate the yFiles part of a yFiles-based application using yGuard, see the obfuscation demo’s Ant build file (included with the yFiles Complete distribution). The build file also shows how to adjust the occurences of obfuscated names of any yFiles features in properties files.