Android Studio (AS)¶

1. Modify the build.gradle file in the app module of your Android project by adding the following compile line in the dependencies body:

   dependencies {
           // Grab'n Run will be imported from JCenter.
           // Verify that the string "jcenter()" is included in your repositories block!
           compile 'it.necst.grabnrun:grabnrun:1.0.4'
   }
   

2. Resync your project to apply changes.

Android Development Tool (ADT)¶

1. Download the latest version of the JAR container of Grab’n Run.
2. Include the JAR in the libs subfolder of your Android project.

Adding missing permissions (Both AS and ADT)¶

Finally it is required to modify the Android Manifest of your application by adding a couple of required permissions if they are not already in place:

<manifest>
        <!--    Include following permission to be able to download remote resources
                like containers and certificates -->
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
        <!--    Include following permission to be able to download remote resources
                like containers and certificates -->
        <uses-permission android:name="android.permission.INTERNET" />
        <!--    Include following permission to be able to import local containers
                on SD card -->
        <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
        ...
</manifest>

Using standard DexClassLoader to load code dynamically¶

Let us pretend that you want to dynamically load an external class through DexClassLoader, a class in the Android API used to load classes from jar and apk files containing a classes.dex entry. This is a convenient way to execute code not installed as part of an application package.

Let’s assume, for example, that you want to load an instance of com.example.MyClass located in the container exampleJar.jar, stored in the Download folder of the sd_card on the target phone. Note that this scenario may potentially lead to a code injection attack when you use the standard DexClassLoader since you are choosing to load code from a container which is stored in a world writable location of your phone. Notice that this kind of attack would be prevented with SecureDexClassLoader. Anyway a snippet of code to achieve this task is the following:

MyClass myClassInstance = null;
String jarContainerPath =       Environment.getExternalStorageDirectory().getAbsolutePath()
                                + "/Download/exampleJar.jar";
File dexOutputDir = getDir("dex", MODE_PRIVATE);
DexClassLoader mDexClassLoader = new DexClassLoader(    jarContainerPath,
                                                        dexOutputDir.getAbsolutePath(),
                                                        null,
                                                        getClass().getClassLoader());

try {
        Class<?> loadedClass = mDexClassLoader.loadClass("com.example.MyClass");
        myClassInstance = (MyClass) loadedClass.newInstance();

        // Do something with the loaded object myClassInstance
        // i.e. myClassInstance.doSomething();

} catch (ClassNotFoundException e) {
        e.printStackTrace();
} catch (InstantiationException e) {
        e.printStackTrace();
} catch (IllegalAccessException e) {
        e.printStackTrace();
}

The String jarContainerPath contains the path to examplejar, while dexOutputDir is an application-private, writable directory to cache optimized dex classes into examplejar. As reported in DexClassLoader documentation, you can retrieve dexOutputDir in different ways but it is fundamental that this cache folder is application-private; otherwise your application may be subjected to code injection attacks. And by the way this kind of attack is prevented if you choose to use SecureDexClassLoader as explained later on in this guide.

The object mDexClassLoader is then initialized as a DexClassLoader instance, which loads all the classes into examplejar and caches their optimized version into dexOutputDir. No native library is included since the third parameter of the constructor is null and the ClassLoader of the current activity is passed as parent class loader.

Finally the designated class is, at first, loaded by invoking the loadClass() method on mDexClassLoader with the full class name provided as a parameter and, secondly, instantiated through the newInstance() method and the forced casting to MyClass. The three different catch blocks are used to handle different exceptions that may be raised during the process.

Package Name

In Java every class is associated to a package name. A package is a grouping of related classes, interfaces and enumerations providing access protection and name space management. In particular in Grab’n Run packages names are accepted if and only if they are a sequence of at least two not-empty, dot-separated words, which starts and ends with a word, not with a dot. This implies that the following are all examples of invalid package names: com, .com.application, com..application, com.application., while suitable package names are com.application or it.polimi.necst.gnr. As you will see later on in this tutorial, package names perform a relevant functionality in GNR system since they link containers to be verified with the certificate used to do so.

