Confinement with Origin Web Labels

1.1. Goals

The goal of COWL is to provide authors with a means for protecting the confidentiality and integrity of data that is shared with untrusted code, whether third-party or their own. Existing mechanisms (e.g., CORS’s Access-Control-Allow-Origin header and the targetOrigin argument to postMessage()) provide a way for restricting which origins may access the shared data. But, once content has access to data it can usually disseminate it without restrictions. While CSP can be used to confine code, i.e., restrict how confidential data is disseminated, setting a correct CSP policy (as to confine code) is difficult and limited to content the author has control over. Indeed, sharing confidential data in the existing model almost always requires the sender to trust the receiver not to leak the data, accidentally or otherwise. COWL provides a defense-in-depth option for protecting data confidentiality and integrity. In particular, with COWL:

1. Authors should be able to specify confidentiality and integrity policies on data in terms of origin labels: the origins to whom the data is confidential and the origins that endorse the data. This allows authors to share sensitive data with third-party content and impose restrictions on the origins with which it can communicate once it inspects the sensitive data. Dually, it allows authors to share data via intermediate content while retaining its integrity.

2. Authors should be able to run code with least privilege by restricting the origins the code can communicate with and thus how it can disseminate sensitive data.

3. Authors should be able to privilege separate applications by compartmentalizing them into separate contexts that have delegated privileges.

1.2. Use Cases/Examples

1.2.1. Confining untrusted third-party services

An author wishes to use a service, loaded in the form of an iframe, without trusting it (or its dependencies) to not leak her sensitive data. To protect the data, the author associates a confidentiality label with the data, specifying the origins allowed to read the data. The author then shares the newly created labeled object with the untrusted code. In turn, COWL confines the untrusted code once it inspects the sensitive data, as to ensure that it can only communicate according to the author-specified policy (the label).

// Create new policy using Labels that specifies that the password is sensitive
// to https://example.com and should only be disclosed to this origin:
var policy = new Label(window.location.origin);

// Associate the label with the password:
var labeledPassword = new LabeledObject(password, {confidentiality: policy});

// Send the labeled password to the checker iframe:
checker.postMessage(labeledPassword, "https://untrusted.com");

// Register listener to receive a response from checker, etc.

Other use cases in this category include password managers and encrypted document editors, for example, where an encryption/decryption layer and a storage layer are provided by distrusting, but not malicious, services. The academic paper on COWL describes these use cases in detail [COWL-OSDI].

1.2.2. Sharing data with third-party mashups

A server operator wishes to provide third-party mashups access to user data. In addition to using CORS response headers to restrict the origins that can access the data [CORS], the operator wishes to restrict how the data is further disseminated by these origins. To do so, the operator sends a response header field named Sec-COWL (described in §3.5.2 The Sec-COWL HTTP Response Header Field) whose value contains the sensitivity of the data in the form of a serialized confidentiality label. In turn, COWL enforces the label restrictions on the third-party code.

Access-Control-Allow-Origin: https://mashup.com
Sec-COWL: data-confidentiality [ ["https://provider.com"] ]

1.2.3. Content isolation via privilege separation

A server operator wishes to isolate content (e.g., of different users) while serving it from a single physical origin. The operator can leverage privileges to ensure that content of one part of the site has different authority from another and, importantly, does not have authority of the physical origin. Concretely, when serving content, the operator can set the content’s context privilege to a weaker, delegated privilege. This ensures that the content are privilege separated.

Sec-COWL: ctx-privilege [ ['self', 'cowl://user1'] ]

1.2.4. Running content with least-privileges

An author wishes to use a library that is tightly coupled with the page (e.g., jQuery), but not trust it to protect the user’s confidentiality and integrity. With COWL, the author can do this by loading the untrusted library after dropping privileges (from the context’s default privilege). In doing so, the content (and thus the library) loses its implicit authority over the content’s origin.

// Drop privileges, by setting the context privilege to an empty privilege:
COWL.privilege = new Privilege();

// Load untrusted library

Sec-COWL: ctx-privilege [ [] ]

In some cases it is useful for a particular context to have the privilege to disseminate certain categories of data. (The or part of labels can be used to easily categorize differently-sensitive data.) To this end, the author should run the context with a delegated privilege instead of the empty privilege. The above §1.2.3 Content isolation via privilege separation shows one such example.

1.3. Trust Model

Similarly, COWL provides no guarantees against attacks wherein users are manipulated into leaking sensitive data via out-of-band channels. For example, an attacker may be able to convince a user to navigate their user agent to an attacker-owned origin by entering a URL that contains sensitive information into the user agent’s address bar.

3.1. Labels

Each label is an immutable object represented by a Label object, the interface of which is defined in this section.

A Label MUST have an internal label set, which is a non-empty set of disjunction sets.

A disjunction set is a set of origin URLs.

A label is said to be an empty label if its label set contains a single, empty disjunction set.

[Constructor, Constructor(DOMString origin), Exposed=Window, Worker]
interface Label {
  boolean equals(Label other);
  boolean subsumes(Label other, optional Privilege priv);

  Label and((Label or DOMString) other);
  Label _or((Label or DOMString) other);

  object toJSON();
  [Throws] static Label fromJSON(object obj, optional DOMString self);
};

Current WebIDL implementation requires an underscore for certain identifiers. Can we rename _or to or?

