Skip to content

Latest commit

 

History

History
128 lines (89 loc) · 9.99 KB

the-whitelist-system.md

File metadata and controls

128 lines (89 loc) · 9.99 KB
Raw

HOW TO apply the Cordova/Phonegap the whitelist system

Date: 2015-10-28
Last Update: 2015-12-12
Cosmetic Update: 2018-09-18

If you have any questions, I am usually in the Adobe Forum for Phonegap Build

This blog post is one page. It has three (3) parts.

  1. The Breakdown. - the four big parts of the whitelist system
  2. Turning It All Off. - turn off security, get the job done.
  3. Lucy, Esplain Youself. - 5+ pages with references, examples, and tips

As such, I want to thank Rob Willett for his invaluable assitance and advice. If you find errors, they are mine. If you have praise, send some luv to Rob.

Note: From here forward I will use Cordova to mean Cordova CLI, Cordova SDK, Phonegap CLI, Phonegap SDK, and Phonegap Build. If there is a difference, I will try to make it abundantly clear. If you did not know there is a difference, read this.

The breakdown

For the Cordova whitelist system, there four (4) unrelated systems (plus one (1) legacy system) that work together, and overlap in places.

  1. legacy-whitelist plugin (avoid) was the previous whitelist system. It is provided for backwards compatibilty only.
  2. cordova-plugin-whitelist (Cordova's) is the new whitelist system. It is required as of Cordova Tools 5.0.0 (April 21, 2015). It has three (3) parts (<access (..) />, <allow-intent (...) />, <allow-navigate (...) />). This plugin does NOT apply to iOS.
  3. W3's <access (..) /> (Widget Access Request Policy) is usually lumped in with Cordova's whitelist plugin documentation, but it is seperate and overlaps with the other systems. However, the latest Cordova cordova-plugin-whitelist suggests that it is mostly historical for webviews which do not support CSP.
  4. W3's CSP (Content Security Policy Level 2) is a whitelist system that is implemented webpage by webpage. It is required as of Cordova Tools 5.0.0 (April 21, 2015). It has sixteen (16) parts.
  5. Apple's ATS (App Transport Security) is a whitelist system exclusive to iOS. It required as of iOS9. It is implemented in the Info.plist. The blog indicates parts of the whitelist system are now cross-compile to ATS elements. See Apache Cordova iOS 3.9.2 02 Nov 2015 and Cordova iOS 4.0.0 08 Dec 2015.

To walk throught the various different systems would be tedious. As such, there are at least five (5) documents that directly support this blog. However, let's cut to the chase.

As such,the code that follows turns off ALL whitelist systems. This means your app is not secured against attacks. It is up to you to secure your App. Below that, you can turn on and apply ALL the whitelist system, complete with detailed explanations, directions, examples, and tips.

Turning It All Off

before 4.0.0

  • Recommended: For development only.
  • The easiest way to turn it all off is to develop with a version before 4.0.0.
  • For Phonegap Build ONLY use: <preference name="phonegap-version" value="3.7.0" />
  • For Cordova/Phonegap CLI/SDK, see the outdated, but useful: Cordova/PhoneGap Version Confusion
  • After following these directions, you should now have full access and be completely insecure.

after 4.0.0

  • Recommended: For production applications.
  • Start by adding the whitelist plugin. required all platforms, except iOS
  • For Phonegap Build Only <gap:plugin name=cordova-plugin-whitelist source=npm>
  • For Cordova/Phonegap CLI cordova plugin add cordova-plugin-whitelist
  • For Cordova/Phonegap SDK see the Cordova documentation -> The config.xml File -> The feature Element
  • For iOS only, the whitelist plugin is not used. However, the <access (...)> tag is used for iOS9.
  • Then to disable the whitelist system, add to config.xml
  • CAUTION: Your app maybe rejected, unless you have a good reason for using this.
    <allow-navigation href="*" />
    <allow-intent href="*" />
    <access origin="*" /> <!-- Required for iOS9 -->
  • To disable the CSP part of the whitelist system, add this to every webpages that needs internet (or network access), inline code (Javascript or style), or eval(). Wikipedia Details on CSP
  • Prior to today 2015-12-01, style-src and script-src, did not have the * (star). This was a mistake. It should have it.
  • CAUTION: Your app maybe rejected, unless you have a good reason for using this.
    <meta http-equiv="Content-Security-Policy" 
             content="default-src *; 
                      style-src * 'self' 'unsafe-inline' 'unsafe-eval'; 
                      script-src * 'self' 'unsafe-inline' 'unsafe-eval';">

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

You should now have full access, and be completely insecure.

Lucy, Esplain Youself

No security system is straight forward. Security systems tend to be compromises of caution and the real world. Jim Dennis, reminds me that, "Security is a matter of policy. As an administrator (or developer), it is your job to enfore policy, not define security."

The Cordova whitelist system is about how best to apply your real-world policies over a hybrid application. As such, sacrifices and compromises are every where. The link below is a document that walks through much of the Cordova whitelist system.

new-whitelist-system.md – NOT FINISHED, in rough state. About 75% done.

Deciding What You Need

Often I think someone at Microsoft designed this, but then I realize that the entire thing was the product of multiple committes, working indepently, with no real design criteria – then, this all makes sense.

As there are three (3) seperate systems and they do not talk about each other, it is difficult to decide how they relate to each other. The matrix on the next page is a series of questions and decision tables that help make you make choices. This matrix is infact an expert system. It will not write your code, but it will tell you what you need to write, and what you do not need to write.

whitelist-matrix.md – NOT FINISHED, in rough state. About 85% done.

Examples

Examples for each part. If you have any you'd like to lend, please email me or create an issue.

whitelist-examples.md – NOT FINISHED, in raw state. About 10% done.

<access Examples> – NOT FINISHED, in rough state. About 90% done.

whitelist-csp-examples.md – NOT FINISHED, in rough state. About 60% done.

whitelist-ats-examples.md – ALMOST FINISHED, in good state. About 90% done. Need more examples, some comments.

*If you have any questions, I am usually in the Google Group for Phonegap

Annoyances in creating this document

Before any of this was implemented, all the members of the various teams shared the same fever dream. As a result, today we have the various systems to deal with.

  • It is NOT helpful that the Cordova Website continues to change and move pages.
  • It is NOT helpful that the Cordova team is weak in communications. (Please remember they all volunteer for this, and help is needed.)
  • It is NOT helpful that Apple's removes important documents. Like this one that is widely referenced. Guess what Apple, there is this thing called archive.org
  • It is NOT helpful that both Google and Apple proclaim that the world must use HTTPS to talk to them. Thank you Homeland f#ck US
  • It is NOT helpful that the press contrives issue between Google and Apple.