This snippet of code is perfectly fine and working but it is not completely secure since neither integrity on the container of the classes, neither authentication on the developer of the container are checked before executing the code. And here comes SecureDexClassLoader to solve these issues.

Using SecureDexClassLoader to load dynamic code securely¶

In order to improve the security of the snippet of code shown in Using standard DexClassLoader to load code dynamically a new version of the code is presented through the use of SecureDexClassLoader and SecureLoaderFactory.

At first you should create a SecureLoaderFactory object as shown here:

SecureLoaderFactory mSecureLoaderFactory = new SecureLoaderFactory(this);

This is an helper class necessary to generate a SecureDexClassLoader object. But before performing this step you have to initialize and provide to mSecureLoaderFactory an associative map which links all the package names of the classes that you want to dynamically load to one developer certificate, which is stored at a secure web location (i.e. an HTTPS link) and which was previously used to sign the jar or apk container which holds those classes.

Developer Certificate

a certificate, which in Android can be even self-signed, used to sign all the entries contained in a jar or in an apk container. Notice that in the Android environment in order to run an application on a smart phone or to publish it on a store, the signing step is mandatory and can be used to check that an apk was actually written and approved by the issuer of the certificate. For more details on signing applications and certificate, please check here.

So in this example we assume that all the classes belonging to the package com.example have been signed with a self-signed certificate, stored at https://something.com/example_cert.pem. Since here you just want to load com.example.MyClass the following snippet of code is enough:

Map<String, URL> packageNamesToCertMap = new HashMap<String, URL>();
try {
        packageNamesToCertMap.put(      "com.example",
                                        new URL("https://something.com/example_cert.pem"));

} catch (MalformedURLException e) {
        // The previous URL used for the packageNamesToCertMap entry was a malformed one.
        Log.e("Error", "A malformed URL was provided for a remote certificate location");
}

Now it comes the time to initialize a SecureDexClassLoader object through the method createDexClassLoader() of SecureLoaderFactory:

SecureDexClassLoader mSecureDexClassLoader =
        mSecureLoaderFactory.createDexClassLoader(      jarContainerPath,
                                                        null,
                                                        getClass().getClassLoader(),
                                                        packageNamesToCertMap);

mSecureDexClassLoader will be able to load the classes whose container path is listed in jarContainerPath and it will use the packageNamesToCertMap to retrieve all the required certificate from the web and import them into an application private certificate folder. Also notice that in this case no directory to cache output classes is needed since SecureDexClassLoader will automatically reserve such a folder.

jarContainerPath = "http://something.com/dev/exampleJar.jar";

Finally you can use the resulting mSecureDexClassLoader to load the desired class in a similar fashion to DexClassLoader:

try {
        Class<?> loadedClass = mSecureDexClassLoader.loadClass("com.example.MyClass");

        // Check whether the signature verification process succeeds
        if (loadedClass == null) {

                // One of the security constraints was violated so no class
                // loading was allowed..
        }
        else {

                // Class loading was successful and performed in a safe way.
                myClassInstance = (MyClass) loadedClass.newInstance();

                // Do something with the loaded object myClassInstance
                // i.e. myClassInstance.doSomething();
        }

} catch (ClassNotFoundException e) {
        // This exception will be raised when the container of the target class
        // is genuine but this class file is missing..
        e.printStackTrace();
} catch (InstantiationException e) {
        e.printStackTrace();
} catch (IllegalAccessException e) {
        e.printStackTrace();
}

It is important to notice that, differently from DexClassLoader, the mSecureDexClassLoader.loadClass() call will return null whenever at least one of the following security constraints is violated:

