Binding rules

The Shielding Tool rule files support the following binding-related options:

Note that you would rarely need to include a specific value in the binding process, as App Shielding will most likely bind the value, regardless. If you are using reflection, however, the affected classes and members could cause issues and should be manually marked as untouchable or unbind.

Binding can also affect performance, especially for classes and methods that are frequently called during runtime. If performance becomes an issue, consider excluding heavily used classes/methods from the binding process.

Examples

The following example excludes binding in MyClass:

unbind class com.example.MyClass;

The following example excludes binding in any class under the com.example package:

unbind class com.example.*;

The following example excludes binding in any class that implements MyInterface:

unbind class * implements com.example.MyInterface;

The following example excludes binding in any class that extends MyBaseClass:

unbind class * extends com.example.MyBaseClass;

The following example excludes binding to the myField field under MyClass:

match class com.example.MyClass {
    unbind java.lang.String myField;
}

The following example excludes binding in any static constructor (i.e., clinit):

match * {
    unbind method <clinit>;
}

The following example excludes binding in any constructor:

match * {
    unbind <init>;
    unbind <clinit>(...);
}

Binding Styles

The bindingStyle option is used to configure a set of pull and push binding rules to apply with the bind keyword. The syntax looks like the following:

bindingStyle my-rules {
    pull { ... }

    push { ... }
}

bind:my-rules *;

In the above example, the binding style has a custom name of my-rules and is applied to all classes and methods (*). Styles can also be applied to more specific selectors (e.g., bind:my-rules com.example.*;).

Pull Bindings

Pull bindings rewrite the app code to retrieve values from native calls to App Shielding. Binding styles can control the number of pull bindings to use for integers and strings. The default configuration looks like the following:

bindingStyle default-bindings {
    pull {
        max-integers 0
        max-strings all
    }
}

bind:default-bindings *;

The max-integers and max-strings options can be set to one of the following:

Pull bindings make it more difficult to remove App Shielding from the app, but they also add a performance overhead. Generally, it is good to keep the default string pull bindings and then add integer pull bindings, if you specifically want coverage for numeric values.

Push Bindings

Push bindings remove values from static class fields. Shield then re-inserts the values on first usage of the Java class. For example:

Currently, binding styles are only used to disable push bindings. For push bindings, binding styles only support disabling them altogether. For example:

bindingStyle no-push-bindings {
    push {
        max 0
    }
}

bind:no-push-bindings *;

This might speed up application launch time at the cost of security degradation and should only be used if the application launch is extremely slow.

Least Recently Used Cache

To improve performance, you can use the bindingCache option to specify which percentage of pull binding strings to store in a Least Recently Used (LRU) cache. For example:

bindingCache { max-size 4% }

Without an LRU cache in place, every retrieval of a pull binding string requires a call to a native method. This is more secure but comes with a performance cost. With the LRU cache enabled, the most recently used strings are stored on the Java side after their initial retrieval, reducing the number of native calls.

A good cache size depends on the application and how it uses strings, but 4% is a good starting point. If you integrate a debug version of App Shielding (using the --debug command line option), then you can monitor the cache activity in the logs and adjust the max-size based on your findings.

A cache log looks like the following example:

03-10 12:57:53.033 26159 26184 D ShieldSDK: Pull bindings LruCache[maxSize=185,hits=416,misses=110,hitRate=79%]

The logs contain the following information: