1. Introduction
This section is not normative.
As the Web platform is extended to enable more useful and powerful applications, it becomes increasingly important to ensure that the features which enable those applications are enabled only in contexts which meet a minimum security bar. This document outlines threat models for feature abuse on the Web and outline normative requirements which should be incorporated into documents specifying new features.
The most obvious of the requirements discussed here is that application code with access to sensitive or private data be delivered over authenticated and confidential channels that guarantee data integrity. Delivering code securely cannot ensure that an application will always meet a user’s security and privacy requirments, but it is a necessary precondition.
2. Key Concepts and Terminology
- privileged context
-
A settings object is considered a privileged
context if the algorithm defined in §5.1
Is settings object a privileged context?
returns
Privileged
when executed upon it. Moreover:-
A
Document
is considered a privileged document if the algorithm defined in §5.1 Is settings object a privileged context? returnsPrivileged
when executed upon its incumbent settings object. -
A
Worker
,SharedWorker
, orServiceWorker
is considered a privileged worker if the algorithm defined in §5.1 Is settings object a privileged context? returnsPrivileged
when executed upon its incumbent settings object.
-
A
- embedding document
-
Given a
Document
A, the embedding document of A is theDocument
through which A’s browsing context is nested.
3. Should [insert feature here] require a privileged context?
This section is non-normative.
Certain web platform features that have a distinct impact on a user’s security or privacy should be available for use only in privileged contexts.
Broadly speaking, we consider a feature powerful enough to restrict when it fits into one or more of the following categories:
- The feature provides access to sensitive data (personally-identifying information, credentials, payment instruments, and so on). [CREDENTIAL-MANAGEMENT] is an example of such an API.
- The feature provides access to sensor data on a user’s device (camera, microphone, and GPS being particularly noteworthy, but certainly including less obviously dangerous sensors like the accelerometer). [GEOLOCATION-API] and [MEDIACAPTURE-STREAMS] are historical examples.
- The feature provides access to or information about other devices a user has access to. [DISCOVERY] and [BLUETOOTH] are good examples.
-
The feature exposes temporary or persistent identifiers, including
identifiers which reset themselves after some period of time
(e.g.
sessionStorage
), identifiers the user can manually reset (e.g. [ENCRYPTED-MEDIA], Cookies [RFC6265], and [IndexedDB]), as well as identifying hardware features the user can’t easily reset. - The feature introduces some state for an origin which persists across browsing sessions. [SERVICE-WORKERS] is a great example.
- The feature manipulates a user agent’s native UI in some way which removes, obscures, or manipulates details relevant to a user’s understanding of her context. [FULLSCREEN], for instance.
- The feature introduces some functionality for which user permission will be required.
This list is non-exhaustive, but should give you a feel for the types of features we should be concerned about when writing or implementing specifications.
Note: While restricting the feature itself to privileged contexts is critical, we ought not forget that facilities that carry such information (such as new network access mechanisms, or other generic functions with access to network data) are equally sensitive.
3.1. Threat Models
Granting permissions to unauthenticated origins is, in the presence of a network attacker, equivalent to granting the permissions to any origin. The state of the Internet is such that we must indeed assume that a network attacker is present. Generally, network attackers fall into 2 classes: passive and active.
3.1.1. Passive Network Attacker
A "Passive Network Attacker" is a party who is able to observe traffic flows but who lacks the ability or chooses not to modify traffic at the layers which this specification is concerned with.
Surveillance of networks in this manner "subverts the intent of communicating parties without the agreement of these parties" and one "cannot defend against the most nefarious actors while allowing monitoring by other actors no matter how benevolent some might consider them to be." [RFC7258] Therefore, the algorithms defined in this document require mechansims that provide for the privacy of data at the application layer, not simply integrity.
3.1.2. Active Network Attacker
An "Active Network Attacker" has all the capabilities of a "Passive Network Attacker" and is additionally able to modify, block or replay any data transiting the network. These capabilities are available to potential adversaries at many levels of capability, from compromised devices offering or simply participating in public wireless networks, to Internet Service Providers indirectly introducing security and privacy vulnerabilities while manipulating traffic for financial gain ([VERIZON] and [COMCAST] are recent examples), to parties with direct intent to compromise security or privacy who are able to target individual users, organizations or even entire populations.
4. Restricting Features
4.1. New Features
When writing a specification for new features, we recommend that authors and editors guard sensitive APIs with checks against §5.1 Is settings object a privileged context? . For example, something like the following would be a good approach:
-
If the incumbent settings object is not a privileged
context, then [insert something appropriate here: perhaps you
could reject a Promise with a
SecurityError
, call an error callback, deny a permission request, etc.].
Note: If you choose to copy/paste the above text for your spec, do remember to put an action appropriate for your use case in place of the placeholder text.
4.2. Legacy Features
The list above clearly includes some existing functionality that is currently available to the web over insecure channels. We recommend that such legacy functionality begin requiring a privileged context as quickly as is reasonably possible.
- If such a feature is not widely implemented, we recommend that the specification be immediately modified to include a restriction to privileged contexts.
- If such a feature is widely implemented, but not yet in wide use, we recommend that it be quickly restricted to privileged contexts by adding a check as described in §4.1 New Features to existing implementations, and modifying the specification accordingly.
- If such a feature is in wide use, we recommend that the existing functionality be deprecated; the specification should be modified to note that it does not conform to the restrictions outlined in this document, and a plan should be developed to both offer a conformant version of the feature and to migrate existing users into that new version.
4.2.1. Example: Geolocation
The [GEOLOCATION-API] is a good concrete example of such an feature; it is widely implemented and used on a large number of insecure sites. A reasonable path forward might look like this:
-
Modify the specification to include
checks against [[#settings-privileged] before executing the algorithms for
getCurrentPosition()
andwatchPosition()
.If §5.1 Is settings object a privileged context? returns
Not Privileged
, then the algorithms should be aborted, and the errorCallback invoked with acode
ofPERMISSION_DENIED
. - User agents should announce clear intentions to disable the API for unprivileged contexts on a specific date, and warn developers accordingly (via console messages, for example).
-
Leading up to the flag day, user agents should announce a deprecation
schedule to ensure both that site authors recognize the need to modify
their code before it simply stops working altogether, and to protect
users in the meantime. Such a plan might include:
- Disallowing persistent permission grants to insecure origins
- Coarsening the accuracy of the API for insecure origins (perhaps consistently returning city-level data rather than high-accuracy data)
- UI modifications to inform users and site authors of the risk
5. Algorithms
5.1. Is settings object a privileged context?
Given a settings object settings, this algorithm returns
Privileged
if the object represents a privileged
context, and Not Privileged
otherwise.
-
If settings' TLS state is not
authenticated
:- Let origin be settings' origin.
-
If origin is a globally unique identifier, set
origin to the origin
of settings’s API base URL.
Note: This is future-proofing against a world where sandboxing
Worker
is a thing."API base URL" isn’t correct. We should use whatever gets produced as a result of bug 27146.
-
If the result of executing the §5.2
Is origin potentially trustworthy?
algorithm
on origin is not
Potentially Trustworthy
, returnNot Privileged
.
TLS State is poorly defined. For example, we should ensure that sandboxed documents retain the TLS State associated with their transport mechanism. See bug 27190.
-
If settings has a responsible document
document, then:
Note: If settings maps to a
Document
(either directly, or as the responsible document of aWorker
), we’ll walk all the way up the document’s ancestor chain to verify that the whole chain is privileged.-
Let documents to check be a list of
Document
s containing document and the active document in each of document’s ancestor browsing contexts. -
For each ancestor in documents to check:
-
If ancestor corresponds to an IFrame
srcdoc
Document
, skip to the next ancestor. -
If ancestor’s incumbent settings object’s
TLS State is
Authenticated
, skip to the next ancestor. -
Let origin be ancestor’s origin if
ancestor’s active sandboxing flag set does not
have its sandboxed origin browsing context flag set, and
the origin of ancestor’s
URL
otherwise. -
If the result of executing the §5.2
Is origin potentially trustworthy?
algorithm on origin is not
Potentially Trustworthy
, returnNot Privileged
.
-
If ancestor corresponds to an IFrame
-
Let documents to check be a list of
-
Return
Privileged
5.2. Is origin potentially trustworthy?
Certain origins are always potentially trustworthy. In particular, UAs
MUST treat file
URLs and URLs with hostnames names equivalent
to "localhost" as potentially trustworthy. In principle the UA could treat
local files and local web servers as untrustworthy. However, given the
information that is available to the UA at runtime, the resources
appear to have been transported securely. Additionally, treating such
resources as potentially trustworthy is convenient for developers building
an application before deploying it to the public.
A user agent MAY choose to extend this trust to other, vendor-specific URL
schemes like app:
or chrome-extension:
.
Given an origin origin, the following algorithm returns
Potentially Trustworthy
or Not Trustworthy
as
appropriate.
-
If origin is a potentially secure origin,
return
Potentially Trustworthy
.Note: The origin of
blob:
andfilesystem:
URLs is the origin of the context in which they were created. Therefore, blobs created in an potentially secure origin will themselves be potentially secure. The origin ofdata:
andjavascript:
URLs is an opaque identifier, which will not be considered potentially secure. -
If origin’s
host
component is or falls withinlocalhost.
[RFC6761], returnPotentially Trustworthy
. -
If origin’s
host
component matches one of the CIDR notations127.0.0.0/8
or::1/128
[RFC4632], returnPotentially Trustworthy
. -
If origin’s
scheme
component isfile
, returnPotentially Trustworthy
. -
If origin’s
scheme
component is one which the user agent considers to be authenticated, returnPotentially Trustworthy
.Note: See §6.1 Packaged Applications for detail here.
-
If origin has been configured as a trustworthy origin,
return
Potentially Trustworthy
.Note: See §6.2 Development Environments for detail here.
-
Return
Not Trusted
.
6. Implementation Considerations
6.1. Packaged Applications
User agents that support packaged applications MAY whitelist specific URL
schemes whose contents are authenticated by the user agent. For example,
FirefoxOS application resources are referred to by a URL whose
scheme
component is app:
. Likewise, Chrome’s
extensions and apps live on chrome-extension:
schemes. These
could reasonably be considered trusted origins.
6.2. Development Environments
In order to support developers who run staging servers on non-loopback hosts,
user agents MAY allow users to configure specific sets of origins as
trustworthy, even though §5.2
Is origin potentially trustworthy?
would normally return
Not Trusted
.
7. Acknowledgements
This document is largely based on the Chrome Security team’s work on [POWERFUL-NEW-FEATURES]. Chris Palmer, Ryan Sleevi, and David Dorwin have been particularly engaged. Anne van Kesteren and Henri Sivonen have also provided very helpful feedback.