• The package name of the class used as a parameter of loadClass() was not previously included in the associative map and so it do not exist any certificate that could be used to validate this class.
• The package name of the class used as a parameter of loadClass() was previously included in the associative map but the related certificate was not found (URL with no certificate file attached or no connectivity) or not valid (i.e. expired certificate, use of the Android Debug Certificate).
• The container file of the required class was not signed.
• The container file of the required class was not signed with the certificate associated to the package name of the class. [Missing trusted certificate]
• At least one of the entry of the container file do not match its signature even if the certificate used to sign the container file is the trusted one. [Possibility of repackaged container]

For all of these reasons you should always check and pay attention when a null pointer is returned after a mSecureDexClassLoader.loadClass() call since this is a clear clue to establish either a wrong set up of SecureLoaderFactoty and SecureDexClassLoader or a security violation. Informative and debug messages will be generated in the logs by the classes of the Grab’n Run library in order to help you figure out what it is happening.

Please notice, on the other hand, that the three exceptions caught in the try-catch block surrounding the loadClass() method behaves and are thrown in the same way as it would happen with DexClassLoader.

Finally for clarity the full snippet of code presented in this section is reported here:

MyClass myClassInstance = null;
jarContainerPath = "http://something.com/dev/exampleJar.jar";

try {
        Map<String, URL> packageNamesToCertMap = new HashMap<String, URL>();
        packageNamesToCertMap.put(      "com.example",
                                        new URL("https://something.com/example_cert.pem"));

        SecureLoaderFactory mSecureLoaderFactory = new SecureLoaderFactory(this);
        SecureDexClassLoader mSecureDexClassLoader =
                mSecureLoaderFactory.createDexClassLoader(      jarContainerPath,
                                                                null,
                                                                getClass().getClassLoader(),
                                                                packageNamesToCertMap);

        Class<?> loadedClass = mSecureDexClassLoader.loadClass("com.example.MyClass");

        // Check whether the signature verification process succeeds
        if (loadedClass == null) {

                // One of the security constraints was violated so no class
                // loading was allowed..
        }
        else {

                // Class loading was successful and performed in a safe way.
                myClassInstance = (MyClass) loadedClass.newInstance();

                // Do something with the loaded object myClassInstance
                // i.e. myClassInstance.doSomething();
        }

} catch (ClassNotFoundException e) {
        // This exception will be raised when the container of the target class
        // is genuine but this class file is missing..
        e.printStackTrace();
} catch (InstantiationException e) {
        e.printStackTrace();
} catch (IllegalAccessException e) {
        e.printStackTrace();
} catch (MalformedURLException e) {
        // The previous URL used for the packageNamesToCertMap entry was a malformed one.
        Log.e("Error", "A malformed URL was provided for a remote certificate location");
}

Wiping out cached containers and certificates¶

In order to improve performance and offer the possibility to partially work also when connectivity is limited, SecureDexClassLoader will store certificates retrieved from the web and all containers into specific application-private directories.

Every time that a resource (container or certificate) is needed to load or verify a class, SecureDexClassLoader will at first look for it inside its private directories and then, if no match is found, possibly attempt to download it from the web or found it at a specified location on the device (this last option is applicable only for containers).

Even if these caching features may come really useful and speed up significantly SecureDexClassLoader execution, it would be also nice for the developer to have the possibility to choose whether a fresh or cached copy of either a certificate or a container should be used for the dynamic loading operations. And that is the reason why SecureDexClassLoader provides a method called wipeOutPrivateAppCachedData() to manage this choice.

To present this method let us consider again the previous scenario shown in Using SecureDexClassLoader to load dynamic code securely: after having tried to load com.example.MyClass, if you want to delete both the cached certificates and the containers used by the related mSecureDexClassLoader, in order to impose for the next loading operation the retrieval of fresh resources, the call to perform is the following:

mSecureDexClassLoader.wipeOutPrivateAppCachedData(true, true);

Retrieve Grab’n Run full repository¶

At first you will need to recover Grab’n Run example code. In order to do so you need to have Git installed on your machine. The latest version can be found at Git download page.

