Skip to content

Latest commit

 

History

History
317 lines (215 loc) · 19.5 KB

whitelist-matrix.md

File metadata and controls

317 lines (215 loc) · 19.5 KB

Whitelist Worksheet (Matrix)

Date: 2015-10-26
Last Update: 2015-12-12

The Whitelist System -> Whitelist Worksheet (Matrix)

By this point you should know there are three (3) platforms and four (4) security systems.

If you have never heard of a decision table, today you'll learn of the value of them. This easy enough. Start at the top (1.) and continue till to the bottom (9.). If you drop out anywhere along the way. You are done.

However, the tables in 1., 7., 9., and 10. are short cuts (or aides) to help you get to the right place. You will notice, the tables do not loop back or interconnect. This was intentionally done to help you work in a linear fashion.

This is, in fact, a simple expert system – with you as the feedback. Meaning, if you discover an error, let me know. I or someone else will adjust this set of tables.

  1. Is my version of Cordova/Phonegap included?
  2. Which whitelist guide should I use?
  3. Which plugin, whitelist or legacy-whitelist?
    The Cordova whitelist
  4. Do I have to apply allow-navigation?
  5. Do I have to apply allow-intent?
  6. Do I have to apply access origin?
  7. How does this affect inappbrowser?
  8. How do I apply those config.xml elements?
    W3's CSP
  9. CSP (Content Security Policy)?
    Apple's ATS
  10. ATS?

1. Is my version of Cordova/Phonegap included

cordova -v

It is recommend that you move to Cordova Tools V4.x as a minimum. Older versions are difficult to support and many plugins do not work correctly.

Your Version of
Cordova/Phonegap Tools ¢		 whitelist
support		 notes
2.x Not support deprecated
3.x Available white-list, plugin
4.x Required white-list, plugin
5.x¥ Required white-list, plugin, CSP
Any above AND iOS9£ Required Apple's ATS§
  • ¢ = Cordova and Phonegap versions do NOT align, but are close. This version is not the *pinned* version either. If you do not know the difference, learn — official release policy.
  • ¥ = This include cli-5.1.0 and cli.5.2.0
  • £ = As of 2015-11-04, iOS9 is officially supported by Cordova (SEE) ; Phonegap Build is still waiting
  • § = ATS requires – if you are using Apple's SSL, then the server you connect to must run TLSv1.2
  • ** = Beginning May 9, 2016, Google Play will block publishing of any new apps or updates that use pre-4.1.1 versions of Apache Cordova.

2. Which guide

For all intensive purpose, there are three (3) whitelist guides. They all have mistakes, lack current information, and suffer from neglect. However, there are important pointers for each platform. So, if you are working on Windows, Blackberry, Tizen, or one of the other platform, do read the appropriate guide.

However, the best and most accurate information seems to come from from the documentation for the cordova-plugin-whitelist plugin. It is at the bottom of this list.

  1. Cordova Whitelist Guide - Cordova CLI and SDK
  2. Phonegap Whitelist Guide - Phonegap CLI and SDK
  3. Phonegap Build Whitelist Guide - Phonegap Build only
  4. cordova-plugin-whitelist - npm

3. Which plugin, whitelist or legacy-whitelist

If you are not aware of it, we have move to an NPM system

This plugin implements a whitelist policy for navigating the application webview on Cordova Tools 4.0 (or higher).

If you have not implemented the whitelist system yet, then you want to start here. This plugin has more parameters and has better granularity that the legacy plugin.

This plugin implements the Cordova Tools 3.6 Whitelist policy for Cordova Tools 4.0.

If you implemented the whitelist system for Android before 15 Apr 2015, then you can still use the legacy system. As of that date, the new whitelist plugin is available and it runs with a different set of rules. While the cordova-plugin-legacy-whitelist is currently supported, you are *strongly* encouraged to move to the whitelist plugin.

##The Cordova whitelist##

The Cordova whitelist has three (3) parts; allow-navigation, allow-intent, and access origin.

4. allow-navigation

Controls which URLs the *WebView* itself can be navigated to. Applies to top-level navigations only.

By default, navigations only to file:// URLs are allowed. To allow other URLs, you must add <allow-navigation> tags to your config.xml.

Quirks: On Android, it also applies to iframes for non-http(s) schemes. This includes, but is not limited to: data:.

DANGEROUS-SETTING: <allow-navigation href="*" />

5. allow-intent

