Cordova CLI 5.1.1 and Higher
Starting with Apache* Cordova* CLI 5.1, the whitelisting security model that restricts and permits access to other domains from the app has changed. It is recommended that before you move your app to production you should provide a whitelist of the domains that you want your app to have access to.
Android
Starting with Cordova Android 4.0, your Android app's security policy is managed through a Whitelist Plugin and standard W3C Content Security Policy (CSP) directives. The Android Cordova whitelist plugin understands three distinct whitelist tags:
- <access> tag for Network Requests
- <allow-intent> tag for Intent Requets
- <allow-navigation> for Navigation
CSP directives are set by including a meta-tag in the <head> section of your index.html file. An Introduction to Content Security Policy is a good place to go to understand how to configure and apply these whitelist rules to your app. The CSP Playground is also a very useful site for learning about CSP and validating your CSP rules.
iOS
Unlike Android, your Cordova iOS app's whitelist security policy is managed directly by the cordova-ios framework. Cordova iOS versions prior to 4.0 used only the W3C Widget Access specification for domain whitelisting (i.e., the <access> tag). Starting with Cordova iOS 4.0, your Cordova iOS app's whitelist uses the <access> tag, as before, and adds support for two additional tags: <allow-intent> and <allow-navigation> as described in the Whitelist Plugin.
Starting with iOS 9, a scheme called Application Transport Security (ATS) is used to implement whitelist rules. Cordova automatically converts your <access> and <allow-navigation> tags to their equivalent ATS directives. When used with iOS apps, the <access> and <allow-navigation> tags support two new attributes for extra security for a domain whose security attributes you have control over. They have their equivalents in ATS:
- minimum-tls-version
- requires-forward-secrecy
See the ATS Technote for more details.
Windows
On Windows platforms, Cordova continues to use the W3C Widget Access specification to enforce domain whitelisting, which is built into the Cordova Windows framework.
See the following section for information regarding CSP directives and the Windows platforms.
Content Security Policy (CSP)
CSP is managed by the webview runtime (the builtin web runtime on which your Cordova app executes). Network requests include such actions as retrieving images from a remote server, performing AJAX requests (XHR), etc. CSP controls are specified in a single meta tag in your html files. Most Cordova apps are single-page apps, meaning they have only a single index.html file. If your app contains multiple html files, it is recommended that you use CSP <meta> tag on all of your pages.
Android version 4.4 (KitKat) and above supports the use of CSP (the Android 4.4 native webview is based on Chromium 30). If you are using the Android Crosswalk webview, CSP is supported on Android version 4.0 (Ice Cream Sandwich) and later (the Crosswalk webviews are also based on Chromium).
Apple iOS 7.1 and later supports the use of CSP directives (Apple iOS devices run on the Safari webview).
Windows Phone 8.x devices provide partial support via the X-Content-Security-Policy directive (Windows Phone 8.x devices run on the IE10 and IE11 mobile webviews). Windows 10 devices include full support for standard CSP directives (Windows Phone 10 and Windows 10 tablets run on the Edge webview).
It is recommended that you use CSP whenever possible!!
To get started with CSP, you can include the following overly permissive directive in the <head> section of your index.html file:
<meta http-equiv="Content-Security-Policy" content="default-src 'self''unsafe-eval'data: blob: filesystem: ws: gap: cdvfile: https://ssl.gstatic.com *; style-src * 'unsafe-inline'; script-src * 'unsafe-inline''unsafe-eval'; img-src * data: 'unsafe-inline'; connect-src * 'unsafe-inline'; 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.
Intel XDK 3088 and Higher
Starting with Intel XDK version 3088, the UI provided to specify whitelist entries has changed to accommodate changes in Cordova whitelist rules. Please read the rest of this document to understand how to specify whitelist entries in the Intel XDK.
Network Request Whitelist (<access>):
Network Request controls which network requests, such as content fetching or AJAX (XHR), are allowed to be made from within the app. For those webviews that support CSP, it is recommended that you use CSP. This whitelist entry is intended for older webviews that do not support CSP.
These whitelist specifications are defined in a Cordova CLI config.xml file using the <access origin> tag. Within the Intel XDK UI you specify your URLs in the Build Settings section of the Projects tab. For example, to specify http://mywebsite.com as a whitelisted URL:
By default, only requests to file:// URLs are allowed, but Cordova applications by default include access to all website. It is recommended that you provide your whitelist before publishing your app.
Intent Whitelist (<allow-intent>):
The intent whitelist controls which URLs the app is allowed to ask the system (ie., the webview) to open. By default, no external URLs are allowed. This applies to inline hyperlinks and calls to the window.open() function (note, if you are using the inAppBrowser it may change the behavior of window.open(), especially regarding whitelist rules). You app can open "hyperlinks" like a browser (for http:// and https:// URLs) and can "open" other apps via hyperlinks, such as the phone, sms, email, maps etc.
To allow your app to launch external apps through a URL or via window.open(), specify your rules in the Build Settings section of the Projects tab.
Navigation Whitelist (<allow-navigation>):
The navigation whitelist rules control which URLs the application webview can be navigated to. Only top level navigations are allowed, with the exception of Android, where it also applies to iframes for non-http(s) schemes. By default, you can only navigate to file:// URLs.
Additional Whitelist Settings for iOS ATS:
The UI whitelist settings for iOS are similar to those described above, with the addition of an ATS setting. When you click the "Edit ATS settings" link you can specify ATS settings for the Network Request and Navigation whitelist rules on your iOS 9 device. ATS settings do not apply to iOS 8 and earlier devices.
Most users should not have to change the ATS settings and can use the default values. For more details about ATS you can read this tutsplus.com article or search the web for additional articles.
The ATS settings dialog looks like this:
Windows Platform Whitelist Rules:
Windows platforms use the W3C Widget Access for whitelisting (that is, the <access> tag). Windows 10 also supports the <allow-navigation> tag. The rules for those tags are consistent with those described above. The Windows platforms also support CSP whitelist rules, which were described in the CSP section above.
Intel XDK versions prior to 3088:
Navigation Whitelist :
Navigation Whitelist controls which URLs the WebView can be navigated to. (Only top level navigations are allowed, with the exception,for Android it applies to iFrames also for non-http(s) schemes.) By default, you can only navigate to file:// URLs. To allow other URLS, <allow-navigation> tag is used in config.xml file. With the Intel® XDK you need not specify this in config.xml, the Intel XDK automatically generates config.xml from the Build settings.
In the Intel® XDK you specify the URL that you would like the WebView to be navigated to under Build Settings > Android > Cordova CLI 5.1.1 > Whitelist > Cordova Whitelist > Navigation. For example : http://google.com
Intent Whitelist:
Intent Whitelist controls which URLs the app is allowed to ask the system to open. By default, no external URLs are allowed. This applies to only hyperlinks and calls to window.open(). App can open a browser (for http:// and https”// URLs) or other apps like phone, sms, email, maps etc. To allow app to launch external apps through URL or launch inAppBrowser through window.open(), <allow-intent> tag is used in config.xml, but again you need not specify this in config.xml, the Intel® XDK takes care of it through Build settings.
In the Intel® XDK specify the URL you want to whitelist for external applications under Build Settings > Android > Cordova CLI 5.1.1 > Whitelist > Cordova Whitelist > Intent. For example http://example.com or tel:* or sms:*
Network Request Whitelist:
Network Request Whitelist controls, which network requests, such as content fetching or AJAX (XHR) etc. are allowed to be made from within the app. For the web views that support CSP, it is recommended that you use CSP. This whitelist is for the older WebViews that do not support CSP. This whitelist is defined in the config.xml using <access origin> tag, but once again in Intel® XDK you provide the URL under Build Settings > Android > Cordova CLI 5.1.1 > Whitelist > Cordova Whitelist > Network Request. For example: http://mywebsite.com
By default, only request to file”// URLs are allowed, but Cordova applications by default include access to all website. It is recommended that you provide your whitelist before publishing your app.
Content Security Policy:
Content Security Policy controls, which network requests such as images, AJAX requests (XHR) etc. are allowed to be made via WebView directly. This is specified through meta tags in your html file. It is recommended that you use CSP <meta> tag on all of your pages. Android KitKat onwards supports CSP, but Crosswalk web view supports CSP on all android versions.
For example include this in your index.html file.
<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: cdvfile: https://ssl.gstatic.com; style-src 'self''unsafe-inline'; media-src *">
For Microsoft Windows* platforms also, W3C Widget Access standards are used and the build settings for whitelisting are as follows.
Cordova CLI 4.1.2
Cordova CLI 4.1.2 is no longer supported by the Intel XDK. Please update your project to use CLI 5.1.1 or later.