3.1.1. Constructors

Label()

When invoking the Label() constructor, the user agent MUST return a new empty label.

Label(DOMString origin)

When invoking the Label(origin) constructor, the user agent MUST use an algorithm equivalent to the following:

1. If the origin argument is not a URL, the constructor MUST throw a TypeError exception [ECMA-262] and terminate this algorithm.

2. Else, it MUST return a new Label that contains a label set of a single disjunction set, which itself MUST contain the URL corresponding to the origin of the parameter.

3.1.2. Methods

equals(Label other)

The user agent MUST return true if the Label on which the method has been called is equivalent to the other parameter; otherwise it MUST return false.

subsumes(Label other, optional Privilege priv)

The user agent MUST use an algorithm equivalent to the following:

1. Let lab be the Label on which the method has been called.

2. If the priv argument is provided, let lab be lab.and(priv.asLabel()).

3. Return true if lab subsumes the other parameter and false otherwise.

and((Label or DOMString) other)

The user agent MUST use an algorithm equivalent to the following:

1. Let O be the other argument.

2. If the type of other is DOMString, run the following sub-steps:

   1. Set O to the result of invoking the Label(other) constructor with other as an argument, if the constructor did not raise an exception.

   2. Else, re-throw the exception and terminate this algorithm.

3. Return a new normal form Label that is equivalent to a label whose label set contains the disjunction sets of O and the Label on which the method was invoked.

_or((Label or DOMString) other)

The user agent MUST use an algorithm equivalent to the following:

1. Let O be the other argument.

2. If the type of other is DOMString, run the following sub-steps:

   1. Set O to the result of invoking the Label(other) constructor with other as an argument, if the constructor did not raise an exception.

   2. Else, re-throw the exception and terminate this algorithm.

3. Return a new Label, in normal form, which is equivalent to adding each element of each disjunction set of O’s label set to each disjunction set of the label set of the Label on which the method was called.

toJSON()

The user agent MUST use an algorithm equivalent to the following:

1. Let JSON lset be a new JSON array.

2. For each disjunction set dset in the label set of the label, this method was invoked on:

   1. Let JSON dset be a JSON array of strings, each corresponding to an origin in dset.

   2. Append JSON dset to the JSON lset array.

3. Return JSON lset.

fromJSON(obj, self)

The user agent MUST use an algorithm equivalent to the following:

1. If obj is not a JSON array of entries, each of which is a JSON array of strings, throw a TypeError exception [ECMA-262] and terminate this algorithm.

2. Let self be null.

3. If the self argument is provided:

   1. If the argument is not a URL, the function MUST throw a TypeError exception [ECMA-262] and terminate this algorithm.

   2. Else, set self to the self argument.

4. Let lab be a new empty label.

5. For each array element dset of obj:

   1. Let dset label be a new empty label.

   2. For each string str of dset:

      1. If str is "unique", let origin be a globally unique identifier.

         Much like FreshPrivilege(), "unique" is used to create a label component that is globally unique.

      2. Else, if str is "self" and self is not null, let origin be self.

      3. Else, if str is a URL, let origin be str.

      4. Else, throw a TypeError exception [ECMA-262] and terminate this algorithm.

      5. Let dset label be dset label._or(origin)

   3. Let lab be lab.and(dset label)

3.1.3. Examples

// C: Public data.
// I: Non-endorsed/untrustworthy data.
var empty = new Label();

// C: Data confidential to a.com.
// I: Data endorsed/trusted by a.com.
var a = new Label("https://a.com");

// C: Data confidential to b.com.
// I: Data endorsed/trusted by b.com.
var a = new Label("https://b.com");

// C: Data confidential to both a.com and b.com
// I: Data endorsed/trusted by a.com and b.com.
var aANDb = new Label("https://a.com").and("https://b.com");

// C: Data confidential to either a.com or b.com.
// I: Data endorsed/trusted by either a.com or b.com.
var aORb = new Label("https://a.com")._or("https://b.com");

// C: Data confidential to a.com (b.com) data is more sensitive than public data.
// I: Data endorsed by a.com (b.com) is more trustworthy than non-endorsed/untrustworthy data.
a.subsumes(empty) === true;
b.subsumes(empty) === true;

// C: Data that is confidential to a.com and b.com is more
//    confidential than data that is only sensitive to a.com (b.com).
// I: Data that is endorsed/trusted by both a.com and b.com is
//    more trustworthy than data endorsed only by a.com (b.com).
aANDb.subsumes(a) === true;
aANDb.subsumes(b) === true;

// C: Data that that is confidential to a.com (b.com) is not comparable to
//    data that is confidential to b.com (a.com).
// I: Data that that is endorsed by a.com (b.com) is not comparable to
//    data that is endorsed by b.com (a.com).
a.subsumes(b) === false;
b.subsumes(a) === false;

// C: Data that is confidential to a.com (b.com) is more confidential than data that is
//    confidential to either a.com or b.com. Alternative intuition: data that can be read by
//    a.com or b.com can be read by an entity that can read a.com (b.com) data alone.
// I: Data that is endorsed by a.com (b.com) is more trustworthy than data that is endorsed
//    by either a.com or b.com. Alternative intuition: an entity that trusts data endorsed
//    by either a.com or b.com necessarily trusts data endorsed by a.com (b.com) alone.
a.subsumes(aOrb) === true;
b.subsumes(aOrb) === true;

