This is an automated email from the ASF dual-hosted git repository.
erisu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 6bd4ffa0f3 doc(CB-12770): revise security documentation (#1407)
6bd4ffa0f3 is described below
commit 6bd4ffa0f3ebf61f84744e7566e3902391ad689b
Author: エリス <er...@users.noreply.github.com>
AuthorDate: Tue Mar 18 11:09:04 2025 +0900
doc(CB-12770): revise security documentation (#1407)
---
www/docs/en/dev/guide/appdev/allowlist/index.md | 58 ++++++++++-
www/docs/en/dev/guide/appdev/security/index.md | 132 ++++++++++++++++++------
2 files changed, 153 insertions(+), 37 deletions(-)
diff --git a/www/docs/en/dev/guide/appdev/allowlist/index.md
b/www/docs/en/dev/guide/appdev/allowlist/index.md
index d3145d0108..885e8c33f1 100644
--- a/www/docs/en/dev/guide/appdev/allowlist/index.md
+++ b/www/docs/en/dev/guide/appdev/allowlist/index.md
@@ -85,7 +85,7 @@ By default navigations are only allowed to `file://` URLs. To
allow others URLs,
to the host, or as a suffix to the path -->
<allow-navigation href="*://*.example.com/*" />
-<!--
+<!--
A wildcard can be used to allow the entire network, over HTTP and HTTPS.
This is *NOT RECOMMENDED*
-->
@@ -141,10 +141,54 @@ Note: `allow-navigation` takes precedence over
`allow-intent`. Allowing navigati
## Content Security Policy (CSP)
-Controls which network requests (images, XHRs, etc) are allowed to be made
(via webview directly).
+The [**Content Security Policy
(CSP)**](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) `<meta>` tag is
a very powerful mechanism that allows you to control trusted sources of
content. You can restrict various content types and domains from which content
can be loaded from. Unsafe and risky HTML and JavaScript can also be disabled
to further increase the security of your app.
+
+The CSP `<meta>` tag should be placed in your app's index.html file.
On Android and iOS, the network request allow list (see above) is not able to
filter all types of requests (e.g. `<video>` & WebSockets are not blocked). So,
in addition to the allow list, you should use a [Content Security
Policy](http://content-security-policy.com/) `<meta>` tag on all of your pages.
+> **Note**: If your app has multiple HTML files and navigates between them
using the browser's navigation features, you should include the CSP in each
file. If your app is a single-page application, you only need to include the
CSP on `index.html`.
+
+### Cordova's Default Template Content Security Policy
+
+The CSP that Cordova's default template uses looks like this (indented for
clarity):
+
+```html
+<meta http-equiv="Content-Security-Policy"
+ content="default-src 'self' data: https://ssl.gstatic.com 'unsafe-eval';
+ style-src 'self' 'unsafe-inline';
+ media-src *;
+ img-src 'self' data: content:;">
+```
+
+The above snippet enforces the following:
+
+**Default Source (`default-src`):**
+
+As a fallback, all other network requests are restricted to:
+
+* The same origin as the app itself (`'self'`).
+* Resources loaded via `data:` URIs.
+* Resources from the specified external domain `https://ssl.gstatic.com`.
+* JavaScript methods such as `eval()` (and similar) are permitted with
`'unsafe-eval'`.
+
+**Style Source (`style-src`):**
+
+* Styles can only be loaded from the same origin (`'self'`).
+* Inline styles (`'unsafe-inline'`) are also allowed, meaning styles can be
directly applied using the `style` attribute on elements or within `<style>`
tags.
+
+**Media Source (`media-src`):**
+
+* Media can be loaded from any source.
+
+**Image Source (`img-src`):**
+
+* Images can only be loaded from the same origin (`'self'`).
+* Allows loading images from `data:` URIs.
+* Allows loading images from `content:` URIs, typically used within the
Android ecosystem.
+
+### Example Content Security Policy Declarations
+
Here are some example CSP declarations for your `.html` pages:
```html
@@ -159,7 +203,7 @@ Here are some example CSP declarations for your `.html`
pages:
<!-- Allow everything but only from the same origin and foo.com -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self'
foo.com">
-<!-- This policy allows everything (eg CSS, AJAX, object, frame, media, etc)
except that
+<!-- This policy allows everything (eg CSS, AJAX, object, frame, media, etc)
except that
* CSS only from the same origin and inline styles,
* scripts only from the same origin and inline styles, and eval()
-->
@@ -172,6 +216,14 @@ Here are some example CSP declarations for your `.html`
pages:
<meta http-equiv="Content-Security-Policy" content="default-src 'self';
frame-src 'self' https://cordova.apache.org";>
```
+You should fully understand the CSP tag and the various directives that can be
specified. More documentation is available at [Content Security
Policy](https://web.dev/articles/csp) (via Google Developers) and Mozilla's
[Content Security Policy
(CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) article.
+
+> **Tip**: If you're using web sockets, include `ws:` (`wss:` if using SSL) in
the `connect-src` directive.
+
+### Debugging Content Security Policy
+
+When adding a CSP to your app, it's likely you'll encounter some issues.
Fortunately, both Google Chrome's Developer Tools and Safari's Web Inspector
make it very clear when a CSP violation occurs. Watch the console for any
violation messages, which are typically quite detailed, specifying exactly
which resource was blocked and why. Address each violation as they appear to
ensure your CSP is properly configured.
+
## Other Notes
[Application Transport Security
(ATS)](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33)
is new in iOS 9 (Xcode 7). This new feature acts as an allow list for your
app. Cordova CLI will automatically convert the `<access>` and
`<allow-navigation>` tags to the appropriate ATS directives.
diff --git a/www/docs/en/dev/guide/appdev/security/index.md
b/www/docs/en/dev/guide/appdev/security/index.md
index 29671e9770..1ffa5571bc 100644
--- a/www/docs/en/dev/guide/appdev/security/index.md
+++ b/www/docs/en/dev/guide/appdev/security/index.md
@@ -28,27 +28,78 @@ The following guide includes some security best practices
that you should consid
## This guide discusses the following topics:
+* General Tips
+* Plugins and Security
* Allow List
-* Iframes and the Callback Id Mechanism
+* Content Security Policy
* Certificate Pinning
-* Self-signed Certificates
+* Using TLS/SSL
+* Avoid Self-signed Certificates
+* Wrapping external sites and hot code push
* Encrypted storage
-* General Tips
* Recommended Articles and Other Resources
+## General Tips
+
+### Use InAppBrowser for outside links
+
+Use the
[InAppBrowser](https://www.npmjs.com/package/cordova-plugin-inappbrowser) when
opening links to any outside website. This is much safer than allow listing a
domain name and including the content directly in your application because the
InAppBrowser will use the native browser's security features and will not give
the website access to your Cordova environment. Even if you trust the third
party website and include it directly in your application, that third party
website could lin [...]
+
+### Validate all user input
+
+Always validate any and all input that your application accepts. This includes
usernames, passwords, dates, uploaded media, etc. Because an attacker could
manipulate your HTML and JS assets (either by decompiling your application or
using debugging tools like `chrome://inspect`), this validation should also be
performed on your server, especially before handing the data off to any backend
service.
+
+> **Tip**: Other sources where data should be validated: user documents,
contacts, push notifications
+
+### Do not store sensitive data
+
+If usernames, password, geolocation information, and other sensitive data is
stored, then it could potentially be retrieved later by an unauthorized user or
application.
+
+### Don't use `eval()`
+
+The JavaScript function `eval()` has a long history of being abused. Using it
incorrectly can open your code up for injection attacks, debugging
difficulties, and slower code execution.
+
+### Do not assume that your source code is secure
+
+Since a Cordova application is built from HTML and JavaScript assets that get
packaged in a native container, you should not consider your code to be secure.
It is possible for an iOS or Android application to be unpacked and unzipped to
reveal its web assets such as HTML and JS.
+
+A sampling of what you should not include in your code:
+
+* Authentication information (usernames, passwords, keys, etc.)
+* Encryption keys
+* Trade secrets
+
+### Do not assume storage containers are secure
+
+Even if a device itself is encrypted, if someone has access to the device and
can unlock it, you should not assume that data stored in various formats and
containers is safe. Even SQLite databases are easily human readable once access
is gained.
+
+As long as you're storing non-sensitive information, this isn't a big deal.
But if you were storing passwords, keys, and other sensitive information, the
data could be easily extracted, and depending on what was stored, could be used
against your app and remote servers.
+
+For example, on iOS, if you store data in `localStorage`, the data itself is
easily readable to anyone who has access to the device. This is because
`localStorage` is backed by an unencrypted SQLite database. The underlying
storage of the device may in fact be encrypted (and so it would be inaccessible
while the device is locked), but once the device decrypts the file, the
contents themselves are mostly in the clear. As such, the contents of
`localStorage` can be easily read and even changed.
+
+## Plugins and Security
+
+Due to the way the native portion of Cordova communicates with your web code,
it is possible for any code executing within the main webview context to
communicate with any installed plugins. This means that you should _never_
permit untrusted content within the primary webview. This can include
third-party advertisements, sites within an `iframe`, and even content injected
via `innerHTML`.
+
+If you must inject content into the primary webview, be certain that it has
been properly sanitized so that no JavaScript can be executed. _Do not try to
sanitize content on your own; use a vetted third-party library instead!_
+
+> **Tip**: If you need to include advertising, use any of the many third-party
plugins for Cordova. These are safer than executing arbitrary JavaScript from
advertisers.
+
## Allow List
By default the app's navigation is unrestricted. It's recommended to restrict
the navigation only to trusted domains. Learn more by reading the [Allow List
Guide](../allowlist/index.html)
-## Iframes and the Callback Id Mechanism
+## Content Security Policy (CSP)
-If content is served in an iframe from a allow listed domain, that domain will
have access to the native Cordova bridge. This means that if you allow a
third-party advertising network and serve those ads through an iframe, it is
possible that a malicious ad will be able to break out of the iframe and
perform malicious actions. Because of this, you should generally not use
iframes unless you control the server that hosts the iframe content. Also note
that there are third party plugins av [...]
+Cordova’s default template includes a basic Content Security Policy (CSP).
It’s recommended to review and customize this CSP to fit your app's specific
needs. For more information, refer to the [Allow List Guide - Content Security
Policy (CSP)](../allowlist/index.html#content-security-policy-csp).
## Certificate Pinning
-Cordova does not support true certificate pinning. The main barrier to this is
a lack of native APIs in Android for intercepting SSL connections to perform
the check of the server's certificate. (Although it is possible to do
certificate pinning on Android in Java using JSSE, the webview on Android is
written in C++, and server connections are handled for you by the webview, so
it is not possible to use Java and JSSE there.) Since Apache Cordova is meant
to offer consistent APIs across m [...]
+It is important to ensure that you trust any hosts with which there are
communications. Typically, one would do this using certificate pinning. The app
would double check any certificates and only communicate over channels where
the certificate check passed. This helps mitigate man-in-the-middle attacks.
+
+Unfortunately, Cordova does not support true certificate pinning. The main
barrier to this is a lack of native APIs in Android for intercepting SSL
connections to perform the check of the server's certificate. (Although it is
possible to do certificate pinning on Android in Java using JSSE, the webview
on Android is written in C++, and server connections are handled for you by the
webview, so it is not possible to use Java and JSSE there.) Since Apache
Cordova is meant to offer consisten [...]
-There are ways to approximate certificate pinning, such as checking the
server's public key (fingerprint) is the expected value when your application
starts or at other various times during your application's lifetime. There are
third-party plugins available for Cordova that can do that. However, this is
not the same as true certificate pinning which automatically verifies the
expected value on every connection to the server.
+There are ways to approximate certificate pinning, such as checking that the
server's public key (fingerprint) is the expected value when your application
starts or at other various times during your application's lifetime. There are
third-party plugins available for Cordova that can do that. However, this is
not the same as true certificate pinning which automatically verifies the
expected value on every connection to the server.
There are also plugins that can do true certificate pinning for some
platforms, assuming your app is able to do all of its network requests using
the plugin (i.e.: no traditional XHR/AJAX requests, etc).
@@ -56,51 +107,64 @@ There are also plugins that can do true certificate
pinning for some platforms,
If your app communicates to an external server, it should be communicating
using modern encryption standards. Use `https` protocol whenever possible.
-[Let's Encrypt](https://letsencrypt.org/) is a free, automated, and open
certificate authority provided by the nonprofit [Internet Security Research
Group](https://www.abetterinternet.org/). Let's Encrypt will offer free
standard certificates, which will be sufficient for most developers. Enterprise
organizations may still want to use a traditional certificate authority that
offers more advanced features such as [Organization
Validation](https://en.wikipedia.org/wiki/Public_key_certifica [...]
+[Let's Encrypt](https://letsencrypt.org/) is a free, automated, and open
certificate authority provided by the nonprofit [Internet Security Research
Group](https://www.abetterinternet.org/). Let's Encrypt will offer free
standard certificates, which will be sufficient for most developers. Enterprise
organizations may still want to use a traditional certificate authority that
offers more advanced features such as [Organization
validation](https://en.wikipedia.org/wiki/Public_key_certifica [...]
It is also important to keep up to date with security standards as they change
over time. What might be acceptable SSL/TLS configuration today may not be
acceptable years in the future. Using tools to test your certificate and
SSL/TLS configuration should be done regularly. [SSL
Labs](https://www.ssllabs.com/ssltest/) is a free online service provided by
Qualys, Inc to test your server's SSL/TLS configuration and encryption
strength, in addition to supported platforms.
-## Self-signed Certificates
+## Avoid Self-signed Certificates
-Using self-signed certificates on your server is not recommended. If you
desire SSL, then it is highly recommended that your server have a certificate
that has been properly signed by a well-known CA (certificate authority). The
inability to do true certificate pinning makes this important.
+Using self-signed certificates on your server is not recommended. If you
desire SSL, then it is highly recommended that your server have a certificate
that has been properly signed by a well-known CA (certificate authority). The
inability to do true certificate pinning makes this even more important.
-The reason is that accepting self-signed certificates bypasses the certificate
chain validation, which allows any server certificate to be considered valid by
the device. This opens up the communication to man-in-the-middle attacks. It
becomes very easy for a hacker to not only intercept and read all communication
between the device and the server, but also to modify the communication. The
device will never know this is happening because it doesn't verify that the
server's certificate is [...]
+The reason is that accepting self-signed certificates bypasses the certificate
chain validation, which allows any server certificate to be considered valid by
the device. This opens up the communication to man-in-the-middle attacks. It
becomes very easy for a hacker to not only intercept and read all communication
between the device and the server, but also to modify the communication. The
device will never know this is happening because it doesn't verify that the
server's certificate is [...]
-If the application is to be used only within a trusted network, such as an
internal corporate network. Using self-signed certificates may be acceptable,
however the public certificate should be pre-installed on the device(s) that
will be running the application. A trusted third-party certificate authority
will always be preferable.
+Because of the ease of doing a man-in-the-middle attack, accepting self-signed
certificates is only marginally better than just running `http` instead of
`https` on an untrusted network. While the traffic would be encrypted, it could
be encrypted with the key from a man-in-the-middle, so the man-in-the-middle
would have access everything, making the encryption useless except to passive
observers. Users trust SSL to be secure, and this would be deliberately making
it insecure, so the SSL [...]
-The principles described here are not specific to Apache Cordova, they apply
to all client-server communication.
+If the app will be used on a trusted network (i.e., you are entirely inside a
controlled enterprise), then self-signed certs are still not recommended. The
two recommendations in a trusted network are to just use http because the
network itself is trusted, or to get a certificate signed by a trusted CA (not
self-signed). Either the network is trusted or it is not.
-When running Cordova on Android, using `android:debuggable="true"` in the
application manifest will permit SSL errors such as certificate chain
validation errors on self-signed certs. So you can use self-signed certs in
this configuration, but this is not a configuration that should be used when
your application is in production. It is meant to be used only during
application development.
+> **Note**: The principles described here are not specific to Apache Cordova,
they apply to all client-server communication.
+> **Android Tip**: When running Cordova on Android, using
`android:debuggable="true"` in the application manifest will permit SSL errors
such as certificate chain validation errors on self-signed certs. So you can
use self-signed certs in this configuration, but this is not a configuration
that should be used when your application is in production. It is meant to be
used only during application development.
-## Encrypted storage
+## Wrapping external sites and hot code push
-(TBD)
+Cordova's implementation allows you to redirect to an external site instead of
using local content. This is **not** suggested for most apps, even though it
might avoid a rewrite of the app or can make code updates faster. You should
avoid this for any apps destined to any app store, but in general, it's risky
regardless, for many reasons:
-## General Tips
+* No local code to detect no route to host. Apple _requires_ apps to detect no
network connection (and other connectivity issues) and display a user-friendly
error message. If there's no local code to detect this, the app will generally
remain blank, and Apple will reject it.
+* No local code to verify the downloaded content. The content could be
incomplete or corrupted, especially if being downloaded over a poor network
connection. Incomplete or corrupt content is not going to render particularly
well, leaving your user frustrated.
+* No local code to detect and remove malicious intent. Local code has a chance
to sanitize content and verify that there are no spurious or unexpected
`script` tags or event handlers. Without local code, the app is at the server's
mercy.
+* No local code to check certificates. See **Certificate Pinning** above.
-### Do not use Android Gingerbread!
-* Set your min-target-sdk level higher than 10. API 10 is Gingerbread, and
Gingerbread is no longer supported by Google or device manufacturers, and is
therefore not recommend by the Cordova team.
-* Gingerbread has been shown to be insecure and one of the most targeted
mobile OSs
[https://www.mobilemag.com/2012/11/06/andriod-2-3-gingerbread-security/](https://bgr.com/2012/11/06/android-security-gingerbread-malware/).
-* The Allowlist on Android does not work with Gingerbread or lower. This means
an attacker can load malicious code in an iframe that would then have access to
all of the Cordova APIs and could use that access to steal personal data, send
SMS messages to premium-rate numbers, and perform other malicious acts.
+Hot code push solutions improve matters a bit, since they will download code
and store it locally on the device. This means that in the event of a network
failure, the code still has a chance to run and display any appropriate
messages, and that same code can verify any future downloads. You should,
however, verify that any hot code push service you use does the following:
-### Use InAppBrowser for outside links
-* Use the InAppBrowser when opening links to any outside website. This is much
safer than allow listing a domain name and including the content directly in
your application because the InAppBrowser will use the native browser's
security features and will not give the website access to your Cordova
environment. Even if you trust the third party website and include it directly
in your application, that third party website could link to malicious web
content.
+* Validate checksums to ensure complete and accurate downloads
+* Certificate checking to ensure that the download is from a trusted server
+* Falls back to last downloaded code in the event something goes wrong
-### Validate all user input
-* Always validate any and all input that your application accepts. This
includes usernames, passwords, dates, uploaded media, etc. Because an attacker
could manipulate your HTML and JS assets (either by decompiling your
application or using debugging tools like chrome://inspect), this validation
should also be performed on your server, especially before handing the data off
to any backend service.
-* Other sources where data should be validated: user documents, contacts, push
notifications
+## Encrypted Storage
-### Do not cache sensitive data
-* If usernames, password, geolocation information, and other sensitive data is
cached, then it could potentially be retrieved later by an unauthorized user or
application.
+Both **Android** and **iOS** offer various secure storage options. While
**Apache Cordova** does not provide these mechanisms natively at the platform
core or plugin level, third-party plugins may be available or can be created to
implement such features.
-### Don't use eval() unless you know what you're doing
-* The JavaScript function eval() has a long history of being abused. Using it
incorrectly can open your code up for injection attacks, debugging
difficulties, and slower code execution.
+**Android:**
-### Do not assume that your source code is secure
-* Since a Cordova application is built from HTML and JavaScript assets that
get packaged in a native container, you should not consider your code to be
secure. It is possible to reverse engineer a Cordova application.
+* [**Encrypted Shared
Preferences**](https://developer.android.com/reference/androidx/security/crypto/EncryptedSharedPreferences)
+
+ **Encrypted SharedPreferences** is an encrypted version of
SharedPreferences, where both the keys and values are encrypted. This is ideal
for storing small amounts of data, such as user settings, preferences, or other
sensitive information.
+
+* [**Encrypted File
Storage**](https://developer.android.com/reference/androidx/security/crypto/EncryptedFile)
+
+ **Encrypted File Storage** is suitable for securely storing files, perfect
for large data. By using the `EncryptedFile` class, you can create and read
encrypted files, ensuring that the file contents remain protected.
+
+**iOS:**
+
+* **File Protection**
+
+ Using
[`NSFileManager`](https://developer.apple.com/documentation/foundation/nsfilemanager),
which provides an interface for managing the file system, you can define a
file's protection level with the
[`NSFileProtectionType`](https://developer.apple.com/documentation/foundation/nsfileprotectiontype)
attribute. This allows you to store files on disk with protection based on the
device's lock state. Files are encrypted and accessible only when the device is
unlocked.
+
+* [**Keychain
Services**](https://developer.apple.com/documentation/security/keychain-services?language=objc)
+
+ **Keychain Services** is a secure method for storing small pieces of
sensitive data, such as passwords or tokens. Data in the keychain is encrypted
and protected by the device's security mechanisms.
## Recommended Articles and Other Resources
-* [HTML5 Security cheat sheet, detailing how to secure your HTML5
application](https://www.owasp.org/index.php/HTML5_Security_Cheat_Sheet)
-* [Whitepaper about well known security flaws in Webview based hybrid
applications](http://www.cis.syr.edu/~wedu/Research/paper/webview_acsac2011.pdf)
+* [OWASP Cheat Sheet Series - HTML5 Security Cheat
Sheet](https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html)
+* [Research Paper - Attacks on WebView in the Android
System](https://www.cs.ucr.edu/~heng/pubs/webview_acsac2011.pdf)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org
For additional commands, e-mail: commits-h...@cordova.apache.org
