Configuration of App Shielding for Android apps

To configure App Shielding for your applications, select the options on the Configuration Page of the OneSpan Customer Portal as needed.

Debug your configuration

You can run your configuration in debug mode. Several security features are disabled in this mode to ease the testing of the app during development.

Debug mode must be disabled for a production app! When enabled, the shielded apk or aab is configured in debug mode (i.e. android:testOnly="true" in AndroidManifest.xml). The allow test packages option (i.e. -t) must be used when installing the apk or aab via adbto avoid the INSTALL_FAILED_TEST_ONLY error (e.g. adb install -t myapp.apk).

Configuration options for Android

QUERY_ALL_PACKAGES permission

With the declaration of the Query All Packages permission configuration option, Google restricts apps and packages from viewing other apps / packages installed on an Android device.

As of July 2022, Google Play has restricted the use of privacy sensitive Android permissions, such as QUERY_ALL_PACKAGES, for all new apps or app updates submitted.

An app with this permission can see and access details of all other installed apps on the device.

App Shielding does not require this permission by default, however, one feature — checkUntrustedInstaller — requires the QUERY_ALL_PACKAGES permission to work correctly.

The checkUntrustedInstaller configuration option is intended to be used for apps that require PCI compliance. When this feature is enabled, App Shielding will check if any apps are either side-loaded or installed from non-trusted app sources. This check is performed inside the app, and fundamentally depends on the QUERY_ALL_PACKAGES permission in order to work.

If an application needs to use the QUERY_ALL_PACKAGES permission, or otherwise requires the checkUntrustedInstaller configuration option to be enabled, then the application owner needs to use the Declaration Form in Google Play Console to get acceptance for using this permission.

If the application owner does not submit a declaration form, or if the permission has not been granted, any app updates may be rejected, or the application may be removed from Google Play.

The Shielding Tool normally enables required permissions automatically by default. However, the Shielding Tool will only enable QUERY_ALL_PACKAGES if both the queryAllPackagesPermission and checkUntrustedInstaller are enabled.

Only enable the queryAllPackagesPermission configuration option if this has been explicitly granted by Google Play.

Reference links: QUERY_ALL_PACKAGES Permission, Package visibility filtering on Android.

OneSpan strongly recommends reading the reference links before setting this value. If queryAllPackagesPermission is enabled, the Shielding Tool will insert android.permission.QUERY_ALL_PACKAGES permission to AndroidManifest.xml. Enabling the queryAllPackages permission is going to indicate to App Shielding and the Shielding Tool that the permission is granted by Google Play Console.

If the Query All Packages permission is disabled but e.g. the checkUntrustedInstaller check is switched on, the shielding of the application will fail because the checkUntrustedInstaller requires the Query All Packages permission to be enabled. In contrast, if both settings are either enabled or both are disabled, the shielded .apk file can be downloaded from the OneSpan Customer Portal or OneSpan Mobile Portal.

Application signer certificate

This option provides the certificate used to sign and verify the app, and can be configured in this field. When App Shielding verifies the signature of the application, it will then validate if the configured certificate matches.

If this value is not set, or is set incorrectly, then App Shielding will consider the app as repackaged.

This public certificate can be safely extracted from the keystore you will use to sign the app. Upload the certificate in .pem, .der or .cer format. It can be exported from the keystore using the following command:

keytool –keystore $keystore_file –storepass $keystore_password –alias $keyname –exportcert –rfc –file cert.pem

If the original application is already signed, it is possible to insert the original certificate with the Original certificate option.

Shutdown immediately

This option determines whether to exit the app immediately when a security policy problem is detected. If this option is enabled, the app will simply exit as soon as possible. If this option is disabled, an error reporting will be processed, andApp Shielding will throw a Java exception and give the user a 30-second grace period to report the problem to Google Play.

A 30-second grace period gives an attacker a time window to perform an attack on the app, even after the app has shut down. However, shutting down immediately may have some side effects such as Android re-launching the app. This may lead to the app launching and exiting in an infinite loop on most Android devices and should therefore be used with care.

For more information about error reporting, see App Shielding Error Reporting.

Updatable configuration

With this option, you can specify whether the app will use the Automatic Configuration feature.