Controls which URLs the app is allowed to ask the *system* to open. By default, no external URLs are allowed.

This whitelist does not apply to plugins, only hyperlinks and calls to window.open().

Quirks: On Android, this equates to sending an intent of type BROWSEABLE. This includes, but is not limited to: tel:, sms:, mailto:, geo:, market:, itms:, itms-apps:.

DANGEROUS-SETTING: <allow-intent href="*" />

6. access origin

Controls which *network* requests (images, XHRs, etc) are allowed to be made (via cordova native hooks).

Without any <access> tags, only requests to file:// URLs are allowed. However, the default Cordova application includes <access origin="*"> by default.

Quirk: Even without this, Android also allows requests to https://ssl.gstatic.com/accessibility/javascript/android/ by default, since this is required for TalkBack to function properly.

DANGEROUS-SETTING: <access origin="*" />

7. inappbrowser

This is one point where the documentation conflicts with it's self. If you do a search for 'whitelist' on the documentation you will see conflicting lines. The inconsistencey in the writing style points to multiple authors, poor design, and neglect. At a minimum, expect a rewrite of the documentation.

In the middle of the 3rd paragraph is

The InAppBrowser is not subject to the whitelist, nor is opening links in the system browser.

In cordova.InAppBrowser.open(), under 'target' is

_self: Opens in the Cordova WebView, if the URL is in the white list, otherwise it opens in the InAppBrowser.

8. How do I apply those config.xml elements

FOREWARNED. The documentation suggests that the CSP be used instead of access origin. I disagree. CSP is confusing and unclear. However, access origin is weak and ripe for more security warnings. There is inconsistency in both methods. As a developer, you should make an objective decision on this. FOREWARNED.

Which XML element Controls Quirks
allow-navigation WebView¿ Android applies this to iframes (non-http(s))
allow-intent URI or URL request to the system window.open()¿ 1. Android equivalent to BROWSEABLE
2. does not apply to plugins
access origin Controls network requests (images, XHRs, etc) via Cordova Hooks Android makes allowance for Talkback µ
the default Cordova application includes <access origin="*">

  • ¿ = It unclear from the documentation how this interacts with inappbrowser.

  • µ = The documentation alludes that Android has this built-in, or hard-coded.

  • See access by default

Cordova whitelist Examples

W3's CSP

9. CSP (Content Security Policy)

Opinion

CSP has to be the most heinous part of the whitelist system. It has sixteen (16) directives and they have overlapping logic. Note, some developer have implemented this in a morning. You are forewarned.

The CSP is configured per web page using HTTP headers (or HTML meta equivalent). Whenever the browser loads an HTML document, the response headers of the HTTP (or HTML meta equivalent) request that the delivered document use the content security policy for all content that originates from this HTML document.

The CSP is configured via a single header (Content-Security-Policy or X-Content-Security-Policy). The value of this header is a string that effectively sets directives separated by a semicolon. The directives define a list of sources that are safe to communicate with. There is a directive available for each of the resource types such as images, xhr, styles, scripts.

Several websites were culled for information to give this specificaiton clarity.

Directives

Each of the directives listed can define one or more sources that are safe to consume. You can combine sources, which can include 'CSP Keywords', 'CSP Data(words)', and 'Host (regular) Expressions'. Note, per the specification, not all directives apply. See Whitelist CSP Examples -> Access By Default for details on this.

CSP Directives W3 Section Governs
base-uri 7.1 restricts the URLs that can be used to specify the document base URL
child-src 7.2 the nested browsing contexts and the execution of Workers
connect-src 7.3 network activities such as XMLHttpRequest::send
default-src 7.4 sets a default source list for a number of directives
font-src 7.5 fonts loading
form-action 7.6 form submissions
frame-ancestors 7.7 Not Available embedding of iframes, objects, applets etc
frame-src 7.8 is deprecated
img-src 7.9 loading of images
media-src 7.10 video and audio sources
plugin-types 1.12 (these are MIME-type plugins, not Cordova)
report-uri 7.13 Not Available a URL to which the user agent sends reports about policy violation
sandbox 7.14 Not Available specifies an HTML sandbox policy that the user agent applies to the protected resource
object-src 7.11 objects (flash, audio, etc.)
script-src 7.15 scripts execution
style-src 7.16 CSS sources

CSP Keywords

  • *The single quotes are required.*
