DOCUMENTATION

Allatori configuration file is an XML file with the following structure:

Note 1. All relative paths are resolved against configuration file location.
Note 2. If you run Allatori from Ant, then you can reference properties defined in the Ant build file using standard Ant syntax: ${PropertyName}.
Note 3. System properties and environment variables could be referenced using ${System.getProperty(property.name)} and ${System.getenv(VARIABLE_NAME)} respectively.

The input tag is used to set jar (war, ear) files that should be obfuscated. It should contain at least one nested jar or dir tag to set input and output files.

The input tag has two optional attributes:

Example:

    <input basedir="input-jars" single-jar="application.jar">
        <jar in="app.jar" out="app-obf.jar"/>
        <jar in="input/*.jar" out="output/*.jar"/>

        <dir in="in-dir" out="out-dir"/>
    </input>

The classpath tag is used to set the classpath for the obfuscated application. It contains nested jar tags with the names of jar files. It is not necessary to reference all library jars needed by your application, but missing classpath elements may result in a weaker obfuscation. Allatori will warn you about all missing classes during the obfuscation process.

The classpath tag has one optional attribute:

Example:

    <classpath basedir="library-jars">
        
<!-- Adding library.jar to the classpath -->
        <jar name="library.jar"/>
        
<!-- Adding all jars in the lib directory to the classpath -->
        <jar name="lib/*.jar"/>
        
<!-- Adding all jars in the lib2 directory and its subdirectories to the classpath -->
        <jar name="lib2/**/*.jar"/>
    </classpath>

Example:

    <keep-names>
        
<!-- Stops applying further rules to classes in the com.company.abc package,
             therefore all classes, methods and fields in this package will be renamed -->
        <class template="class com.company.abc.*" stop="true"/>
        
<!-- Further rules instruct Allatori not to rename matched elements -->

        
<!-- Matches classes with the name "Main" in any package -->
        <class template="class *.Main"/>

        
<!-- Matches classes with the name ending with "Bean" -->
        <class template="class *Bean">
            
<!-- Matches all fields -->
            <field access="private+"/>
            
<!-- Matches public integer fields -->
            <field template="public int *"/>
            
<!-- Matches all static fields -->
            <field template="static *"/>
            
<!-- Matches protected and public String fields -->
            <field template="protected+ java.lang.String *"/>
            
<!-- Matches all methods -->
            <method template="private+ *(**)"/>
            
<!-- Matches all getter methods -->
            <method template="private+ get*(**)"/>
            
<!-- Matches all methods with String argument,
                 parameter names of these methods will not be changed -->
            <method template="private+ *(java.lang.String)" parameters="keep"/>
        </class>

        
<!-- Matches serialization members -->
        <class template="class * instanceof java.io.Serializable">
            <field template="static final long serialVersionUID"/>
            <method template="void writeObject(java.io.ObjectOutputStream)"/>
            <method template="void readObject(java.io.ObjectInputStream)"/>
            <method template="java.lang.Object writeReplace()"/>
            <method template="java.lang.Object readResolve()"/>
        </class>

        
<!-- Matches applets -->
        <class template="class * instanceof java.applet.Applet"/>
        
<!-- Matches servlets -->
        <class template="class * instanceof javax.servlet.Servlet"/>
        
<!-- Matches midlets -->
        <class template="class * instanceof javax.microedition.midlet.MIDlet"/>
    </keep-names>

The expiry tag is used to set expiry date to your application. Expiry date checks are inserted into many methods, not just main method, therefore cannot be easily removed. This feature can be used to obfuscate libraries that do not even have main method. The tag has two required attributes:

Example:

    <expiry date="2017/01/01" string="EXPIRED!"/>

Complete example of using expiry date can be found in the tutorial that comes with Allatori distribution.

The property tag is used to set different obfuscation properties. The tag has two required attributes - name and value:

    <property name="property-name" value="property-value"/>

The log file is used to restore original stack trace from the obfuscated one. It keeps obfuscated-to-original mapping of names and line numbers.

Examples:

    <property name="log-file" value="log.xml"/>
    <property name="log-file" value="logs/file.xml"/>

Stack trace utility takes log file and restores original names:

    java -cp allatori.jar com.allatori.StackTrace2 log.xml input.txt output.txt

