PreEmptive Protection - DashO v8.2 User Guide

New Project Wizard

Overview

The easiest way to create a PreEmptive Protection - DashO project is to use the New Project Wizard. The wizard examines your application and determines the settings to obfuscate your application. To start the wizard, go to File > New Project > Wizard.

The first step in using the wizard is to characterize your application. Select the type that best describes your application.

Based on your selection the wizard will ask you a series of questions that are specific to your application type. When the wizard finishes, take a look at the Console for any issues which may have been encountered. The following sections show you how to use the wizard for each type of application.

Note:

By default, the New Project Wizard will automatically launch on startup.

Library Applications

When you select a library to be obfuscated the wizard will ask you for the location of the jar or directory that contains the library.

The wizard will examine the library and determine dependencies that will be needed at runtime or for obfuscation purposes. You can add additional jars as input to be obfuscated or as runtime support jars. The missing classes list shows classes that are referenced by your library.

Next the wizard will ask about the entry points in the library. The wizard will show the entire library as an entry point along with any special classes or methods that are used as entry points.

Finally, the wizard asks where you want to save the resulting project file. If you overwrite an existing project file the wizard will update the project file with your new selections. It will update the Make Synthetic option, setting it to Only private and package, but other obfuscation and PreEmptive Analytics settings are preserved.

Note: When obfuscating a library, use a Make Synthetic option of Never, Only private and package, or If not public. Choosing Always will prevent the library from being properly exposed to your end users.

Applications in a Jar

When you select an application jar to be obfuscated the wizard will ask you for the location of the jar that contains the application.

The wizard will examine the application and determine dependencies that will be needed at runtime or for obfuscation purposes. You can add additional jars as input to be obfuscated or as runtime support jars. The missing classes list shows classes that are referenced by your application.

Next the wizard will ask about the entry points of the application. If the jar's manifest included a Main-Class attribute it will be listed as an entry point. In addition, the wizard will show the special classes or methods that could also be used as entry points. DashO uses these entry points to determine unused items that will be pruned from the obfuscated output. You can select as many entry points you wish to have DashO follow, but should always select at least one.

Finally, the wizard asks where you want to save the resulting project file. If you overwrite an existing project file the wizard will update the project file with your new selections. Other obfuscation and PreEmptive Analytics settings are preserved.

WAR Files

When you select a WAR file to be obfuscated the wizard will ask you for the location and name of the WAR to be obfuscated.

The wizard will examine the WAR file for classes and jars that are included in the WAR. These items include the special locations in WEB-INF that are used by the web container as well as jars that may be referenced by JNLP files. You can select which items in the WAR file that you wish to obfuscate.

In addition to the jar files that are stored in the WAR file, DashO needs the classes that are part of the Servlet and JSP APIs. The wizard will look for these jars in well-known locations and add them to the list of support jars that will not are not obfuscated. If your application expects the web container to provide any other classes shared amongst web application, such as the logging service log4j, you need to add it to the list of jars.

Finally, the wizard asks for the directory where you want to save the wizard's output. The wizard will create several files in addition to a project file:

  • obfuscate.xml: An Ant script that opens the WAR file, runs the DashO project file, and then re-assembles the WAR file.

  • obfuscate.properties: A Java properties file read by obfuscate.xml. Use this file to change location defaults.

The obfuscate.xml file can be executed by running Ant:

ant -f obfuscate.xml

or by calling it from another Ant file:

<ant antfile="obfuscate.xml"/>

It performs three tasks:

  • It un-WARs the WAR file into a directory. The default directory is .unwar.

  • It runs the Wizard generated project files against the contents of the .unwar directory. Results are temporarily stored in the .obfus directory.

  • It recreates the WAR with the obfuscated results into a new WAR file with _dashoed added to the original file name.

Note: The default memory allocated to DashO processes is 192M. You can change this and other defaults used in WAR file processing by editing obfuscate.properties.

If you overwrite an existing project file the wizard will update the project file with your new selections. Other obfuscation and PreEmptive Analytics settings are preserved.

You will need to install DashO's Ant tasks to perform the obfuscation. See DashO's Ant Task documentation for additional details.

Android Applications

When you select an Android application to be obfuscated the wizard will ask you for the build environment and the location of the Android project. The process is slightly different between Gradle build environments and direct APK projects.

Gradle Build Environment

Prerequisites

  • Android SDK Tools Revision 19 (or later depending on Android's Gradle plugin's requirements)
  • Gradle version 2.2 (or later depending on Android's Gradle plugin's requirements)
  • Android’s Gradle Plugin versions: 0.14.3, 0.14.4, 1.0.0-rc*, 1.0.x, 1.1.x, 1.2.x, 1.3.0, 1.3.1, 1.5.0, 2.0.0, 2.1.0, 2.2.0, and 2.3.0 (later versions may not work).

Note:

Please see Working with Build Flavors if your project contains build flavors.

The wizard considers a directory to be an Android project if it contains the build.gradle file used by Gradle. If you created your Android application using an IDE the build.gradle may not exist. You can create the required build.gradle manually or by using Android’s Eclipse ADT plugin http://developer.android.com/sdk/installing/migrate.html. You should then build your application:

gradlew build

Running the wizard in a directory that already contains source for an Android application will not overwrite any of your source files.