Next open a terminal and clone the example repository into grab-n-run, a local folder located at absolute_path_to_gnr_repo, through Git:

$ cd <absolute_path_to_gnr_repo>
$ mkdir grab-n-run
$ cd grab-n-run
$ git clone "https://github.com/lukeFalsina/Grab-n-Run.git"

At the end of the process you will have all the GNR code locally including a copy of the example application and of the documentation.

Include Grab’n Run example code in your IDE¶

The next step is importing the example sources into an IDE. The process will be now described for both Android Studio (AS) and Android Development Tool (ADT).

1. Android Studio (AS)

In the welcome window of Android Studio select from the Quick Start menu the option “Open an existing Android Studio project”.

Next navigate to the grab-n-run folder in which you previously cloned the repository and then pick the project AS from the example subfolder as shown in the image below.

The example project should have been now successfully imported! It may be necessary to rebulit it again by picking the option “Make Project”.

P.S. Notice that you can open in Android Studio also the original GNR library project by using the very same procedure but by picking the gnr Studio project from the main grab-n-run folder in stead of the example/AS one.

2. Android Development Tool (ADT)

At first right click in the Package Explorer and select “Import..”

Next select under the Android folder “Existing Android Code Into Workspace” and then “Next >”

By pressing the “Browse...” button point the Root Directory to the grab-n-run folder in which you previously cloned the repository and then to the subfolder grab-n-run/example/ADT. You should be now able to the see and select the candidate project ExampleAppGNR (an example application which makes use of GNR). In the end press “Finish” to import the example project. Below you can see a screenshot which summarizes all the settings before the “Finish” button is clicked.

At the end of this process you should have been able to correctly import the example application!

Retrieve and set up the emulator¶

Then it is time to retrieve the emulator used to run the example application. You can easily find it in the assets folder of the example repository. So once that you have located the compressed file ExampleAppGNREmu.tar.gz containing the emulator, open a terminal and at first copy this file into your home folder:

$ cd <absolute_path_to_gnr_repo>/example/
$ cp ExampleAppGNREmu.tar.gz ~

Next decompress this container:

$ cd ~
$ tar xzf ExampleAppGNREmu.tar.gz

This operation will generate two files, a folder called ExampleAppGNREmu.avd and a configuration file ExampleAppGNREmu.ini. In the end move these two files into the Android emulator folder, normally located at /home/<your_username>/.android/avd:

$ mv ExampleAppGNREmu.avd ExampleAppGNREmu.ini .android/avd

The last step consist in editing the path variable stored in the configuration file. So open ExampleAppGNREmu.ini at the final location with a text editor and change the path variable in order to match the current location of the ExampleAppGNREmu.avd folder. So if my user name is for example bill90, I need to change the path variable from path=/home/<USER_NAME>/.android/avd/ExampleAppGNREmu.avd to path=/home/bill90/.android/avd/ExampleAppGNREmu.avd.

Before starting the emulator in your IDE, remember to verify that the SDK version 17 is installed on your machine since the emulator targets that version. Otherwise you can also edit the emulator configuration from your IDE to target a different and more recent version of the SDK which is installed on your machine.

When the emulator is finally set up, you can start it in either ADT Eclipse or Android Studio (it may take time depending on your machine..). Next, whenever you want to run the example code and the IDE asks which device should be used, remember to select this emulator as the running Android device.

In case you need to integrate this previous concise walk-through, please give a look at these other resources:

• https://blahti.wordpress.com/2011/08/24/how-to-export-and-import-android-virtual-device-avd-files/
• http://stackoverflow.com/questions/4575167/android-how-to-copy-the-emulator-to-a-friend-for-testing

setUpDexClassLoader()¶

In this method a standard initialization of a DexClassLoader is applied. So at first the usual application-private, writable directory for caching loaded .dex classes must be set up.

Then a DexClassLoader object is initialized using test.apk, a container located directly in the phone external storage ( as described by exampleTestAPKPath), as its jar path for the classes to load.