var aORbANDc = aORb.and(new Label("https://c.com");

JSON.stringify(empty)    === '[[]]';
JSON.stringify(a)        === '[["https://a.com"]]';
JSON.stringify(aANDb)    === '[["https://a.com"], ["https://b.com"]]';
JSON.stringify(aORb)     === '[["https://a.com", "https://b.com"]]';
JSON.stringify(aORbANDc) === '[["https://a.com", "https://b.com"], ["https://c.com"]]';

Label.fromJSON([[]]).equals(empty) === true;
Label.fromJSON([["https://a.com"]]).equals(a) === true;
Label.fromJSON([["https://a.com"], ["https://b.com"]]).equals(aANDb) === true;
Label.fromJSON([["https://a.com", "https://b.com"]]).equals(aORb) === true;
Label.fromJSON([["https://a.com", "https://b.com"], ["https://c.com"]]).equals(aORbANDc) === true;
Label.fromJSON([["self"]], "https://a.com").equals(a) === true;
Label.fromJSON([["unique"]]).equals(Label.fromJSON([["unique"]])) === false;

3.2. Privileges

Each privilege is an immutable object represented by a Privilege object, the interface of which is defined in this section.

A Privilege MUST have an internal privilege label.

The combination of privileges A and B is a privilege produced by invoking the combine() method on A (respectively, B) with B (respectively, A) as an argument.

A privilege is said to be an empty privilege if its internal privilege label is the empty label. A context is said to be unprivileged if its context privilege is the empty privilege. By setting the context privilege to the empty privilege, a context is said to be dropping privileges.

A privilege P1 is said to be a delegated privilege of P2 if P2’s internal privilege label subsumes P1’s internal privilege label.

[Constructor, Exposed=Window, Worker]
interface Privilege {
  static Privilege FreshPrivilege(); // Named constructor
  Label asLabel();

  Privilege combine(Privilege other);
  [Throws] Privilege delegate(Label label);
};

Bikeshed does not allow WebIDL’s NamedConstructor. For now, inlining the constructor as a static method.

3.2.1. Constructors

Privilege()

When invoking the Privilege() constructor, the user agent MUST return a new Privilege that has an internal privilege label set to Label().

FreshPrivilege()

When invoking the FreshPrivilege() constructor, the user agent MUST use an algorithm equivalent to the following:

1. Let unique Label be the label produced by invoking the Label(other) constructor with a globally unique identifier.

2. Return a new Privilege that has an internal privilege label set to unique Label.

3.2.2. Methods

asLabel()

The user agent MUST return the internal privilege label of the Privilege on which the method has been called.

combine(Privilege other)

The user agent MUST return a new Privilege whose internal privilege label is equivalent to a label created according to an algorithm equivalent to the following:

1. Let internalLabel be the internal privilege label of the Privilege on which the method has been called.

2. Let otherLabel be the internal privilege label of the other argument.

3. Return internalLabel.and(otherLabel).

delegate(Label label)

The user agent MUST return a new Privilege whose internal privilege label is equivalent to a label created according to an algorithm equivalent to the following:

1. Let internalLabel be the internal privilege label of the Privilege on which the method has been called.

2. If the internalLabel does not subsume the label argument, throw a SecurityError exception and terminate this algorithm.

3. Else, return a new Privilege that has an internal privilege label set to label.

3.2.3. Examples

// Save privilege in case we need it later:
var __savedPriv = COWL.privilege;

// Drop privilege (set the context privilege to the empty privilege):
COWL.privilege = new Privilege();

// Create new fresh privilege:
var priv = new FreshPrivilege();

// Take ownership of the fresh privilege:
COWL.privilege = COWL.privilege.combine(priv);

// Associate the unique label with the password:
var labeledPassword = new LabeledObject(password, {confidentiality: priv.asLabel()});

// Send the labeled password to the checker iframe:
checker.postMessage(labeledPassword, "https://untrusted.com");

// Create a label corresponding to the university origin:
var uni = new Label(window.location.origin);
// Create a new label that corresponds to user1’s data on university.edu:
var user1 = uni._or("cowl://user1"); // Here the cowl:// is an arbitrary scheme

// Originally, COWL.privilege.asLabel().equals(uni).
// Drop the current context privilege to a delegated privilege:
COWL.privilege = COWL.privilege.delegate(user1);

3.3. Labeled Contexts

COWL extends browsing contexts and Workers with a COWL state, which is used to restrict the context’s communication channels. In this document, the term context is used to refer to both browsing contexts and Workers. The COWL state consists of:

• The confinement mode status, which indicates whether or not COWL confinement is enabled and thus labels should be enforced in the current context.

• The context labels, which consist of:

  • context confidentiality label reflects the sensitivity of the data that the context has read.

  • context integrity label reflects the integrity of the data that the context has read.

• The context privilege, which encodes the context’s ability to bypass the restrictions of certain labels.

Each context’s COWL state MUST be initially set to the default COWL state, where:

• The confinement mode is disabled.

• The context confidentiality label is set to the default confidentiality label: empty label.

• The context integrity label is set to the default integrity label: empty label.

• The context privilege is set to the default privilege: a privilege whose internal privilege label is equivalent to Label(origin), where origin is the string representation of the context or Worker’s origin.

Each context’s COWL state is made available via the COWL interface defined below.

[Exposed=Window, Worker]
interface COWL {
  static void enable();
  static boolean isEnabled();

  [SetterThrows] static attribute Label confidentiality;
  [SetterThrows] static attribute Label integrity;

  [SetterThrows] static attribute Privilege privilege;
};

3.3.1. Attributes

confidentiality, of type Label

• On getting, the user agent MUST return the current confidentiality label.

• On setting, the user agent MUST use an algorithm equivalent to the following:

  1. Enable confinement mode.

  2. Let conf be the set confidentiality label.

  3. Let canWrite be the result of invoking the write check algorithm with conf and the current integrity label.

  4. If canWrite is false, throw a SecurityError exception and terminate this algorithm.

  5. Else, set the current confidentiality label to conf.

integrity, of type Label

• On getting, the user agent MUST return the current integrity label.

• On setting, the user agent MUST use an algorithm equivalent to the following:

  1. Enable confinement mode.

  2. Let int be the set integrity label.

  3. Let canWrite be the result of invoking the write check algorithm with the current confidentiality label and int.

  4. If canWrite is false, throw a SecurityError exception and terminate this algorithm.

  5. Else, set the current integrity label to int.

privilege, of type Privilege

• On getting, the user agent MUST return the current privilege.

• On setting, the user agent MUST enable confinement mode and set the current privilege to the set privilege.

3.3.2. Methods

enable()

On invocation, the user agent MUST enable confinement mode by setting the current context’s COWL state confinement mode status.

isEnabled()

On invocation, the user agent MUST return true if the confinement mode is enabled for the current context; else, it MUST return false

3.3.3. Examples

COWL.isEnabled() === false;
COWL.enable();
COWL.isEnabled() === true;

COWL.integrity = new Label(window.location.origin);

COWL.confidentiality = new Label('https://provider.com');

3.4. Labeled Objects

A LabeledObject interface represents an immutable object that is protected by a confidentiality and integrity label, i.e., the object has associated labels.

This API is designed to be used in conjunction with other APIs and elements on the web platform. In particular, postMessage(), Web Workers, and XMLHttpRequest (e.g., with an overloaded send() method for LabeledObject arguments).

A LabeledObject MUST have an internal protected object, a confidentiality label, and an integrity label. The interface is defined below.

dictionary CILabel {
  Label? confidentiality;
  Label? integrity;
};

[Constructor(object obj, CILabel labels), Exposed=Window, Worker]
interface LabeledObject {
  readonly attribute Label confidentiality;
  readonly attribute Label integrity;

  [GetterThrows] readonly attribute object protectedObject;

  [Throws] LabeledObject clone(CILabel labels);
};

3.4.1. Constructors

LabeledObject(obj, labels)

When invoking the LabeledObject() constructor, the user agent MUST use an algorithm equivalent to the following:

1. Let obj clone be the result of obtaining a structured clone of the obj argument.

2. Let conf be the confidentiality member of the labels argument, if it is set. Otherwise, let conf be the current confidentiality label.

3. Let int be the integrity member of the labels parameter, if it is set. Otherwise, let int be the current integrity label.

4. Let canWrite be the result of invoking the write check algorithm with the conf and int labels.

5. If canWrite is false, the constructor MUST throw a SecurityError exception and terminate this algorithm.

6. Else, the user agent MUST return a new LabeledObject, with the protected object set to obj clone, the confidentiality label set to conf, and the integrity label set to int.

3.4.2. Attributes

confidentiality, of type Label, readonly

On getting, the user agent MUST return the LabeledObject’s confidentiality label.

integrity, of type Label, readonly

On getting, the user agent MUST return the LabeledObject’s integrity label.

protectedObject, of type object, readonly

On getting, the user agent MUST use an algorithm equivalent to the following:

1. Invoke the context tainting algorithm with the LabeledObject’s confidentiality and integrity labels.

2. Return LabeledObject’s protected object.

3.4.3. Methods

clone(CILabel labels)

On invocation, the user agent MUST use an algorithm equivalent to the following:

1. Let obj be the protected object of the object on which the method was invoked.

2. Let conf be the confidentiality label of the object on which the method was invoked.

3. Let int be the integrity label of the object on which the method was invoked.

4. Let newConf be the confidentiality member of the labels argument, if it is set. Otherwise, let newConf be conf.

5. Let newInt be the integrity member of the labels parameter, if it is set. Otherwise, let newInt be int.

6. Let privs be the internal privilege label of the current context privileges.

7. If newConf.subsumes(conf, privs) returns false or if int.subsumes(newInt, privs) returns false, the method MUST throw a SecurityError exception and terminate this algorithm.

   Note, these checks ensure that the new labels of the object are at least as restricting as the original labels, taking into consideration the privileges of the context.

8. Else, return a new LabeledObject, with the protected object set to obj, the confidentiality label set to newConf, and the integrity label set to newInt.

3.4.4. Examples

// Fetch map for provided location and draw it
mapsIframe.postMessage({ cmd: 'draw', location: ... }, mapsOrigin);

var locations = ... // Array of police-car coordinates

// Label the locations:
var labeledLocations = new LabeledObject(locations,
                             { confidentiality: new Label(window.location.origin) });

// Send the labeled locations and plot them
mapsIframe.postMessage({ cmd: 'plot', locations: labeledLocations }, mapsOrigin);

window.addEventListener("message", function (event) {
  switch (event.data.cmd) {
    case 'plot':
      var coordinates = event.data.locations.protectedObject;
      coordinates.forEach(function (coordinate) {
        // add car to map at coordinate
      });
    case 'zoom': ...
    case 'move': ...
    ...
  };
}, false);

function handler(lObj) {
  if (validateA(lObj.protectedObject)) {
    var origin = ... ; // current origin (e.g., window.location.origin)
    var endorsement = new Label(origin)._or('cowl://validate-A');
    // Return a clone of the labeled object that is additionally
    // endorsed by the current (sub-)origin.
    return lObj.clone({ integrity: lObj.integrity.and(endorsement) });
  } else {
    return null;
  }
}

3.5. The Sec-COWL HTTP Headers

The Sec-COWL HTTP request and response headers are used by user agents and servers to convey label metadata to servers and user agents, respectively.

Label metadata is either labeled context metadata or labeled data metadata.

Labeled context metadata encodes COWL state information, including:

• the serialized context confidentiality label given by the ctx-confidentiality directive,

• the serialized context integrity label given by the ctx-integrity directive, and

• the serialized context privilege’s internal privilege label given by the ctx-privilege directive.

Its ABNF is:

ctx-metadata        = ctx-directive *( ";" [ ctx-directive ] )
ctx-directive       = *WSP ctx-directive-name 1*WSP label-set
ctx-directive-name  = "ctx-confidentiality" / "ctx-integrity" / "ctx-privilege"

Labeled data metadata is used to convey the confidentiality and integrity labels of an HTTP request or response, using the data-confidentiality and data-integrity directives. Its ABNF is:

data-metadata       = data-directive *( ";" [ data-directive ] )
data-directive      = *WSP data-directive-name 1*WSP label-set
data-directive-name = "data-confidentiality" / "data-integrity"

The ABNF for serialized labels is:

label-set           = "[" disjunction-set *( "," [ disjunction-set ] ) "]" / empty-label
disjunction-set     = "[" [ source-expression *( "," [ source-expression ] ) ] "]"
source-expression   = "'self'" / host-source
empty-label         = "[" *WSP "[" *WSP "]" *WSP "]"

The parsing algorithms for label metadata are given in §4.10 Parse labeled data metadata and §4.11 Parse labeled context metadata.

"Sec-COWL:" ( ctx-metadata [ "," data-metadata ] ) /
            ( data-metadata [ "," ctx-metadata ] )

Sec-COWL: ctx-confidentiality [ ['https://b.com'] ];
          ctx-integrity [ [] ];
          ctx-privilege [ ['https://a.com'] ];

Sec-COWL: ctx-confidentiality [ [] ];
          ctx-integrity [ [] ];
          ctx-privilege [ ['http://university.edu', 'cowl://user1'], ['cowl://a0281e1f-8412-4068-a7ed-e3f234d7fd5a'] ];

"Sec-COWL:" ctx-metadata / data-metadata

Sec-COWL: ctx-privilege [ ['self', 'cowl://user1'] ];

Sec-COWL: data-confidentiality [ ['https://a.com'], ['https://b.com'] ];
          data-integrity [ ['https://a.com'] ];

3.6. Extensions to XMLHttpRequest

The XMLHttpRequest specification SHOULD contain the modifications described below to enable the rest of this specification’s work [XHR].

3.6.1. Sending labeled objects

partial interface XMLHttpRequest {
  void send(LabeledObject lobj);
};

The send(lobj) method MUST use an algorithm that is equivalent to the following:

1. Let obj be the protected object of the lobj argument.

2. Let conf be the confidentiality label of the lobj argument.

3. Let int be the integrity label of the lobj argument.

4. Let privs be the current context privileges.

5. Let remoteConf be the label returned by the Label(origin) constructor called with the url associated with the request.

6. If responseConf.subsumes(conf, privs) returns false, throw a SecurityError and terminate this algorithm.

   The user agent SHOULD warn the user that the script attempted to leak data to a remote server.

7. Let json be a new JSON object with the following entries:

   • "confidentiality" set to conf.toJSON().

   • "integrity" set to int.toJSON().

   • "object" set to obj.

8. Set the Content-Type header to `application/labeled-json`.

9. Append a header named Sec-COWL to the author request headers associated with the object this methods was called on. The value of the Sec-COWL header MUST be labeled data metadata containing the confidentiality and integrity labels of the lobj argument.

10. Invoke the send() method on the object this method was called on with json as an argument.

    Note, that send() throws an exception in step 4 if obj cannot be serialized. User agents MUST ensure that all protected objects can be serialized at the time of creating LabeledObjects.

    This algorithm does not check if the integrity label of the object subsumes the server’s integrity label. It is the server’s responsibility to ensure that untrustworthy data does not affect its computation in an unsafe way. Indeed, the only reason for checking the confidentiality labels is because the user agent has no way to ensure that the server will respect the confidentiality of the data.

3.6.1.1. Examples

// Suppose that labeledObject is a public, high-integrity value:
JSON.stringify(labeledObject.confidentiality) === '[[]]';
JSON.stringify(labeledObject.integrity) === '[["https://validator.com"]]';

// Create an XHR request:
var req = new XMLHttpRequest()
req.open("POST", "https://example.com/...");

// Send the labeled object:
req.send(labeledObject);

Sec-COWL: ctx-confidentiality [[]];
          ctx-integrity [[]];
          ctx-privilege [["https://example.com"]];
Sec-COWL: data-confidentiality [[]];
          data-integrity [["https://validator.com"]];
Content-Type: application/labeled-json;

{
  "confidentiality": [[]],
  "integrity": [["https://validator.com"]],
  "object": ...
}

3.6.2. Receiving labeled objects

1. The XMLHttpRequestResponseType enumeration is extended with a new response type:

   enum XMLHttpRequestResponseType {
     // ... existing response types ...
     "labeled-json"
   };
   

2. The Response body section of the specification is modified to add:

   1. An XMLHttpRequest has associated response LabeledObject object.

   2. A labeled JSON response is the return value of these steps:

      1. If the response LabeledObject object is non-null, return it.

      2. If responseType is not "labeled-json" or the final MIME type is not application/labeled-json, return null.

      3. Let bytes be the response’s body.

      4. If bytes is null, return null.

      5. Let JSON text be the result of running utf-8 decode on byte stream bytes.

      6. Let JSON object be the result of invoking the initial value of the parse property of the JSON object, with JSON text as its only argument. If that threw an exception, return null. [ECMA-262]

      7. If the JSON object is missing any of the three entries: "object", "confidentiality", or "integrity" return null.

      8. Let protected object be the value of the "object" entry.

      9. Let self be the url associated with the response.

      10. Let conf be the label returned by calling the fromJSON() function with the "confidentiality" entry of the JSON object and self. If the function threw an exception, return null.

      11. Let int be the label returned by calling the fromJSON() function with the "integrity" entry of the JSON object and self. If the function threw an exception, return null.

      12. Let responseInt be the label returned by the Label(origin) constructor called with self.

      13. If responseInt does not subsume int, return null.

          Should the user agent warn the user if the server provided an integrity label that it is not allowed to provide?

      14. Set the labeled JSON response to a newly created LabeledObject whose protected object is protected object, confidentiality label is conf, and integrity label is int.

      15. Return the labeled JSON response.

3. Modify the response attribute by adding the following clause to step 2 of the ↪ Otherwise clause:

   ↪ If responseType is "labeled-json"

   Return the labeled JSON response.

4. Modify step 12 of the open() method by adding the following sub-step:

   • Set response LabeledObject object to null.

3.6.2.1. Examples

Access-Control-Allow-Origin: https://mashup.com
Content-Type: application/labeled-json;

{
  "confidentiality": [[]],
  "integrity": [["https://provider.com"]],
  "object": ...
}

// Create an XHR request to get the data:
var req = new XMLHttpRequest()
req.open("GET", "https://provider.com/apis/...");
req.responseType = "labeled-json";
req.onload = function (e) {
  var labeledObject = req.response; // is a LabeledObject

  // At this point, the context is still untainted, but:
  JSON.stringify(labeledObject.confidentiality) === '[[]]';
  JSON.stringify(labeledObject.integrity) === '[["https://provider.com"]]';
};
req.send();

Access-Control-Allow-Origin: *
Content-Type: application/labeled-json;

{
  "confidentiality": [["'unique'"]],
  "integrity": [[]],
  "object": ... base64-encoded image ...
}

3.7. Confinement Enforcement

This sub-section is non-normative

To enforce confinement, COWL ensures that code in a context cannot send data (e.g., via cross-document messaging or by performing a fetch) to contexts or servers that do not preserve the confidentiality of the data. Similarly, COWL ensures that a context cannot receive data from a context or server that is less trustworthy.

3.7.1. Modifications to Fetch

The Fetch specification SHOULD contain the following modifications in order to enable the rest of this specification’s work [FETCH]:

1. Perform the following step between step 4 and 5 in the "main fetch" algorithm:

   1. If should fetching request be blocked as COWL returns blocked, set response to a network error.

2. Perform the following step between step 12 and 13 in the "main fetch" algorithm:

   1. If process response to request as COWL returns blocked, set response to a network error.

3.7.2. Modifications to Web Messaging

The Web Messaging specification SHOULD contain the following modifications in order to enable the rest of this specification’s work [WEBMESSAGING]:

1. Perform the following step between step 9 and 10 in the posting messages algorithm:

   1. Let conf be the current context’s effective confidentiality label.

   2. Let int be the current context’s effective integrity label.

   3. Let dstState be the COWL state associated with the Document of the Window object on which the method was invoked.

   4. If confinement mode for dstState is enabled, let dstConf be the dstState effective confidentiality label.

   5. Else, let dstConf be the Label returned by the label upgrade algorithm when invoked with the dstState context confidentiality label and context privilege.

      Note, if the receiver has not enabled confinement mode, COWL flexibly assumes that it can receive data sensitive to its origin (in using the label upgrade).

   6. Let dstInt be the dstState effective integrity label.

   7. If dstConf does not subsume conf or if int does not subsume dstInt, then abort the remaining steps silently.

2. Perform the following step between step 9 and 10 in the MessagePort postMessage() method:

   1. Let conf be the current context’s effective confidentiality label.

   2. Let int be the current context’s effective integrity label.

   3. Let dstState be the COWL state associated with the owner of the target port the Message Port postMessage() was called on.

   4. If confinement mode for dstState is enabled, let dstConf be the dstState effective confidentiality label.

   5. Else, let dstConf be the Label returned by the label upgrade algorithm when invoked with the dstState context confidentiality label and context privilege.

      Note, if the receiver has not enabled confinement mode, COWL flexibly assumes that it can receive data sensitive to its origin (in using the label upgrade).

   6. Let dstInt be the state effective integrity label.

   7. If dstConf does not subsume conf or if int does not subsume dstInt, then abort the remaining steps.

3.7.3. Modifications to HTML5

When confinement mode is enabled the user agent MUST ensure that content cannot access other content from the same origin (e.g., using an iframe’s contentDocument) that would violate label restrictions. Specifically, if a browsing context’s confinement mode is enabled the user agent MUST set the following flags of the context’s active sandboxing flag set:

• The sandboxed plugins browsing context flag.

• The sandboxed document.domain browsing context flag.

If the context’s effective confidentiality label or integrity label are not the empty label, the user agent MUST additionally set the following flags:

• The sandboxed origin browsing context flag. This flag ensures that the browsing context cannot access content of (what was previously) the same origin. It also prevents script from reading from or writing to the document.cookie IDL attribute, and blocks access to localStorage. [WEBSTORAGE]

  The user agent MUST ensure that if content has access to another content from the same origin, but either ends up enabling confinement mode and has a non-empty label, access must be revoked and the two must be considered as if they are of different origins. Th current version of this document specifies this requirement in terms of the sandboxed origin browsing context flag.

  Implementation-wise, this may pose a challenge for certain browsers. An alternative design may disallow enabling confinement mode if the browsing context has any references to or from another same-origin content. Feedback on this would be very welcome.

• The sandboxed navigation browsing context flag.

Should COWL restrict communication via less overt channels (e.g., height/width of an iframe, URL fragment, or even)index in window.top.frames)? Maybe as optional modifications to HTML? Feedback on this would be very welcome.

