Secure Contexts

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 level. This document describes threat models for feature abuse on the web (see §4.1 Threat Models) and outlines normative requirements which should be incorporated into documents specifying new features (see §7 Implementation Considerations).

The most obvious of the requirements discussed here is that application code with access to sensitive or private data be delivered confidentially over authenticated 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.

Less obviously, application code delivered over an authenticated and confidential channel isn’t enough in and of itself to limit the use of powerful features by non-secure contexts. As §4.2 Ancestral Risk explains, cooperative frames can be abused to bypass otherwise solid restrictions on a feature. The algorithms defined below ensure that these bypasses are difficult and user-visible.

The following examples summarize the normative text which follows:

1.1. Top-level Documents

Top-level documents are secure as long as they don’t have a non-secure opener browsing context. This is a bit convoluted, so let’s go straight to the examples:

Link!
      

noopener" target="_blank">Link!
      

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:

1.3. Web Workers

Dedicated Workers are similar in nature to framed documents. They’re secure contexts when they’re delivered from potentially trustworthy origins, only if their owner is itself a secure context:

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 a 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.

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.

2. Framework

An environment settings object is considered a secure context if the algorithm in §3.1 Is settings object a secure context? returns "Secure", and a non-secure context otherwise.

Likewise, a global object is considered a secure context if its relevant settings object is a secure context.

2.1. Intergration with WebIDL

This section is non-normative.

A new [SecureContext] attribute is available for operators, which ensures that they will only be exposed into secure contexts. The following example should help:

interface ExampleFeature {
  // This call will succeed in all contexts.
  Promise <double> calculateNotSoSecretResult();

  // This operation will not be exposed to a non-secure context.
  [SecureContext] Promise<double> calculateSecretResult();

  // The same applies here: the operation will not be exposed to a non-secure context.
  [SecureContext] boolean getSecretBoolean();
};

[SecureContext]
interface SecureFeature {
  // This interface will not be exposed to non-secure contexts.
  Promise<any> doAmazingThing();
};

Specification authors are encouraged to use this attribute when defining new features.

2.2. Modifications to HTML

2.2.1. Shared Workers

The SharedWorker() constructor will throw a SecurityError exception if a secure context attempts to attach to an Worker which is not a secure context, and if a non-secure context attempts to attach to a Worker which is a secure context. The constructor is modified as follows:

1. As the first substep of the SharedWorker() constructor’s current step 6.7 ("If worker global scope is not null, then run these steps:"), run the following step:

   1. If the result of executing §3.1 Is settings object a secure context? on the current 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 these steps.

Upstreaming to WHATWG is underway.

It’s not clear to me how the W3C’s [WEBWORKERS] document is updated. It looks like it’s pulling content from the WHATWG upstream, which means that the PR linked above should flow into it? But that document hasn’t been updated since 2015, so...

2.2.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 WindowOrWorkerGlobalScope {
  readonly attribute boolean isSecureContext;
};

interface GlobalSecureContext {
  readonly attribute boolean isSecureContext;
};
Window implements GlobalSecureContext;
WorkerGlobalScope implements WindowBase64;

The isSecureContext attribute’s getter returns true if §3.1 Is settings object a secure context? returns "Secure" when executed upon this global object’s relevant settings object, and false otherwise.

3. Algorithms

3.1. Is settings object a secure context?

Given an environment settings object (settings) this algorithm returns "Secure" if the object represents a context which the user agent obtained via a secure channel, and "Not Secure" otherwise.

1. Let global be settings’s global object.

2. If global is a WorkerGlobalScope, then:

   1. For each Document (document) in global’s list of the worker’s Documents:

      1. If §3.1 Is settings object a secure context? returns "Not Secure" when executed upon document’s relevant settings object, return "Not Secure".

3. Assert: global is a Window.

4. If settings object’s responsible document has an creator browsing context whose creator context security is "Not Secure", return "Not Secure".

   Note: Since we take account of creator browsing contexts' status, a popups' status depends on how it is opened, as discussed in §1.1 Top-level Documents.

   The 'creator context security' concept doesn’t yet exist, other than in an open PR against WHATWG’s HTML.

   The 'creator context security' concept doesn’t yet exist in W3C’s HTML.

5. If settings object’s HTTPS state is "modern", return "Secure".

   Most of the time, this check will be enough to determine whether a particular context was securely delivered. Documents delivered over TLS will have their HTTPS state set, and srcdoc Documents inherit their ancestor’s HTTPS state (as do other kinds of requests which inherit their requestor’s origin: see the basic fetch algorithm for details on some of these [FETCH]).

   We only continue past this check in order to allow resources delivered from "trustworthy" but unauthenticated locations like http://127.0.0.1/ to be treated as creating a secure context.

6. Let origin be settings object’s origin.

7. If origin is an opaque origin, set origin to the origin of settings object’s creation URL.

   Note: We use the origin of the URL here because sandboxed content that is treated as being in a unique origin (e.g.