The default value is current time in milliseconds.

By default, if you run Allatori twice on the same input jars, it will produce different output jars. Renamed classes, fields and methods will have different names, fields and methods will be reordered differently, etc. This is done to make analyzing two versions of the obfuscated application extremely difficult. If you need the same output jars over several consecutive runs of Allatori, then you need to set the random seed. We recommend changing the random seed for different public releases of your application.

Example:

    <property name="random-seed" value="any text here"/>

Sometimes, strings are compared this way:

    String myString = "Hello";
    ...
    public boolean test() {
        return myString == "Hello";
    }

public boolean test() {
    return myString == new String("Hello");
    // "Hello" string isn't encrypted to make this example more clear
}

    <property name="string-encryption" value="enable"/>

The specified text file contains string templates. Each line is a new template, '*' matches any number of any characters. If template line starts with "regex:", then it is processed as a regular expression:

Copyright*
All Rights Reserved*
*CompanyName*
regex:\d+

    <property name="string-encryption-ignored-strings" value="patterns.txt"/>

Example:

    <property name="control-flow-obfuscation" value="enable"/>

Example:

    <property name="packages-naming" value="abc"/>

Example:

    <property name="classes-naming" value="abc"/>

Example:

    <property name="methods-naming" value="keywords"/>

Example:

    <property name="fields-naming" value="keywords"/>

Example:

    <property name="classes-naming-prefix" value="c_"/>

Possible usage is specifying MainClass$ as a prefix:

    <property name="classes-naming-prefix" value="MainClass$"/>

Some decompilers will see renamed classes as inner classes of MainClass.

Example:

    <property name="methods-naming-prefix" value="m_"/>

Example:

    <property name="fields-naming-prefix" value="f_"/>

Example:

    <property name="local-variables-naming" value="single-name"/>

The default single name for single-name and optimize renaming options is 'a'. You can change it using one of the following lines:

    <property name="local-variables-naming" value="optimize:ANY_OTHER_NAME"/>
    <property name="local-variables-naming" value="optimize:int"/>
    <property name="local-variables-naming" value="single-name:4"/>

Example:

    <property name="skip-renaming" value="enable"/>

Example:

    <property name="update-resource-names" value="enable"/>

Example:

    <property name="update-resource-contents" value="enable"/>
    <property name="update-resource-contents" value="enable:UTF-8"/>

The property can be applied to the specified files using apply2file attribute:

    <property name="update-resource-contents" value="enable" apply2file="*.xml"/>

  java.lang.NullPointerException
        at com.company.c.a(m:61)
        at com.company.b.b(w:94)
        at com.company.b.a(w:83)
        at com.company.a.a(n:75)

  java.lang.NullPointerException
        at com.company.Util.createTestException(Util.java:38)
        at com.company.TraceTest.testNullObject(TraceTest.java:53)
        at com.company.TraceTest.allTraceTests(TraceTest.java:14)
        at com.company.Main.runTest(Main.java:27)

  java.lang.NullPointerException
        at com.company.c.a(Unknown Source)
        at com.company.b.b(Unknown Source)
        at com.company.b.a(Unknown Source)
        at com.company.a.a(Unknown Source)

  java.lang.NullPointerException
        at com.company.c.a(Util.java:38)
        at com.company.b.b(TraceTest.java:53)
        at com.company.b.a(TraceTest.java:14)
        at com.company.a.a(Main.java:27)

Example:

    <property name="line-numbers" value="obfuscate"/>

Example:

    <property name="generics" value="remove"/>

Example:

    <property name="inner-classes" value="remove"/>

Example:

    <property name="throws-clause" value="remove"/>

Example:

    <property name="member-reorder" value="random"/>

Example:

    <property name="finalize" value="enable"/>

Example:

    <property name="version-marker" value="THIS_IS_DEMO_VERSION"/>

Some decompilers do not output synthetic methods.

Example:

    <property name="synthetize-methods" value="all"/>

The property can be used more than once:

    <property name="synthetize-methods" value="private"/>
    <property name="synthetize-methods" value="package"/>
    <property name="synthetize-methods" value="protected"/>

Some decompilers do not output synthetic fields.

Example:

    <property name="synthetize-fields" value="all"/>