4.1. Label Normal Form Reduction

1. Let lset be the label set of an empty label.

2. For each disjunction set dset in the label set of label:

   1. If there is no disjunction set in lset that is a subset of dset, then:

      1. Remove every disjunction set in lset that dset is a subset of.

      2. Add dset to lset.

3. Return a newly created Label whose label set is lset.

Note, this algorithms assumes that disjunction sets and label sets do not have duplicate elements, much like mathematical sets.

var a    = Label("https://a.com");  // https://a.com
var aORb = Label("https://a.com")._or("https://b.com"); // https://a.com OR https://b.com
var a2   = a.and(aORb); // https://a.com AND (https://a.com OR https://b.com) ≡ https://a.com

JSON.stringify(a2) === '[["https://a.com"]]';
a2.equals(a);

4.2. Label Subsumption

1. If, for each disjunction set b in the label set of B there is disjunction set a in the label set of A such that a is a subset of b, return true.

1. Else, return false.

Note, when interpreting labels as mathematical formulae, label subsumption is logical implication: A subsumes B is equivalent as A implies B, i.e, A⇒B.

4.3. Label Downgrade

1. Let privLabel be the internal privilege label of priv.

2. Let lset be the label set of an empty label.

3. For each disjunction set dset in the label set of label:

   1. Let cur be a newly create Label whose label set is dset.

   2. If privLabel does not subsume cur, add dset to lset.