CSP Keywords Meaning
'none' Refers to the empty set; that is, no URLs match.
'self' Refers to the origin from which the protected document is being served, including the same URL scheme and port number.
'unsafe-inline' Allows the use of inline resources, such as inline <script> elements, javascript: URLs, inline event handlers, and inline <style> elements.
This is what makes this ridiculous for mobile Apps
Early event handlers -- Working with Inline Event Handlers
'unsafe-eval' Allows the use of eval() and similar methods for creating code from strings.
What does "similar methods" mean? No one says.

CSP Data

CSP Data(words) Meaning
data: Allows data: URIs to be used as a content source. This is insecure; an attacker can also inject arbitrary data: URIs. Use this sparingly and definitely not for scripts.
mediastream: Allows mediastream: URIs to be used as a content source.
blob: Allows blob: URIs to be used as a content source.
This is another ridiculous thing for mobile Apps
filesystem: Allows filesystem: URIs to be used as a content source.
This is another ridiculous thing for mobile Apps
gap: This dataword only applies to Cordova/Phonegap. At this time, it is required only on iOS (when using UIWebView) and is needed for JS->native communication. It is badly documented

CSP Host (regular) Expressions

name usage Example
need add examples -

There are four (4) documents worth reading on this subject.

Apple's ATS##

10. ATS

As part of Apples move to iOS 9, Apple is mandating the use of Apple Transport System (ATS). This basically means that all web communications should use https: rather than http:. At the moment, it is easy to create exceptions to the ATS policy. Apple is likely to tighten up these exceptions over time, though it is difficult to see how they can make it 100% mandatory. The issue being that some server sites simply will not work over https: and may never convert.

Note, there are known issues with some sites using https: and Apple's ATS. It is not as simple as adding an 's' to http:. Apple mandates TLS1.2 (or better) when using iOS9 and https:. On some sites, TLS1.2 will not work, though they will work with https:. Google Ads and Amazons Web Services are known to have problems. Luckily, it is easy to create an exception.

Turns off all security. Google and Ionic provide these answers.
CAUTION: Your app maybe rejected, unless you have a good reason for using this. SEE

<key>NSAppTransportSecurity</key>
    <dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    </dict>

Solution for amazonaws.com

<key>NSAppTransportSecurity</key>
<dict>
      <key>NSExceptionDomains</key>
      <dict>
            <key>amazonaws.com</key>
            <dict>
                  <key>NSThirdPartyExceptionMinimumTLSVersion</key>
                  <string>TLSv1.0</string>
                  <key>NSThirdPartyExceptionRequiresForwardSecrecy</key>
                  <false/>
                  <key>NSIncludesSubdomains</key>
                  <true/>
            </dict>
            <key>amazonaws.com.cn</key>
            <dict>
                  <key>NSThirdPartyExceptionMinimumTLSVersion</key>
                  <string>TLSv1.0</string>
                  <key>NSThirdPartyExceptionRequiresForwardSecrecy</key>
                  <false/>
                  <key>NSIncludesSubdomains</key>
                  <true/>
            </dict>
      </dict>
</dict>

11. Still not working

Unapplied Notes

When I say the information about the whitelist system was buried, I mean these three (3) blog posts

Plugins Release and Moving plugins to npm: April 21, 2015 SEE: New Whitelist Plugins https://cordova.apache.org/announcements/2015/04/21/plugins-release-and-move-to-npm.html

Apache Cordova Android 4.0.0: 15 Apr 2015 SEE: Major Changes http://cordova.apache.org/announcements/2015/04/15/cordova-android-4.0.0.html

  • CSP is now supported
  • Network requests are blocked by default without the plugin
  • latest default app created by cordova-cli will include this plugin by default

SEE: org.apache.cordova.inappbrowser@0.5.4

SEE: Major Changes http://cordova.apache.org/announcements/2015/04/15/cordova-android-4.0.0.html

What's New in iOS https://developer.apple.com/library/prerelease/ios/releasenotes/General/WhatsNewIniOS/Articles/iOS9.html

Differences between test and production release for Android - A network puzzler https://groups.google.com/d/msg/phonegap/ALL8SsuFCiQ/4m_WN6NcAwAJ

The problem was caused by an intermediate certificate not being installed correctly on a CDN server. The main wildcard certificate installed on the CDN server was correct and that (...) The fact that the CDN server said everything was OK and IOS was very happy only lulled us into a false sense of security. (Another developer remarks) In short: certs are painful and capable of causing concussions and large dents in desks.