The wizard will examine the application and determine dependencies that will be needed at runtime or for obfuscation purposes. You can add additional jars as input to be obfuscated or as runtime support jars. If your Android application uses an add-on target, like Google-APIs, those libraries may not be added automatically as support files. The missing classes list shows classes that are referenced by your application but were not located.

The wizard analyzes the AndroidManifest.xml, the resources, and the compiled classes to determine the entry point of the application. For Android applications you should use all the entry points suggested by the wizard.

The wizard will create/change several files:

  • project.dox: This is the DashO configuration file, containing all the project-specific settings. This is related directly to the source code of the project. It can be manipulated using DashO’s user interface.

  • build.gradle: This is a Gradle build script. The wizard modifies this file to add dependencies to the DashO Gradle plugin. The modifications include an import of dasho.gradle. This is not project-specific, except that different versions of DashO might make different modifications (as we add new features to DashO).

    dasho.gradle: This is a Gradle build script piece that is referenced by the main build.gradle. It provides configuration information. It does not have project-specific data in it (except for a reference to project.dox), but different versions of DashO might create different versions of this file (as we add new features to DashO). Make sure to use the correct version of the DashO Gradle plugin.

Note: See the Version Compatibility section of the DashO Gradle Plugin User Guide to make sure the correct versions are configured.

Building the Project

You can use DashO's user interface to configure the obfuscation and instrumentation or execute the obfuscation to investigate any issues or misconfigurations. You may need to manually add required support jars or set them in the gradleSupport User Property. To build and obfuscate the application you simply need to use the standard commands provided by Android’s Gradle plugin. Such as:

  • gradlew assemble

  • gradlew build

  • gradlew installDebug

By default, debug builds are not obfuscated. If you need to enable/disable obfuscation, simply edit the dasho.gradle file and change the disabledForBuildTypes line inside the dashOConfig closure:

  • disabledForBuildTypes = ['debug'] //Do not obfuscate debug builds

  • disabledForBuildTypes = ['release'] //Do not obfuscate release builds

  • disabledForBuildTypes = ['debug', 'release'] //Do not obfuscate

  • disabledForBuildTypes = ['none'] //Obfuscate debug and release builds

Note: Please see consult the Android Gradle Plugin User Guide and DashO Gradle Plugin User Guide for additional information.

DashO will rewrite the AndoidManifest.xml file using the ${AndroidManifestFile} and ${AndroidManifestOutput} settings in the non-class files section.

Working with Build Flavors

The wizard does not work directly with build flavors. However the following steps will help you setup the initial project configuration via the wizard. In these steps, replace {flavorName} with the flavor's name.

  1. Build your project via gradlew build.

  2. Copy the debug (or release) directory from build/intermediates/classes/{flavorName} to the build/intermediates/classes directory.

  3. Copy the debug (or release) directory from build/intermediates/res/merged/{flavorName} to the build/intermediates/res/merged directory.

  4. Handle the Manifest:

    1. If the location of AndroidManifest.xml is specified in build.gradle (I.E. manifest.srcFile={PathToManifest}), make sure the flavor being configured is listed first.

    2. If the location of the AndroidManifest.xml is NOT specified in build.gradle:

      1. If you have an AndroidManifest.xml in src/main, that manifest will be used by the wizard. You will need to add any flavor specific entrypoints manually.

      2. If you do not have an AndroidManifest.xml in src/main, make a copy of the flavor’s manifest and put it in the root of your project (the same directory as build.gradle). Delete the copy once you have finished the wizard.

  5. Run through the wizard.

  6. If you want to be able to run DashO via the GUI, go to the User Properties section and enter the proper defaults for the build locations based on this flavor. This typically includes:

    1. Change buildType to default to {flavorName}/debug (or {flavorName}/release)

    2. Add the {flavorName} into the default for gradleInput providing the correct path.

  7. Add any additional flavor specific entrypoints.

  8. Delete the debug (and/or release) directories, created in steps 2 and 3, from build/intermediates/classes and build/intermediates/res.

  9. Save the created configuration to {flavorName}.dox and delete the project.dox file.

  10. Repeat from Step 2 for other flavors.

  11. Remove the doxFilename entry from dasho.gradle.

DashO will now work with flavor-specific Gradle builds, automatically.

Direct APK Manipulation

Prerequisites

  • Android SDK Tools Revision 10 or later.

The wizard requires you to select a valid APK file and then requires you to select an appropriate android.jar file.

The wizard analyzes the AndroidManifest.xml, the resources, and the compiled classes inside the APK to determine the entry point of the application. For Android applications you should use all the entry points suggested by the wizard.

Note:

If the APK cannot be decoded properly you will see an error on the Add Jars page. Click Cancel and look at the Console for additional details.

The wizard will create a project.dox file. This is the DashO configuration file, containing all the project-specific settings. This is related directly to the compiled code of the APK. It can be manipulated using DashO’s user interface.

Note:

You should configure signing on the Output – Signing screen and configure, or verify, the Android Build Tools directory on the Output – APK screen. The wizard tries to detect the Android SDK's build-tools directory to help with this configuration.

Building the Project

Use DashO's user interface to configure and run the obfuscation and instrumentation. DashO will rewrite the AndoidManifest.xml file to allow for the renaming of classes. A new APK file will be output.

Note:

You may want to configure signing and turn on zipalign so the output APK is ready to be installed.

PreEmptive Protection - DashO Version 8.2.0. Copyright © 2017 PreEmptive Solutions, LLC