4. Return a newly created Label whose label set is lset.

Note, label downgrade removes every disjunction set permitted by priv. This is used to safely declassify data labeled label.

4.4. Label Upgrade

1. Let privLabel be the internal privilege label of priv.

2. Return label.and(privLabel).

Note, label upgrade is the dual of label downgrade. This can be used to safely endorse data labeled label (and thus potentially already endorsed).

4.5. Context Tainting

1. Let currentConf be the current context confidentiality label.

2. Let currentInt be the current context integrity label.

3. Set the context confidentiality label to the Label returned by the by the label downgrade algorithm when invoked with currentConf.and(confidentiality) and current privilege.

4. Set the context integrity label to the Label returned by the by the label downgrade algorithm when invoked with currentInt._or(integrity) and current privilege.

4.6. Write Check

1. Let currentConf be the current context’s effective confidentiality label.

2. Let currentInt be the current context’s effective integrity label.

3. If objConf does not subsume currentConf or if currentInt does not subsumes objInt, return false.

4. Else, return true.

4.7. Structured Cloning

1. Let input be the value being cloned.

2. If input is a Label object, let output be a newly constructed Label object with the same label set as that of input.

3. If input is a Privilege object that was constructed with the FreshPrivilege() constructor, let output be a newly constructed Privilege object with the same internal privilege label as that of input.

   To prevent attacks that launder page privileges, the current version of COWL only allows transferring fresh privileges.

   We can be more permissive and allow transferring all but default privileges. Feedback on this would be welcome.

