Using Apache* Cordova* Whitelist Rules

Domain whitelists and Content Security Policy (CSP) rules comprise the basis of the security model Apache* Cordova* applications use to control which external resources your app is allowed to access (the HTML5 hybrid mobile apps created by the Intel XDK are standard Apache Cordova apps). The default Cordova security policies specified by the Intel XDK blank templates allow access to any external resource (they are set, by default, to be permissive). Most of the Intel XDK sample apps include whitelists and CSP rules that explicitly limit their external resource access to only those needed by the sample app. Before publishing your app you should define whitelist and CSP rules that limit external access to only the external resources your app requires, in order to maximize the security of your app and its data. This article will direct you on how to find information to set those policies for your application.

Please read Cordova Whitelisting with Intel® XDK for AJAX and Launching External Apps for details regarding how to configure and setup your whitelist rules in the Intel XDK. 

NOTE: Your application runs in the context of a WebView, which can be thought of as an embedded browser in the device on which your app runs. This WebView, and the target device and operating system it is running on, ultimately determines the security model and security options available to insure the safety of your app and its data. For more information about what a WebView is read When is an HTML5 Web App a WebView App?.

Defining Whitelist Rules

When no whitelist rules are defined, all network accesses are blocked. The rules you supply within the "Whitelist" option in the Build settings section of the Projects tab declare the network and resource domains your application can access. Your whitelist controls access to external resources whether that access is requested through an API (e.g. XMLHttpRequest) or via markup (e.g. <iframe>, <script>, <img>).

A "Block All" option is provided so you can force all external accesses by your application to be blocked. This is the recommended setting if your app does not require any external resources. This setting also guarantees that the whitelist plugin is not included with your app and that no whitelist preferences are included in your build config file.

NOTE: whitelist rules ONLY apply to built apps. The Simulate, Test and Debug tabs do not use the whitelist rules defined in your project settings. These debug tools are permanently configured to allow unrestricted external access. If you need to test your whitelist rules you MUST test them using a built app installed on a real device.

Behind the Scenes

An external access request is a request made by any code running within the application's Cordova WebView (the web app runtime). Whitelist rules define the Cordova app's behavior regarding how to respond to requests for access to external resources.

The app execution scope is the execution context for code running from documents (files) that are part of the app package. The external execution scope is the execution context for code running from documents (files) that originate outside the app package.

At runtime, when a request is made to access a network resource from within the app execution scope, the Cordova WebView compares the request against the whitelist rules. Granting access to an external resource, via a whitelist rule, means that the code running within the WebView context authorizes access to the external context. In other words, the Cordova WebView interprets the rules to decide when to authorize and when to deny an access request.

Detailed Whitelist Rules

It is recommended that you use CSP rules whenever possible!!

The following documents provide details for the various whitelist rules. Please read them carefully to determine how best to specify the whitelist and CSP rules for your application.

Windows Phone 8.x and Windows 8.x devices provide partial support of CSP rules via the X-Content-Security-Policy directive (Windows Phone 8.x and Windows 8.x devices run on IE10 and IE11 mobile webviews). Windows 10 devices include full support for standard CSP directives (Windows Phone 10 and Windows 10 tablets and laptops run on the Microsoft Edge webview).

To get started, include the following very long and dangerously permissive directive in the <head> section of your index.html file (let your mouse hover over the code fragment shown below and then select (click) the "view source" icon to open a code window from where you can view and copy the entire CSP rule):

<meta http-equiv="Content-Security-Policy" content="default-src 'self' 'unsafe-eval' data: blob: filesystem: ws: gap://ready file: cdvfile: https://ssl.gstatic.com *; style-src * 'unsafe-inline'; script-src * 'unsafe-inline' 'unsafe-eval'; img-src * data: 'unsafe-inline'; connect-src * 'unsafe-inline'; frame-src *; worker-src *; child-src *;">

There is no single CSP directive that can be recommended for all applications. The correct CSP directive is the one that provides the access you need while simultaneously insuring the protection necessary to keep your app from being compromised and exposing customer or user data.

