cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From agri...@apache.org
Subject [1/2] docs commit: CB-8715 Update whitelist guide for Android 4.0.0
Date Wed, 25 Mar 2015 13:40:26 GMT
Repository: cordova-docs
Updated Branches:
  refs/heads/master ac5530599 -> 074944bba


CB-8715 Update whitelist guide for Android 4.0.0


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/53a189b5
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/53a189b5
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/53a189b5

Branch: refs/heads/master
Commit: 53a189b518be2f6a4f684e1b02b73e7d1a0cd864
Parents: ac55305
Author: Jason Chase <jasonpchase@gmail.com>
Authored: Tue Mar 24 23:04:59 2015 -0400
Committer: Andrew Grieve <agrieve@chromium.org>
Committed: Wed Mar 25 09:40:19 2015 -0400

----------------------------------------------------------------------
 docs/en/edge/guide/appdev/whitelist/index.md | 135 ++++------------------
 1 file changed, 21 insertions(+), 114 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/53a189b5/docs/en/edge/guide/appdev/whitelist/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/appdev/whitelist/index.md b/docs/en/edge/guide/appdev/whitelist/index.md
index 155c5b7..79698c9 100644
--- a/docs/en/edge/guide/appdev/whitelist/index.md
+++ b/docs/en/edge/guide/appdev/whitelist/index.md
@@ -20,13 +20,21 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 # Whitelist Guide
 
 Domain whitelisting is a security model that controls access to
-external domains over which your application has no control.  Cordova's
-default security policy allows access to any site. Before moving your
-application to production, you should formulate a whitelist and allow
-access to specific network domains and subdomains.
-
-Cordova adheres to the [W3C Widget Access][1] specification, which
-relies on the `<access>` element within the app's `config.xml` file to
+external domains over which your application has no control. Cordova
+provides a configurable security policy to define which external sites may be
+accessed.  By default, new apps are configured to allow access to any site.
+Before moving your application to production, you should formulate a whitelist
+and allow access to specific network domains and subdomains.
+
+For Android and iOS (as of their 4.0 releases), Cordova's security policy is extensible via
a plugin
+interface.  Your app should use the [cordova-plugin-whitelist][wlp], as it provides
+better security and configurability than earlier versions of Cordova.  While
+it is possible to implement your own whitelist plugin, it is not recommended
+unless your app has very specific security policy needs.  See the
+[cordova-plugin-whitelist][wlp] for details on usage and configuration.
+
+For other platforms, Cordova adheres to the [W3C Widget Access][1] specification,
+which relies on the `<access>` element within the app's `config.xml` file to
 enable network access to specific domains. For projects that rely on
 the CLI workflow described in The Command-Line Interface, this file is
 located in the project's top-level directory. Otherwise for
@@ -34,7 +42,7 @@ platform-specific development paths, locations are listed in the
 sections below. (See the various Platform Guides for more information
 on each platform.)
 
-The following examples demonstrate whitelist syntax:
+The following examples demonstrate `<access>` whitelist syntax:
 
 * Access to [google.com][2]:
 
@@ -78,89 +86,13 @@ Platform-specific whitelisting rules are found in
 
 ## Android Whitelisting
 