4. If input is a LabeledObject object, let output be a newly constructed LabeledObject object with the same internal protected object, confidentiality label, and integrity label as that of input.

5. Return output.

Note, cross-context messaging constructs such as postMessage() use the structured clone algorithm (e.g., see the internal structured cloning algorithm). This algorithm is used to allow authors to transfer COWL object, such as LabeledObjects, to other contexts.

4.8. Should fetching request be blocked as COWL?

Given a Request request, a user agent determines whether the Request request should proceed or not via the following algorithm:

1. Let context be the client associated with the request.

2. If context is null, let context be the incumbent settings object.

   Note, the client associated with the request is null when navigating, so we use the incumbent settings object to get the COWL state of the context that initiated the request.

3. Let state be the COWL state retrieved via the environment settings object context.

4. If the state confinement mode is not enabled, return allowed and terminated this algorithm.

5. Let conf be the state effective confidentiality label.

6. Let dstConf be the Label created by invoking the Label(origin) constructor with the url associated with the request.

7. If dstConf subsumes conf, return allowed.

8. Else:

   1. If the request is a navigation request and the context is a top-level browsing context, the user agent MAY return allowed, but MUST indicate to the user that data labeled conf may have been leaked due to the navigation. It is RECOMMENDED that user agents give users the options to block the navigation, e.g., via a pop-up dialog.

      We can simply disallow leaks via top-level navigation at the cost of potentially forcing users to navigate away by closing tabs or inputting another URL via the address bar. Feedback on this would be welcome.

   2. Else, return blocked.