The property can be used more than once:

    <property name="synthetize-fields" value="private"/>
    <property name="synthetize-fields" value="package"/>
    <property name="synthetize-fields" value="protected"/>

Example:

    <property name="set-methods-to-public" value="all"/>

The property can be used more than once:

    <property name="set-methods-to-public" value="package"/>
    <property name="set-methods-to-public" value="protected"/>

Example:

    <property name="set-fields-to-public" value="all"/>

The property can be used more than once:

    <property name="set-fields-to-public" value="package"/>
    <property name="set-fields-to-public" value="protected"/>

Example:

    <property name="remove-toString" value="enable"/>

Examples:

    <property name="remove-calls" value="android.util.Log.d"/>
    <property name="remove-calls" value="android.util.Log.*"/>

    // if a call to methodOne() is removed, then the line
    int i = methodOne(); 
    // would be changed to
    int i = 0;

    // if a call to methodTwo() is removed, then the line
    Object o = methodTwo();
    // would be changed to
    Object o = null;

Examples:

    <property name="remove-annotations" value="kotlin.Metadata"/>
    <property name="remove-annotations" value="com.package.annotations.*"/>

Examples:

    <property name="output-jar-compression-level" value="9"/>

Examples:

    <property name="output-jar-duplicate-name-entries" value="keep"/>

Example:

    <property name="incremental-obfuscation" value="input-renaming-log.xml"/>

Example:

    <property name="unique-renaming" value="enable"/>

Annotation classes are located in the allatori-annotations.jar. All Allatori annotations are removed during the obfuscation process, so you don't need this jar file in the runtime. Annotations are used for easier and more accurate configuration of the obfuscator.

Here all are available annotations located in the com.allatori.annotations package:

Allatori performs full-featured obfuscation of Android applications and can be easily integrated into the build process. We've created a typical configuration file for Android projects, making it very easy to obfuscate Android application. You can find the configuration file (allatori.xml) and sample build files (build.gradle and build.xml) in the tutorial that comes with Allatori distribution.

android {
    ...
    // for applications
    applicationVariants.all { variant ->
        variant.javaCompileProvider.get().doLast {
            runAllatori(variant)
        }
    }
    // for libraries
    // libraryVariants.all { variant ->
    //    variant.javaCompileProvider.get().doLast {
    //        runAllatori(variant)
    //     }
    // }
}

def runAllatori(variant) {
    copy {
        from "$projectDir/allatori.xml"
        into "$buildDir/intermediates/classes/"
        expand(classesRoot: variant.javaCompileProvider.get().destinationDir,
                kotlinRoot: "${buildDir}/tmp/kotlin-classes/${variant.name}",
                androidJar: "${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar",
                classpathJars: variant.javaCompileProvider.get().classpath.getAsPath(),
                logFile: "allatori-log-${variant.name}.xml")
        rename('allatori.xml', "allatori-${variant.name}.xml")
    }

    new File("${variant.javaCompileProvider.get().destinationDir}-obfuscated").deleteDir()
    javaexec {
        main = 'com.allatori.Obfuscate'
        classpath = files("$rootDir/allatori/allatori.jar")
        args "$buildDir/intermediates/classes/allatori-${variant.name}.xml"
    }
    new File("${variant.javaCompileProvider.get().destinationDir}").deleteDir()
    new File("${variant.javaCompileProvider.get().destinationDir}-obfuscated").renameTo(new File("${variant.javaCompileProvider.get().destinationDir}"))

    // Kotlin support
    // new File("${buildDir}/tmp/kotlin-classes/${variant.name}").deleteDir()
    // new File("${buildDir}/tmp/kotlin-classes/${variant.name}-obfuscated").renameTo(new File("${buildDir}/tmp/kotlin-classes/${variant.name}"))
}

    <target name="-obfuscate" unless="do.not.compile">
        <taskdef name="allatori" classname="com.allatori.ant.ObfuscatorTask"
                                 classpath="allatori/allatori.jar"/>
        <delete dir="${out.classes.absolute.dir}-obfuscated"/>
        <allatori config="allatori.xml"/>
        <property name="out.dex.input.absolute.dir"
                  value="${out.classes.absolute.dir}-obfuscated"/>
    </target>