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 requirements, but it is a necessary precondition.
1.1. Examples
1.1.1. Top-level Documents
Top-level documents are secure on their own merits:
https://example.com/
opened in a top-level browsing
context is a secure context, as it was delivered over
an authenticated and encrypted channel.
http://non-secure.example.com/
opened in a top-level
browsing context pops open a new window containing https://example.com/
. The former is not a secure
context; the latter is a secure context, because it is a new
top-level browsing context delivered over an authenticated and encrypted
channel.
1.1.2. Framed Documents
Framed documents can be secure contexts if they are delivered from potentially trustworthy origins, and if they’re embedded in a secure context. That is:
if https://example.com/
opened in a top-level browsing
context opens https://sub.example.com/
in a frame, then
both are secure contexts, as both were delivered over
authenticated and encrypted channels.
If https://example.com/
was somehow able to frame http://non-secure.example.com/
(perhaps the user has
overridden mixed content checking?), the top-level frame would remain
secure, but the framed content is not a secure context.
If, on the other hand, https://example.com/
is framed
inside of http://non-secure.example.com/
, then it is not a secure context, as its ancestor is not delivered over an
authenticated and encrypted channel.
1.1.3. Web Workers
Dedicated Web Workers are similar in nature to framed documents. They’re secure contexts when they’re delivered from potentially trustworthy origins, and when their owner is itself a secure context:
If https://example.com/
in a top-level browsing
context runs https://example.com/worker.js
, then
both the document and the worker are secure contexts.
If http://non-secure.example.com/
in a top-level browsing
context frames https://example.com/
, which runs https://example.com/worker.js
, then neither the framed document
nor the worker are secure contexts.
1.1.4. Shared Workers
Multiple contexts may attach to a Shared Worker. If a secure context creates a Shared Worker, then it is a secure context, and may only be attached to by other secure contexts. If an non-secure context creates a Shared Worker, then it is not a secure context, and may only be attached to by other non-secure contexts.
If https://example.com/
in a top-level browsing
context runs https://example.com/worker.js
as a Shared
Worker, then both the document and the worker are considered secure
contexts.
If https://example.com/
in a different top-level
browsing context (e.g. in a new window) is a secure context, so it may
access the secure shared worker:
https://example.com/
nested in http://non-secure.example.com/
may not connect to the secure
worker, as it is not a secure context.
Likewise, if https://example.com/
nested in http://non-secure.example.com/
runs https://example.com/worker.js
as a Shared
Worker, then both the document and the worker are considered non-secure.
1.1.5. Service Workers
Service Workers are always secure contexts. Only secure contexts may register them, and they may only have clients which are secure contexts.
If https://example.com/
in a top-level browsing
context registers https://example.com/service.js
,
then both the document and the Service Worker are considered secure
contexts.
2. Framework
A settings object is considered a secure context if
the algorithm in §3.1 Is settings object a secure context? returns "Secure
". The settings
object is otherwise non-secure.
2.1. Modifications to HTML
2.1.1. Shared Workers
The SharedWorker()
constructor will throw a SecurtyError
exception if
a if a secure context attempts to attach to an Worker which is not a secure context, and if an non-secure context attempts to attach to a
Worker which is a secure context. The constructor is modified as
follows:
-
As the first substep of the
SharedWorker()
constructor’s current step 7.7 ("If worker global scope is notnull
, then run these steps:"), run the following step:-
If the result of executing §3.1 Is settings object a secure context? on the incumbent settings object does not match the result of executing the same algorithm on worker global scope’s relevant settings object, then throw a
SecurityError
exception, and abort the remaining steps.
-
2.1.2. Feature Detection
To determine whether a context is capable of making use of features which require secure contexts, a simple boolean attribute is added to the global object:
partial interface Window { readonly attribute boolean isSecureContext; }; partial interface WorkerGlobalScope { readonly attribute boolean isSecureContext; };
Both Window
's isSecureContext
and WorkerGlobalScope
's isSecureContext
attribute’s getters return true
if the relevant settings object for the getter’s global object is a secure context, and false
otherwise.
3. Algorithms
3.1. Is settings object a secure context?
Given a settings object (settings), this algorithm returns
"Secure
" if the object represents a context which the user agent fetched via
a secure channel, and "Not Secure
" otherwise.
-
Let ancestors be a list containing settings.
-
If settings' global object is a
WorkerGlobalScope
, then:-
For each
Document
(document) in settings' global object’s list of the worker’sDocuments
:-
Add each item in the result of executing §3.3 Gather document’s relevant ancestors on document to ancestors.
-
-
-
Otherwise, settings' global object is a
Window
, so:-
Add each item in the result of executing §3.3 Gather document’s relevant ancestors on settings' responsible document to ancestors.
-
-
For each ancestor settings in ancestors:
-
If ancestor settings’s HTTPS state is "
modern
", skip to the next ancestor settings. -
Let origin be ancestor settings' origin.
-
If origin is a globally unique identifier, set origin to the origin of settings’s creation URL.
Note: We use the origin of the URL here in order to allow sandboxed context to remain secure (as sandboxing is a strict reduction in the context’s capabilities, and therefore to the risk it poses). This covers scenarios such as
<iframe sandbox src="http://localhost/">
. -
If the result of executing the §3.2 Is origin potentially trustworthy? algorithm on origin is not
Potentially Trustworthy
, then return "Not Secure
".
-
-
Return "
Secure
".
3.2. Is origin potentially trustworthy?
A potentially trustworthy origin is one which a user agent can generally trust as delivering data securely.
Certain origins are always potentially trustworthy. In particular, user agents
MUST treat file
URLs and URLs with hostnames names equivalent to localhost
as potentially trustworthy. In principle the user agent could
treat local files and local web servers as untrustworthy, but, given the
information that is available to the user agent 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
.
3.3. Gather document’s relevant ancestors
Given a Document
(document), this algorithm returns a list of settings objects which ought to be considered when determining whether
or not document is a secure context.
-
Let ancestors be a list containing document’s relevant settings object.
-
While document has a creator
Document
creator:-
If creator’s browsing context is an ancestor browsing context of document:
-
Insert creator’s relevant settings object into ancestors, unless creator is an IFrame
srcdoc
Document
. -
Let document be creator.
-
-
Otherwise, exit this loop.
-
-
Return ancestors.
Note: When gathering a Document
's ancestors, we walk the browsing context
creation document chain, but stop when that chain spans across more than one Window
. That is, a newly opened window is evaluated on its own merits,
without regard for the status of the opener.
4. Threat models and risks
This section is non-normative.
4.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.
4.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.
4.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.2. Risks associated with non-secure contexts
Certain web platform features that have a distinct impact on a user’s security or privacy should be available for use only in secure contexts in order to defend against the threats above. Features available in non-secure contexts risk exposing these capabilities to network attackers:
- The ability to read and modify sensitive data (personally-identifying information, credentials, payment instruments, and so on). [CREDENTIAL-MANAGEMENT] is an example of an API that handles sensitive data.
- The ability to read and modify input from sensors 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 of features that use sensor input.
- The ability to access information about other devices a user has access to. [DISCOVERY] and [BLUETOOTH] are good examples.
- The ability to track users using 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 ability to introduce some state for an origin which persists across browsing sessions. [SERVICE-WORKERS] is a great example.
- The ability to manipulate a user agent’s native UI in some way which removes, obscures, or manipulates details relevant to a user’s understanding of their context. [FULLSCREEN], for instance.
- The ability to introduce some functionality for which user permission will be required.
This list is non-exhaustive, but should give you a feel for the types of risks we should consider when writing or implementing specifications.
Note: While restricting a feature itself to secure 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.
5. Security Considerations
5.1. Incomplete Isolation
The secure context definition in this document does not completely
isolate a "secure" view on an origin from an "non-secure" view on the same
origin. That is, a developer who is actively working to bypass the secure
context restriction on a particular API will be able to create a postMessage
-based shim if they’re willing to pop up a new window
and rely on its persistence (as the new window will be a new top-level
browsing context, and will be evaluated without regard for the opener’s
state).
More esoteric exfiltration methods will be available as well, ranging from
shared localStorage
and related storage
events to window.name
tricks.
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 §3.2 Is origin potentially trustworthy? would normally return Not Trusted
.
6.3. Restricting New Features
This section is non-normative.
When writing a specification for new features, we recommend that authors and editors guard sensitive APIs with checks against secure contexts. For example, something like the following might be a good approach:
-
If the incumbent settings object is not a secure
context, then:
- [insert something appropriate here: perhaps a Promise could be
rejected with a
SecurityError
, an error callback could be called, a permission request denied, etc.].
- [insert something appropriate here: perhaps a Promise could be
rejected with a
6.4. Restricting Legacy Features
This section is non-normative.
The list above clearly includes some existing functionality that is currently available to the web over non-secure channels. We recommend that such legacy functionality begin requiring a secure 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 secure contexts.
-
If such a feature is widely implemented, but not yet in wide use, we recommend that it be quickly restricted to secure contexts by adding a check as described in §6.3 Restricting 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.
6.4.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 non-secure sites. A reasonable path forward might look like this:
-
Modify the specification to include checks against secure context before executing the algorithms for
getCurrentPosition()
andwatchPosition()
.If the incumbent settings object is not a secure context, then the algorithms should be aborted, and the errorCallback invoked with a
code
ofPERMISSION_DENIED
. -
User agents should announce clear intentions to disable the API for non-secure 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 any or all of:
-
Disallowing persistent permission grants to non-secure origins
-
Coarsening the accuracy of the API for non-secure origins (perhaps consistently returning city-level data rather than high-accuracy data)
-
UI modifications to inform users and site authors of the risk
-
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, Boris Zbarsky, and Henri Sivonen have also provided very helpful feedback.