Configuration of Shielding Tool Rules on Android

You can specify a rules list in the App Shielding configuration. This list determines how App Shielding will modify the Android application, especially with regards to shielding and obfuscation.

Find below information about how the rules list can be used to match classes, fields, and methods to resolve issues with shielding or obfuscation.

Syntax

class_op+ [[!]@annotation] [[!]access] [[!]flag]* [[!]class_spec] class_name [[!]extension class_name] (; | { 
  [member_op]* [[!]@annotation] [[!]access] [[!]flag]* [member_type] 
  [return_type] member_name [method_arguments];
})

You can specify as many rules as needed, and the rules are matched from top to bottom.

When configuring rules, you can use one line per rule, or, for better readability, you can use multiple lines for one rule.

# Comment
class_operation [[!]access] [!]class_spec class_name [[!]extension class_name] (; | {
[[!]access] [[!]class_mod] member type name;
})
set_operation name value;
firstdex class_name;
verify regex;

Definitions

The following tables list the commands to be used in a rules list.

List of operation options

List of class_operation options

List of member_operation options

List of class and member definitions

Specification

Negating

For the rules, most class specifiers can be negated by adding an exclamation mark in front of them.

Wildcards

Wildcards can be used as follows:

• * matches zero or more characters.

• + matches one or more characters.

• ? matches exactly one character.

*Test matches MyTestOne and Test but not TestTwo.

Comments

Comments are prefixed with #.

# Verify a single file
verify "assets/my-asset.bin";

# Verify all files in the assets folder
verify "^assets/.*";

# Verify all HTML/JS in the assets folder
verify "^assets/(.+)\.(html|js)$";

# Verify all files inside the APK
verify ".*";

Binding

Using the untouchable or unbind operation will ensure that a matching class, method, or field will not be affected when values are removed during the binding operation. Optionally, the bind operation asks the Shielding Tool to include the specific value in the binding process (which would most likely bind the value regardless).

After shielding, the performance of the application can be impacted at startup. In this case, exclusion options can be defined to reduce the impact of shielding on the application.

The security provided by App Shielding is reduced by excluding classes from the shielding process. The number of bindings must be high enough to ensure security requirements (more than 2,000 push/pull bindings).

Since certain parts of the app code need to run for App Shielding to be launched, the shielding process will automatically trace and mark the relevant parts as untouchable: they cannot be modified in any way.

By default, the <clinit> class initializers, all variables, and method calls called from these are marked as untouchable. In some cases, however, tracing is not possible because the method call flow cannot be determined. Issues may occur especially with code reflection or provider classes in the Android manifest.

For these cases, a generic way to exclude classes and methods in a declarative manner is available so that the shielding process will not modify them in any way by marking them as untouchable.

String scrambling

Using the keepStrings operation will ensure that a matching class, method, or field will not be affected by the string scrambling operation. Optionally, the scrambleStrings operation asks the Shielding Tool to scramble string values.If both bind and scrambleStrings are enabled for a class or method, some constants are used for push and pull binding, and the remaining constants are used for string scambling.

Obfuscation

Using the preserve operation will ensure that a matching class, method, or field will not be affected when renamed as part of the obfuscation process.

Enabling obfuscation is not a mere ON / OFF feature. Rules must be configured manually. The effort to fine-tune the configuration is comparable to the one required to fine-tune similar commercially available obfuscation tools.

Repackaging checks

App Shielding checks at the start of the application if the application is repackaged. The repackaging check consists of three parts:

• Check that all expected files are present, that is, no file was removed.

• Check that no unexpected file was added to the apk.

• Verify the file integrity of a few selected files, that is, verify that the content of the file was not modified.

If the repackaging check fails, App Shielding reports the app as repackaged.

By default, all files that are present in the application when integrating App Shielding are expected, although there are a few well known exceptions. For example, Google Play inserts some files on converting an app bundle to an apk before the apk is installed.

By default, App Shielding verifies the file integrity of:

• AndroidManifest.xml

• classesX.dex

• the App Shielding library.

For more information about repackaging, see Repackaging detection.

# Verify a single file
verify "assets/my-asset.bin";

# Verify all files in the assets folder
verify "^assets/.*";

# Verify all HTML/JS in the assets folder
verify "^assets/(.+)\.(html|js)$";

# Verify all files inside the APK
verify ".*";

By default, not all application files are specifically checked at startup for possible application launch time performance considerations. Integrity checks of large files may cause noticeably longer launch times.

Amazon App Store and repackaging checks

Amazon App Store will modify your application’s files. For all applications, Amazon App Store will also inject some code and files into the application, which for most applications also shuffles the classes in the apps' classesX.dex files. Since this modification would trigger the default repackaging checks of App Shielding, the file integrity checking must be tuned for apps published on Amazon App Store.

Due to the changes, the file integrity checking for Amazon App Store must be tuned for Amazon App Store.

The Shielding Tool has a built-in rules file, builtin:amazon-app-store-support.cfg, for the Amazon App Store. To use the file, you must use the following in your rules file:

include "builtin:amazon-app-store-support.cfg";

These rules will skip the classesX.dex files and the files that are known to be injected by Amazon App Store. The content of builtin:amazon-app-store-support.cfg:

# Amazon App Store modifies classes.dex, all the classesX.dex files must be skipped
skipVerifyPath "classes*.dex";

# Amazon App Store injects these files
skipVerifyPath "com.amazon.*";
skipVerifyPath "kiwi";

Rule examples

Class-level rule

• No values from MyClass will be removed:

  untouchable class com.example.MyClass;

• No values from any class inside the com.example.* package will be removed:

  untouchable class com.example.*;

• No class that implements MyInterface will be modified:

  untouchable class * implements com.example.MyInterface;

• No class that (immediately) derives from MyBaseClass will be modified:

  untouchable class * extends com.example.MyBaseClass;

Method-level rule

• This rule only matches the public static method getValue that returns int within MyClass:

  untouchable class com.example.MyClass
  {
    public static method int getValue;
  }

• This method matches any public method called getValue and setValue in any class that implements SomeInterface. All other methods in these classes can still be modified:

  untouchable class * implements SomeInterface
  {
    public method * getValue;
    public method void setValue;
  }

• To match a constructor, it must be added as a regular method <init> with a void return value:

  untouchable class * implements SomeInterface
  {
    public method * getValue;
    public method void setValue;
  }

Troubleshooting

For detailed information about troubleshooting, see the Troubleshooting Guide.

Troubleshooting the shielding of an app

If you experience issues (e.g. the application does not start properly), you may need to exclude certain classes from the binding process. For detailed information, see Binding.