-Platform-specific whitelisting rules are found in
-`res/xml/config.xml`.
-
-__NOTE__: On Android 2.3 and before, domain whitelisting only works
-for `href` hyperlinks, not referenced resources such as images and
-scripts. Take steps to avoid scripts from being injected into the
-application.
-
-__NOTE__: In order to prevent external URLs such as `mailto:` from being opened
-in the Cordova webview as of Cordova 3.6.0, specifying `origin="*"` will
-implicity add rules for http and https protocols. If you require access to
-additional custom protocols, then you should also add them explicity to the
-whitelist. Also see "External Application Whitelist" below for more information
-on launching external applications by URL.
-
-__NOTE__: Some network requests do not go through the Cordova Whitelist.
-This includes &lt;video&gt; and &lt;audio&gt; resouces, WebSocket connections
(on
-Android 4.4+), and possibly other non-http requests. On Android 4.4+,
-you can include a [CSP](https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy)
-header in your HTML documents to restrict access to those resources.
-On older versions of Android, it may not be possible to restrict them.
-
-### External Application Whitelist
-
-Cordova 3.6.0 introduces a second whitelist, for restricting which URLs
-are allowed to launch external applications. In previous versions of
-Cordova, all non-http URLs, such as `mailto:`, `geo:`, `sms:` and `intent`,
-were implicitly allowed to be the target of an &lt;a&gt; tag. Because of the
-potential for an application to leak information, if an XSS vulnerability
-allows an attacker to construct arbitrary links, these URLs must be
-whitelisted as well, starting in Cordova 3.6.0.
-
-To allow a URL pattern to launch an external application, use an &lt;access>
-tag in your `config.xml` file, with the `launch-external` attribute set.
-
-Examples:
-
-* To allow links to send SMS messages:
-
-        <access origin="sms:*" launch-external="yes" />
-
-* To allow links to open Maps:
-
-        <access origin="geo:*" launch-external="yes" />
-
-* To allow links to example.com to open in an external browser:
-
-        <access origin="http://example.com/*" launch-external="yes" />
-
-* To allow all non-whitelisted websites to open in an external browser:
-(This is the same as the previous behaviour for non-whitelisted URLs)
-
-        <access origin="http://*" launch-external="yes" />
-        <access origin="https://*" launch-external="yes" />
-
-* To allow access to all URLs, reverting to the Cordova 3.5.0 policy (not recommended):
-
-        <access origin="*" launch-external="yes" />
-
-When navigating to a URL from within your application, the interal whitelist
-is tested first, and if the URL is not whitelisted there, then the external
-whitelist is tested. This means that any `http:` or `https:` URLs which match
-both whitelists will be opened inside of the Cordova application, rather than
-launching the external browser.
+As above, see [cordova-plugin-whitelist][wlp] for details.  For cordova-android
+prior to 4.0.0, see older versions of this documentation.
 
 ## iOS Whitelisting
 
-The platform's whitelisting rules are found in the named application
-directory's `config.xml` file.
-
-Origins specified without a protocol, such as `www.apache.org` rather
-than `http://www.apache.org`, default to all of the `http`, `https`,
-`ftp`, and `ftps` schemes.
-
-Wildcards on the iOS platform are more flexible than in the [W3C
-Widget Access][1] specification.  For example, the following accesses
-all subdomains and top-level domains such as `.com` and `.net`:
-
-        <access origin="*.google.*" />
-
-Unlike the Android platform noted above, navigating to non-whitelisted
-domains via `href` hyperlink on iOS prevents the page from opening at
-all.
+As above, see [cordova-plugin-whitelist][wlp] for details.  For cordova-ios
+prior to 4.0.0, see older versions of this documentation.
 
 ## BlackBerry 10 Whitelisting
 
@@ -215,32 +147,6 @@ The `XMLHttpRequest` object needs to be instantiated with two parameters
 
 This solution is transparent so there is no difference for other platforms.
 
-## iOS Changes in 3.1.0
-
-Prior to version 3.1.0, Cordova-iOS included some non-standard
-extensions to the domain whilelisting scheme supported by other
-Cordova platforms. As of 3.1.0, the iOS whitelist now conforms to the
-resource whitelist syntax described at the top of this document. If
-you upgrade from pre-3.1.0, and you were using these extensions, you
-may have to change the `config.xml` file in order to continue
-whitelisting the same set of resources as before.
-
-Specifically, these patterns need to be updated:
-
-* "`apache.org`" (no protocol): This would previously match `http`,
-  `https`, `ftp`, and `ftps` protocols. Change to "`*://apache.org/*`"
-  to include all protocols, or include a line for each protocol you
-  need to support.
-
-* "`http://apache.*`" (wildcard at end of domain): This would
-  previously match all top-level-domains, including all possible
-  two-letter TLDs (but not useful domains like .co.uk). Include a line
-  for each TLD which you actually control, and need to whitelist.
-
-* "`h*t*://ap*he.o*g`" (wildcards for random missing letters): These
-  are no longer supported; change to include a line for each domain
-  and protocol that you actually need to whitelist.
-
 ## Windows Phone Whitelisting
 
 The whitelisting rules for Windows Phone 8 are found in the
@@ -254,6 +160,7 @@ platform.
 (For more information on support, see Tizen's documentation on the
 [access element][9].)
 
+[wlp]: https://github.com/apache/cordova-plugin-whitelist
 [1]: http://www.w3.org/TR/widgets-access/
 [2]: http://google.com
 [3]: https://google.com


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org


Mime
View raw message