When you enable this option, the portal displays additional configuration fields:

• Request timeout (seconds): Specify the duration in seconds before the client device stops connecting to the server and sends a request timeout error.

• Config Identifier: Identify for which application the configuration update is intended. A configuration update file must contain the identical config identifier as the original configuration for the app, and must be created with the exact same version of App Shielding.

  If not specified or set to an empty string, the config identifier is set to the package ID of the app, which means that any configuration update for the app must be created with the same input app. However, using the config identifier option allows for multiple apps to use a common source for the updatable configuration file.

• Certificate type: Use this field to upload your server certificate in the .pem file format.

• URL: Specify the URL of the web page where the configuration can be downloaded. The server must be running with a config.dat file accessible in the destination path.

  It is possible to use substitution variables encoded in the URL, consistent with the substitution variables launching Exit URL. For more information, see URL variable substitution for the updatable configuration.

• Client Certificate: Upload a TLS client certificate. This must be exported as a base64 string from a pkcs12 file.

  The base64 string can be extracted from the pkcs12 file using this command:

  base64 client_cert.p12 > client_cert.b64

• Password: Password used to generate the pkcs12 client certificate file.

Launch performance

With very large apps, launch times can suffer from having a very large number of bindings. The purpose of binding is first and foremost to ensure that the app cannot be decoupled from App Shielding to run the app in a less secure manner. However, after a certain point of adding bindings, no real value or benefit is added from a security point of view.

If the app becomes too slow during launch, the following options can be explored to reduce the number of bindings extracted:

• Limit binding on classes
• Limit binding on methods
• Disable push binding

The options to limit bindings per class and method minimize the number of bindings per class and method, respectively, ensuring that there is at least one such binding. This will reduce the number of bindings significantly for most apps, and at the same time retain a good distribution of bindings.

The downside of using these options is that constants such as strings are not as aggressively removed from the code, which reduces the obfuscation side-effect of binding.

Configuration of Shielding Tool rules

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.

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 #.

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

To identify issues in cases where the application cannot be started after successful application wrapping, you need to disable all bindings and obfuscation.

This can be achieved by creating new exclusion rules, to which you need to add the following:

1. # disable all bindings
2. untouchable class *;

These lines will ensure that no bindings are created for any parts of the application.

Update your configuration to disable obfuscation. This version of the shielded application should work with these settings, since App Shielding has made very few changes to the application.

At this point you can try re-enabling features one by one.

1. Re-enable bindings gradually (see Troubleshooting the shielding of an app). This can be somewhat time consuming in certain cases.
2. (Optional) Enable full app obfuscation if you wish to obfuscate the entire app.

The effort needed to enable obfuscation is not fully automatic, and is comparable to the effort needed when integrating ProGuard and other similar code shrinking and obfuscation tools.

Troubleshooting the shielding of an app

This section provides an overview of classes you may need to exclude from the binding process if you experience issues (e.g. the application does not start properly).

• If the application terminates unexpectedly during startup, it may be useful to attempt to run the application without any form of binding first. This can be done by adapting the exclusion list and adding a line that excludes all classes:

  untouchable *;

  If the application can be started, try to identify the class, method, or field that is causing the problem.

• In the event of general binding problems, you will get an exception and stack trace in the log. This message may vary significantly from case to case, depending on the cause, but always includes ClassNotFoundException.

  D/dalvikvm( 6367): Added shared lib 
  /data/data/com.example.mytestapp/files/libshield.png 0 ← x4273ffb0

  In this case, App Shielding is loaded as a library by the runtime, and the process ID is 6367.

  Now, you need to locate messages related to the same process ID, for example:

  W/dalvikvm( 6367): Exception Ljava/lang/NullPointerException; thrown while
  initializing ← Lcom/example/mytestapp/BadClass;
  I/dalvikvm( 6367): Rejecting re-init on previously-failed class
  Lcom/example/mytestapp/ ← BadClass; v=0x0

  From this message, it is clear that Dalvik attempted to initialize the class BadClass, but failed due to a NullPointerException.

  To resolve this, add the following rule to the rules list:

  untouchable class com.example.mytestapp.BadClass;

  Now, you can re-wrap the application.