PreEmptive Protection - DashO v8.1 User Guide

Direct APK Manipulation

Overview

This section will walk you through setting up an existing Android project to use PreEmptive Protection - DashO. The setup process differs if you use Gradle for your build environment or you are working directly with an APK file. DashO can work directly with the APK package.

When dealing with the APK, DashO uses the third-party dex2jar and apktool utilities to extract the classes. DashO then obfuscates and instruments them. It then uses those tools to output a new APK.

Prerequisites

The DashO host must have the Android SDK tools and Java 7 (or later). Java must be on the system path.

Stage your Android project for PreEmptive Protection - DashO

No staging is necessary in this setup. You just need to have the built APK file.

Note:

DashO does not support manipulating multidex APK files. If your application requires multidex support, use DashO’s Gradle integration.

DashO will not process embedded APK files (as used by Android Wear). If you have an application which includes a Wear application, use DashO’s Gradle integration if you wish to obfuscate the Wear portion.

Create a PreEmptive Protection - DashO project with the wizard

The New Project Wizard may start automatically when you start DashO. If DashO is already running, you can start the wizard from File New project Wizard. Choose “An Android application” in the “Select Application Type” Wizard screen, and then select the “APK” build environment and enter your Android APK filename.

The Wizard will perform most of its work automatically. The Wizard will use dex2jar and apktool to determine the contents for the APK. You will be required to provide the path to the android.jar file used when compiling the APK.

The Wizard saves a file called project.dox, in the same directory as the APK file, containing all the configuration.

After you create your DashO project, you will should set additional properties so DashO can work directly with the APK. Set the following on the Options - User Properties page:

  • ANDROID_BUILD_TOOLS_HOME – The location of the Android build tools you wish to use. This directory specified should contain the zipalign executable (e.g. c:\android-sdk\build-tools\23.0.2). If you are using build tools version prior to 19.1.0, this executable is not under the build-tools directory but should be under the tools directory.

  • APKTOOL_FRAMEWORK_DIR – A directory containing the framework file(s) to use with Apktool. This is only necessary in rare cases when the default framework file will not work (e.g. a custom device or an Android beta release). See http://ibotpeaches.github.io/Apktool/documentation/#frameworks for instructions regarding extracting the necessary framework.

  • SKIP_APK_MANIFEST – This optional setting will enable skipping the processing of the AndroidManifest.xml file inside the APK. This can be set to “true” if none of the classes mentioned in the manifest are being renamed. A full walkthrough of the wizard can be found in the Getting Started Android Applications section.

Configure obfuscation and instrumentation with the PreEmptive Protection - DashO GUI

Now that you have your staged Android project loaded into DashO, you can use the DashO GUI to make the desired configurations. Remember to save your project, which will update the project.dox file. To change the configuration settings later, run DashO, open your project.dox file, make your changes, and save.

See the User Interface Reference section for a walkthrough of the DashO GUI

You can test your configurations to see if they build correctly by building the project within the GUI.

Integrate with a Gradle build

You can add call DashO from a Gradle build by adding the following to your build script:

buildscript {
    repositories {
        flatDir dirs: "{DashO's Installation Directory}/gradle"
    }
    dependencies {
        classpath "com.preemptive:dasho:2.3.+"
    }
}

apply plugin: 'com.preemptive.dashoCustom'

dashOConfig {
    dashOHome = '{DashO's Installation Directory}'
    doxFilename = 'project.dox'
}

task obfuscate (type:DashOFileTask) {
    from("application.apk")  //Where application.apk is replaced by the actual filename and path
    to("application-ob.apk")
    addUserProperty("apkInput", '${gradleInput}')
    addUserProperty("apkOutput", '${gradleOutput}')
}

This will incorporate the standard java DashO plugin. To run, call gradlew obfuscate.

Note:

Notice the single quotes around ${gradleInput} and ${gradleOutput}. Those literal strings need to be passed as property values.

Integrate with an Ant build

You can add call DashO from an Ant build by adding the following to your build script:

<typedef onerror="failall" resource="preemptive/dasho/anttask/antlib.xml"/>
<target name="obfuscate" description="Obfuscate the application.">
    <obfuscate project="project.dox">
        <sysproperty key="apkInput" value="application.apk" /> 
        <!-- Where application.apk is replaced by the actual filename and path -->
        <sysproperty key="apkOutput" value="application-ob.apk" />
    </obfuscate>
</target>

This will incorporate DashO’s Ant plugin. To run, call ant obfuscate.

It assumes you have installed DashO’s Ant Task. Information on installing the Ant task is available in DashO's Ant Task documentation.

Sign and Install your obfuscated APK to an emulator or device

The build will output a new APK. You will need to sign it and then you can install it to an emulator or physical device. You have to create a signing key and provide this information to DashO, or manually sign the app yourself. This information can be provided on the Output – Signing page. Once you configure signing, you can also enable zip align on the Output – APK page.

Please see http://developer.android.com/tools/publishing/app-signing.html for more information on signing APKs.

Once signed it can be installed using the standard Android tools:

adb install {filename}.apk

This will install the APK to the running emulator or connected device. You can then access the application by navigating to the applications list. The installed application will appear just like any other Android app installed on a device.

Run on another machine

Copying the APK and project.dox file from one machine to another should work as long as DashO and the Android SDK is available to the other machine. You may need to update ANDROID_BUILD_TOOLS_HOME to point to the new location of the Android SDK.

Your best solution will be to prepare an environment ahead of time in such a way that one build machine has access to the different tools mentioned above.

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