Finally the NasaDailyImage Activity is loaded. If such an operation is successful the simple name of the loaded class is shown to the user through a toast message; otherwise different exceptions are raised and show again through a toast message an appropriate helper message.

setUpSecureDexClassLoader()¶

In this method repeated loadClass() calls are performed on differently initialized SecureDexClassLoader instances in order to show different behaviors of the loader class while retrieving the usual NasaDailyImage Activity.

At first a SecureLoaderFactory object is created. Then this instance is used to generate three SecureDexClassLoader that covers different cases and ends up with different results on the load operation:

1. Test case 1: Load a class through SecureDexClassLoader without providing an associative map for certificates location

   This first test case shows a possible error that a developer may encounter when using this library for the first time. If you want to have the location of the certificate being computed by reversing the package name, as explained in Reverse package name to obtain remote certificate URL, you still need to populate an associative map with entries like (“any.package.name”, null) and use it as a parameter of the method createDexClassLoader(). To understand why the class works in this way think of this system as a kind of white listing. Only those classes inside package names which are declared into the associative map or directly descend from one of the declared package names will be considered as possible valid ones, while all classes belonging to a not listed package name or not a descendant of the declared ones will be immediately rejected.

   And this is exactly what happens in this test case where no associative map is provided and so all the classes in the two containers, including the target NasaDailyImage, are prevented from being loaded since there is no clue on the certificate location.