This StackOverflow post is very helpful to read as an introduction to how Content Security Policy rules work.

Whitelist Idiosyncrasies

The following commentary is based on an example that is specific to iOS whitelisting. Unfortunately, the Cordova whitelisting behavior is unique to each platform (Android, iOS, Windows, etc.) and cannot be easily generalized.

Due to the nature of Cordova’s whitelisting features, there are many edge cases and subtleties. This makes it difficult to provide accurate high-level guidance – any whitelist guidance is likely to have important details omitted that are relevant to specific cases. The exact configuration and implementation details are important in order to understand whitelisting behavior. When it comes to whitelisting, one must be cautious about high-level generalizations, as this case illustrates.

Based on this Intel XDK forum thread, if an iOS app is configured with the tel:* whitelist intent entry, the expectation is that all "tel:" URIs will work in your app.

However, in the test app provided in the above-mentioned forum thread, the developer says that they “hooked up a button” to test this but it did not work until they also added an ‘allow-navigation’ tel:* directive. Given this description, it is possible to reproduce this behavior, as follows:

Although it is not documented, the whitelist implementation for cordova-ios@4.1.0 (aka Intel XDK CLI 5.4.1) only applies the allow-intent directives to click events on anchor tags using an href. That is, something like the following will work when providing just an intent directive:

<a id="tel-a" href="tel:777777777">make phone call with "a.href"</a>

However, the following examples will not work when only an intent directive is provided:

<a id="tel-a-onclick" onclick="document.location.href='tel:777777777';">make phone call with "a.onclick"</a>
<button id="tel-button" onclick="document.location.href='tel:777777777;'">call with "button.onclick"</button>

This is because the intent whitelist is only being applied to anchor tags. Therefore, although tel:* is whitelisted, and these are tel:* intent requests, they will not be allowed by the Cordova iOS whitelist mechanism, because the Cordova iOS intent whitelist entries are only being applied to requests originating from anchor tags that use an href declaration.

As noted in the thread, adding an allow-navigation directive enables all of the above examples to work (with the side-effect that the allow-intent directive is then not required).

The particular Cordova whitelist behavior described in this example was changed in an August, 2016 commit to the cordova-ios platform framework code. However, that fix will likely not be "live" in the Intel XDK build system until later in the year.

It is important to note that:

  • Whitelist behavior varies as a function of target platforms (Android, iOS, Windows, etc.).
  • Whitelist rules and behavior vary with Cordova platform versions (aka CLI versions in the XDK).
  • Content-Security-Policy (CSP) whitelisting rules may vary between platforms and webview versions.
  • Getting your whitelist rules to work requires patience and perseverance, they are confusing!
  • Whitelist rules and behavior are not governed by the Intel XDK, they are determined by Cordova and the target platform webviews.

Obsolete Cordova Whitelist and W3C Widget Access Options

The Cordova-Android 4+ and Cordova-iOS 4+ frameworks used an external resource access security policy that is configured by a special Cordova whitelist plugin. Older Cordova-Android and Cordova-iOS frameworks (<4.0) and any version of non-Android and non-iOS platforms (such as Windows) use the W3C Widget <access> specification to control access to external resources. The new Cordova security policy provides better security and more configuration options than the W3C widget <access> mechanism used by these other Cordova frameworks.

NOTE: Cordova apps based on Cordova CLI 4.1.2. The CLI 4.1.2 build system creates cordova-android@3.6.4 applications and cordova-ios@3.7.0 applications.

If the "Cordova Whitelist" option is available in the Build Settings section of the Projects tab, you should use that option for its more secure Cordova whitelist mechanism. You should always define a whitelist that limits external access to only the resources needed by your app, to maximize the security of your app and its data.

For details regarding the "old" W3C Widget Access whitelist rules, which apply only to now obsolete versions of the Intel XDK, see this list of articles:

For more complete information about compiler optimizations, see our Optimization Notice.