Note, the integrity label of the current context is not used in this algorithm since, conceptually, the integrity label of a server is the empty label and, thus, always subsumed. Server operators SHOULD check the Sec-COWL request header to ensure untrustworthy data does not affect the computation in an unsafe way.

4.9. Process response to request as COWL

Given a Request request and Response response, a user agent determines whether the response should be returned via the following algorithm:

1. If the response’s header list has no header whose name is Sec-COWL, return allowed and terminate this algorithm.

2. Let destination be the request’s destination.

3. Let type be the request’s type.

4. Let MIMEType be the result of extracting a MIME type from response’s header list.

5. Let context be the client associated with the request.

6. If context is null, let context be the incumbent settings object.

   Note, the client associated with the request is null when navigating, so we use the incumbent settings object to get or set the COWL state of the context that initiated the request.

7. Let state be the COWL state retrieved via the environment settings object context.

8. Let metadata be the first header whose name is Sec-COWL in the response’s header list.

9. If destination is "document", "worker" or "serviceworker":

   1. Let self be the serialization of the origin retrieved via the environment settings object context.

   2. Let conf, int, priv be the result of calling the parse labeled context metadata algorithm with metadata and self.

   3. If either conf, int, or priv are null, return blocked.

   4. Else:

      1. Set the state context confidentiality label to conf.

      2. Set the state context integrity label to int, if the state effective integrity label subsumes int.

         Note, by performing the label subsumption check before setting the context privilege (next step), the context integrity label can be upgraded from the empty label, while allowing the context privilege to also be dropped.

         Should the user agent warn the user if the server provided an integrity label that it is not allowed to provide?

      3. Set the state context privilege to priv, if priv is a delegated privilege of the state context privilege.

         Should the user agent warn the user if the server provided a privilege that it is not allowed to provide?

      4. Enable confinement mode for state.

      5. Return allowed.