2. Test case 2: Unsuccessful load of a class through SecureDexClassLoader with an associative map (Debug certificate)

   In the second test case you can see different ways to populate the associative map packageNamesToCertMap, used to link packages with certificates location.

   Warning

   Always keep in mind that prior to downloading a certificate from the web the certificate for that package will be searched inside the application-private directory reserved for certificates and then possibly at the remote location. If you wish to just look at the remote URL without considering cached certificates, always remember to wipe out private application data through the invocation of the method wipeOutPrivateAppCachedData() before dismissing your SecureDexClassLoader instances. In such a way every time that a new SecureDexClassLoader is created, you will be sure that no cached resource will be associated with it.

   The first put() call inserts the package name headfirstlab.nasadailyimage of the class that we would like to load later in the example and associates it with a valid remote URL. What you can immediately notice by pointing your browser to that URL is that the remote certificate in this case is a self-signed developer one since the subject of the certificate is also the issuer of it but, as it is mentioned in the Quick start and tutorial, this is perfectly fine in the Android environment.

   The second entry inserted into the associative map provides a remote URL to an inexistent certificate (once again you can try to point there your browser to easy spot this out). More over since no certificate for the package name ``it.polimi.example`` has been already cached into the application-private certificate directory, then no certificate is available for it and that is the reason why any class belonging to the it.polimi.example package will be rejected and prevented from being loaded by SecureDexClassLoader.

   Lastly the third put() call on the associative map will insert a package name that will be also used to construct the remote certificate URL (reverse package name). Once again the final remote URL (https://polimi.it/example3/certificate.pem) points to no certificate so any class, whose package name is it.polimi.example3, will be rejected from being loaded.

   In the end a SecureDexClassLoader is generated using as a container file a valid apk containing the target class but signed with a certificate, the Debug Android Certificate, which is different from the one issued by the developer. For such a reason the result of the loadClass() method will be that no class object is going to be returned since the apk is not signed with the required certificate.

3. Test case 3: Unsuccessful load of a class through SecureDexClassLoader with an associative map (Failed signatures verification of some container’s entries)

   In the third test case you can immediately notice that all the settings for the invocation of SecureDexClassLoader are equals to those of the previous case except for the chosen apk container. In fact, while before the container was signed with a non valid certificate, this time the container is signed with the right certificate but someone modified a couple of the entries signature, which do not match anymore with the one obtained during the signing procedure. To sum up also in this case no class will be loaded since this container results to be partially corrupted and so not safe.

4. Test case 4: Successful load of a class through SecureDexClassLoader with an associative map

   In this last test case a successful example of dynamic code loading is shown. This time SecureDexClassLoader is initialized with a valid apk container, signed with the correct developer certificate, and with the associative map previously initialized in Test case 2. The whole process works fine since this associative map contains the necessary key entry headfirstlab.nasadailyimage and the related developer certificate has been already cached during Test case 2. Finally during the signature verification step inside the loadClass() method all the entries inside the container match properly with their signature and the certificate used for that signing process is exactly the one linked to headfirstlab.nasadailyimage package. That is the reason why dynamic loading of NasaDailyImage activity is allowed.

1. Export the project “MyLibrary” into a jar archive.¶

If your project was developed using Android Studio, you can easily obtain a copy of your jar library by opening a terminal and pointing it to the main folder of your project and then by invoking a series of tasks through the ./gradlew script as shown here:

$ cd <absolute_path_to_your_jar_lib_project>
$ ./gradlew clean build assembleRelease

If the build process goes smoothly, you should now be able to find a file presumably called “MyLibrary-release.jar” located under one of your project build/outputs folder.

On the other hand if you are relying on the ADT (Android Development Tool), right-click on the project “MyLibrary” and select “Export...”.

Then choose the option “Jar File” and click “Next...”.

Finally choose the location of the exported jar archive by clicking on the “Browse...” button and then “Finish”.

Independently from which of the two methods you implied, you should have now successfully exported your project into a jar container!

2. Translate Java Byte Code (.class) into Dalvik Byte Code (classes.dex).¶

After having exported your project into a jar container you now have code that can run on a Java Virtual Machine (JVM) in the form of class file with the extensions .class. Nevertheless in order to have your code running with SecureDexClassLoader on an Android phone it is necessary to translate the class files from Java Bytecode to Dalvik Bytecode. This task can be accomplished easily thanks to the dx tool, present in the Android SDK folder.

So by assuming that you have just exported the project into a file called myLibrary.jar in a terminal type the following commands:

$ cd <path_to_exported_jar>
$ /<path_to_sdk>/build-tools/<last_stable_sdk_version>/dx --dex --output=myLibrary-dex.jar myLibrary.jar

The result is an output jar container called myLibrary-dex.jar. You can easily spot that no .class file is stored in this container and in stead a file called classes.dex was added. This is the direct result of the translation mentioned before.

3. Generate a keypair and export the developer certificate¶

If this is the first time that you sign a container you will need to generate a key pair with keytool and then export a certificate containing the newly created public key. Otherwise if you already have a key pair and the associated certificate, simply skip this section and continue reading from the next one.

In order to generate a keystore and a key pair type in the following command line in a terminal:

$ keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000

This line prompts you for passwords for the keystore and private key, and to provide the Distinguished Name fields for your key. It then generates the keystore as a file called my-release-key.keystore. The keystore will contain a single key, valid for 10000 days. The alias is a name that you choose to identify keys inside the keystore. In this case this private key will be identified as alias_name.

If the previous step succeeded, now it is time to export your developer certificate that will be used by application developers to verify your library code before dynamically loading it. This can be accomplished again thanks to a keytool feature:

$ keytool -exportcert -keystore my-release-key.keystore -alias alias_name -file certificate.pem

This command will export the certificate embedding the public key associated to the private key whose alias is alias_name. This certificate will be stored in the file certificate.pem.

Even if the previous commands are all that you will need here, if you desire to deepen your knowledge on keystore, keys and signing Android applications visit these reference links:

• https://www.digitalocean.com/community/tutorials/java-keytool-essentials-working-with-java-keystores
• http://developer.android.com/tools/publishing/app-signing.html#signing-manually

4. Sign the library with the developer private key.¶

Now it is time to sign the jar library with the library developer private key to enable the possibility to verify it.

Assuming that you have generated a private key whose alias is alias_name and stored it in a keystore whose name is my-release-key.keystore in order to sign the jar container manually type in this line in your terminal:

$ jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore my-release-key.keystore myLibrary-dex.jar alias_name

You can then verify that the jar container is actually signed by typing:

$ jarsigner -verify -verbose -certs myLibrary-dex.jar

5. Make the library and the certificate publicly available.¶

The last step is making public the signed version of the jar container, obtained after the previous step, and the exported certificate embedding the library developer public key (as explained in 3. Generate a keypair and export the developer certificate ).

While you can store the library container basically everywhere on the web (application developers can retrieve your library via both HTTP or HTTPS protocol), it is crucial and fundamental for the whole security model to handle that you publish your library developer certificate on a secure trustworthy remote location which can be accessed only via HTTPS protocol.

If you have successfully followed up all the previous steps, you have now correctly published your library and application developers will be able to run your code securely by using SecureDexClassLoader.

Step 1: Select the application to patch¶

Select the application you want to patch to use the secure Grab’n Run APIs. Notice that this application must be a regular APK file, which is stored locally on your machine.

It is not required for this container to be aligned, or signed, but notice that you will have to sign, and then align the final application generated by the script in order to have it installed on the user’s devices.

If you are not familiar on how to sign, and align an APK, you may want to check the third bullet point of the “Quick example of use” section in the README file of the Grab’n Run repository on GitHub.

Step 2: Select the containers sources for DCL¶

Next step is listing all the JAR, or APK containers used by your application as sources for dynamic code loading. Each container can be either stored locally (in this case indicate the absolute path on the file system), or remotely on an endpoint (in this case simply type the URL pointing to the file, and notice that both HTTP and HTTPS protocol are supported).

The screenshot below shows the first screen of the UI with an example of a feasible configuration for Step 1 and Step 2.

Step 3: Configure the security policy for the source containers¶

Once you confirm the settings in the first window, you will be prompted with a new screen to decide against which certificate each source container should be verified by Grab’n Run. At the moment we support three policies:

1. Evaluate all the containers against one certificate.
2. Evaluate each container against a different certificate.
3. Provide a validation mapping, which has on the left side the prefix of the package name of the involved classes, and on the right side the corresponding certificate to use for the evaluation.

The three screenshots below show an example of a valid configuration for each of the three policy. Switching from one to another is as simple as picking a different value in the drop-down menu box on top of the UI.

Some further considerations for this step:

• You must provide each certificate through a remote reference to a secure endpoint containing such resource. The use of HTTPS protocol for the endpoint is required, and, if this is not the case, the repackaging tool will enforce it.
• For the first two policies you can select as source containers either archives stored locally on your machine (use the absolute path of these resources on the file-system), or a remote endpoint containing such container (use its URL). In the latter case the repackaging tool will take care, when started, to retrieve these containers for further analysis. For these two policies, you can optionally also provide a default certificate that will be used for evaluating any other source container, which was not listed in the previous step but is used by your application at run time.
• For the third policy the most restrictive package name prefix will be applied during the evaluation: This means that if your application wants to load code for a class, whose full name is com.example.myapp.MyClass, and you have two entries in your mapping, one for com.example and the other for com.example.myapp, the certificate associated to the latter one will be used since this entry has a longer prefix matching the name of the class to load. You should consider to use the last policy only if you are really aware of how the system works (see Quick start and tutorial, and Complementary topics for further details on the mapping process); in general, using one of the two first policies is already enough for most of the use cases, and it avoids pain from your side since the tool handles automatically the process of generating a validation mapping from your settings.

Step 4: Gotta patch them all!¶

Once you enter your settings and you press the “Finish” button, the repackaging tool will start its execution. If no error is raised, the patched APK will be available in the main folder where you launched the script from terminal (take extra care of having the original application in a different folder unless you want it to be overwritten by the patched version).

I hope you will find this tool useful and I am eager to hear your feedbacks :)