10. Else:

    1. Let self be the url associated with the response.

    2. Let conf and int be the results of calling the parse labeled data metadata with metadata and self.

    3. If either conf or int is null, return blocked and terminate this algorithm.

    4. If the state effective confidentiality label subsumes conf and int subsumes the state effective integrity label, return allowed.

    5. Else, return blocked.

       Note, COWL conservatively blocks a response that is potentially more confidential or less trustworthy than the context making the request. In future versions of COWL, certain responses (e.g., images) which are only not as trustworthy as the context integrity label may be allowed by the user agent.

4.10. Parse labeled data metadata

To parse labeled data metadata metadata for origin self, the user agent MUST use an algorithm equivalent to the following:

1. Let conf be null.

2. Let int be null.

3. For each non-empty token returned by strictly splitting the string metadata on the character U+003B SEMICOLON (;):

   1. Skip whitespace.

   2. Collect a sequence of characters that are not space characters. The collected characters are the directive name.

   3. If there are characters remaining in token, skip ahead exactly one character (which must be a space character).

   4. The remaining characters in token (if any) are the directive value.

   5. Let label value be the label returned by calling the fromJSON() function with the directive value and self. If the function threw an exception, ignore this instance of the directive and continue to the next token.

   6. If directive name is data-confidentiality and conf is null, let conf be label value.

   7. Else, if directive name is data-integrity and int is null, let int be label value.

   8. Else, ignore this instance of the directive and continue to the next token.

4. Return conf and int.

4.11. Parse labeled context metadata

To parse labeled context metadata metadata for origin self, the user agent MUST use an algorithm equivalent to the following:

1. Let conf be null.

2. Let int be null.

3. Let priv be null.

4. For each non-empty token returned by strictly splitting the string metadata on the character U+003B SEMICOLON (;):

   1. Skip whitespace.

   2. Collect a sequence of characters that are not space characters. The collected characters are the directive name.

   3. If there are characters remaining in token, skip ahead exactly one character (which must be a space character).

   4. The remaining characters in token (if any) are the directive value.

   5. Let label value be the label returned by calling the fromJSON() function with the directive value and self. If the function threw an exception, ignore this instance of the directive and continue to the next token.

   6. If directive name is ctx-confidentiality and conf is null, let conf be label value.

   7. Else, if directive name is ctx-integrity and int is null, let int be label value.

   8. Else, if directive name is ctx-privilege and priv is null, let priv be a newly created privilege whose internal privilege label is set to label value.

   9. Else, ignore this instance of the directive and continue to the next token.

5. Return conf, int, and priv.