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 cowl 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 once they have access to it, in the browser. To do so, the perator sends a response header field named Sec-COWL (described in §3.5.2 Sec-COWL in HTTP Responses) 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 the 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' OR app: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 dropping privileges (from the context’s default privilege) and then loading the untrusted library. In dropping privileges, the content (and untrusted 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 'none'

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. Security Considerations

1.3.1. Information leakage via covert channels

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.

1.3.2. Defense in depth

1.4. Privacy Considerations

1.4.1. Encoding information in labels

1.4.2. Using labels to enhance privacy

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

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

[Constructor, Constructor(DOMString principal), 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);

  stringifier;
};

3.1.1. Constructors

Label()

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

Label(DOMString principal)

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

1. If the principal argument is not a principal, 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 principal corresponding to the principal argument.

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.

3.1.3. Serializing labels

The stringification behavior MUST return the serialization of the label, which adheres to the label-expression grammar, using an algorithm equivalent to the following:

1. Let label be the label being serialized.

2. If label is the empty label, return "'none'" and terminate this algorithm.

3. Let result be the empty string.

4. For each element dset in the label’s label set:

   1. If result is not the empty string, append the characters " AND " to it.

   2. If the number of elements in dset is greater than 1:

      1. Append the character "(" (U+0028) to result.

      2. Append the character " " (U+0020) to result.

   3. Let o be the empty string.

   4. For each element prin in the disjunction set dset:

      1. If o is not the empty string, append the characters " OR " to it.

      2. Append prin to o.

   5. Append o to result.

   6. If the number of elements in dset is greater than 1:

      1. Append the character " " (U+0020) to result.

      2. Append the character ")" (U+0029) to result.

3.1.4. 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");

empty.toString()    === "'none'";
a.toString()        === "https://a.com";
aANDb.toString()    === "(https://a.com) AND (https://b.com)";
aORb.toString()     === "https://a.com OR https://b.com";
aORbANDc.toString() === "(https://a.com OR https://b.com) AND (https://c.com)";

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), SecureContext]
interface Privilege {
  static Privilege FreshPrivilege(); // Named constructor
  Label asLabel();

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

3.2.1. Constructors

Privilege()

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

FreshPrivilege()

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

1. Let unique principal be a freshly generated unique principal.

2. Let unique label be the label produced by invoking the Label(principal) constructor with unique principal.

3. 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("app:user1"); // Here the app:user1 is an application-specific princial

// 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 with a COWL state, which is used to restrict the context’s communication channels. 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.

  A context is considered a confined context if its confinement mode status is set, and a unconfined context otherwise.

  Note: confinement mode is currently only be enabled for contexts instantiated in cowl iframes. In future versions we may generalize the enforcement to other browsing contexts and Workers.

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

COWL restricts the code running in a confined context from communicating with other contexts or remote servers in a way that preserves confidentiality and integrity (see §3.7 Confinement Enforcement).

In general, COWL does not restrict code running in unconfined contexts from communicating with other unconfined contexts or remote servers. To preserve this invariant COWL does, however, prevent such code from reading overly sensitive data (i.e., data that would taint the context) or communicating with certain confined contexts and COWL-enabled servers.

Note: the COWL state of an unconfined context does not change from its original default COWL state.

The COWL state is exposed to confined contexts via the COWL interface defined below. This interface MUST not be exposed to unconfined contexts.

[SecureContext, COWLContext]
interface COWL {
  [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. Let conf be the set confidentiality label.

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

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

  4. 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. Let int be the set integrity label.

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

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

  4. 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 use an algorithm equivalent to the following:

  1. Let priv be the set privilege.

  2. Set the current privilege to priv.

3.3.2. Examples

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() and XMLHttpRequest (e.g., with an overloaded send() method for LabeledObject arguments). It SHOULD be exposed to both confined contexts and unconfined contexts.

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), SecureContext]
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 labels be the labels argument if it provided, otherwise an empty object with no members.

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

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

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

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

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

should protectedObject be a promise? Otherwise we may be a bit too inflexible.

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

1. If the current settings object is not a secure context, then the user agent MUST throw a SecurityError exception and terminnate this algorithm.

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

3. If the tainting algorithm raised an exception, re-throw the exception and terminate this algorithm.

   The tainting algorithm fails if code in a unconfined context tries to read data that should confine the context. To make it easier for developers to debug such cases, the user agent SHOULD report a message to inform developers that they can create cowl iframes wherein they can inspect such sensitive objects instead.

4. Else, return the LabeledObject’s protected object.

3.4.3. Methods

clone(CILabel labels)

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

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

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

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

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

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

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

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

7. 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 (as being sensitive to the police origin):
var labeledLocations = new LabeledObject(locations,
                             { confidentiality: new Label(window.location.origin) });

// Send the labeled locations to the map iframe to 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 (isValidEmail(lObj.protectedObject)) {
    var origin = window.location.origin;
    // Endorse with application-specific label: ' OR app:isValidEmail'
    var endorsement = new Label(origin).or('app:isValidEmail');
    // Return a clone of the labeled object that is additionally
    // endorsed by the validator’s (sub-)origin.
    return lObj.clone({ integrity: lObj.integrity.and(endorsement) });
  } else {
    return null;
  }
}

3.5. The Sec-COWL HTTP Header Field

The Sec-COWL HTTP header field is used to convey label metadata.

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-expression
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-expression
data-directive-name = "data-confidentiality" / "data-integrity"

The ABNF for serialized labels is:

label-expression   = empty-label / and-expression / or-expression / principal-expression
and-expression     = *WSP "(" or-expression *WSP ")" *( 1*WSP "AND" WSP and-expression )
or-expression      = *WSP principal-expression *( 1*WSP "OR" WSP or-expression ) 
empty-label        = "'none'"

Note, the ABNF grammar limits the expression of labels to conjunctions of disjunctions, even though the JavaScript API allows AND’s and OR’s to be used interchangably. This is done to simplify auditing of declarative (header) labels, but may be changed in future versions to be more flexible.

The ABNF for serialized principals is:

principal-expression        = origin-principal-expression 
                            / app-principal-expression 
                            / unique-principal-expression
origin-principal-expression = "'self'" / host-source
app-principal-expression    = "app:" 1*( ALPHA / DIGIT / "-" )
unique-principal-expression = "unique:" UUID

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 'none';
          ctx-privilege https://a.com

Sec-COWL: ctx-confidentiality 'none';
          ctx-integrity 'none';
          ctx-privilege (https://university.edu OR app:user1) AND (unique:a0281e1f-8412-4068-a7ed-e3f234d7fd5a)

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

Sec-COWL: ctx-privilege 'self' OR app:user1;

Sec-COWL: data-confidentiality 'self' AND https://b.com;
          data-integrity 'self'

3.6. Extensions to XMLHttpRequest

should we disable XHR and just force developers to use fetch?

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(principal) constructor called with the stringified origin url associated with the request.

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

   The user agent SHOULD report a warning that the context attempted to leak data to a remote server.

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

   • "confidentiality" set to the serialized conf.

   • "integrity" set to the the serialized int.

   • "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 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:
labeledObject.confidentiality.toString() === "'none'";
labeledObject.integrity.toString() === "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 'none';
          ctx-integrity 'none';
          ctx-privilege https://example.com
Sec-COWL: data-confidentiality 'none';
          data-integrity https://validator.com
Content-Type: application/labeled-json;

{
  "confidentiality": "'none'",
  "integrity": "https://validator.com",
  "object": ... JSON 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 invoking the §4.12 Parse label expression algorithm with the "confidentiality" entry of the JSON object and self. If parsing failed, return null.

      11. Let int be the label returned by invoking the §4.12 Parse label expression algorithm with the "integrity" entry of the JSON object and self. If parsing failed, return null.

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

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

          The user agent SHOULD report a warning message indicating that the server provided an integrity label that it is not allowed to provide.

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

      15. Return the response LabeledObject object.

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": "'self'",
  "integrity": "'self'",
  "object": ... JSON 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:
  labeledObject.confidentiality.toString() === "https://provider.com";
  labeledObject.integrity.toString() ===  "https://provider.com";
};
req.send();

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

{
  "confidentiality": app:too-secret,
  "integrity": 'none',
  "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 5 and 6 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 13 and 14 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. Let dstConf be the Label returned by the label upgrade algorithm when invoked with the dstState context confidentiality label and context privilege.

      Note, in using the label upgrade COWL flexibly assumes that receivers wish to receive data potentially sensitive to their origin (really data they can declassify with their privileges).

   5. Let dstInt be the dstState context integrity label.

   6. 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. Else, let dstConf be the Label returned by the label upgrade algorithm when invoked with the dstState context confidentiality label and context privilege.

      Note, in using the label upgrade COWL flexibly assumes that receivers wish to receive data potentially sensitive to their origin (really data they can declassify with their privileges).

   5. Let dstInt be the dstState context integrity label.

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

3.7.3. Modifications to HTML5

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

1. To allow authors to create confined contexts this this specification extends the HTMLIFrameElement interface with a new cowl attribute:

   partial interface HTMLIFrameElement {
     attribute boolean cowl;
   };
   

   The cowl attribute, when specified, enables a set of extra restrictions on any content hosted by the iframe, much like the sandbox attribute. We call an iframe with the cowl attribute set a cowl iframe.

   When an iframe element with a cowl attribute has its nested browsing context created (before the initial about:blank Document is created), the user agent MUST enable the context’s confinement mode. The iframe element’s cowl attribute may not be set or changed after this point.

   what’s the best way to deal with authors modifying the cowl attribute?

2. 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) or use otherwise unsafe APIs 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 document.domain browsing context flag.

   • The sandboxed origin browsing context flag.

     Note, this flag is used to ensure that the browsing context cannot directly access content of the same origin. It also prevents script from reading from or writing to the document.cookie IDL attribute, and blocks access to localStorage. [WEBSTORAGE]

     is there a better way for us to just disallow direct DOM access and preserve same-origin?

   • The sandboxed navigation browsing context flag.

   • The sandboxed auxiliary navigation browsing context flag.

   • The sandboxed top-level navigation browsing context flag.

   In addition to these flags, the user agent MUST set a container policy of the cowl iframe that contains the confined context that disables the following features:

   • Workers: Web Workers, Shared Workers, Service Workers

   • Communication: Web Sockets, Server-sent events, channel messaging, broadcast channels and WebRTC

   • Storage: document.cookie, localStorage, IndexedDB

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

a2.toString() === "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.

2. 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 created 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. Let newConf be the Label returned by the by the label downgrade algorithm when invoked with currentConf.and(confidentiality) and current privilege.

4. Let newInt be the Label returned by the label downgrade algorithm when invoked with currentInt.or(integrity) and current privilege.

5. If the current context is an unconfined context and either newConf or newInt are not the empty label, throw a SecurityError exception and terminate this algorithm.

6. Set the context confidentiality label to newConf.

7. Set the context integrity label to newInt.

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 subsume 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, then:

   1. If the input’s internal privilege label subsumes any label whose label set is a singleton origin principal, let output be null.

   2. Else, let output be a newly constructed Privilege object with the same internal privilege label as that of input.

   To prevent attacks that launder default privileges, the current version of COWL only allows transferring weaker delegated privileges or privileges constructed with FreshPrivilege(). The first step above ensures this by setting the output to null if the privilege subsumes any privilege corresponding to an origin principal.

4. If input is a LabeledObject object, let output be a newly constructed LabeledObject object whose confidentiality and integrity labels are the same as that of input, and whose internal protected object is a structured clone of the protected object of the input LabeledObject.

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 terminate this algorithm.

5. Let conf be the state effective confidentiality label.

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

7. If dstConf subsumes conf, return allowed.

8. Else, return blocked.

   The user agent SHOULD report a warning that the context attempted to leak data to a remote server.

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 context be the client associated with the request.

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

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

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

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

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

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

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

      The user agent SHOULD report a warning that the server supplied a malformed Sec-COWL header.

   3. Else:

      1. If context is an unconfined context, return blocked and terminate this algorithm.

         The user agent SHOULD report a warning that the application attempted to embed confined content outside a cowl iframe.

      2. If priv is not a delegated privilege of the state context privilege, return blocked and terminate this algorithm.

         The user agent SHOULD report a warning that the server supplied a privilege that it is not trusted for.

      3. If the state effective integrity label does not subsume int, return blocked and terminate this algorithm.

         The user agent SHOULD report a warning that the server supplied an integrity label that it is not trusted for.

      4. Set the state context confidentiality label to conf.

      5. Set the state context integrity label to int.

         Note, by performing the label subsumption check (step 3 above) 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.

      6. Set the state context privilege to priv.

      7. Return allowed.

8. Else:

   1. Let self be the origin of 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.

      The user agent SHOULD report a warning that the server supplied a malformed Sec-COWL header.

   4. Let effConf be the Label returned by the label downgrade algorithm when invoked with conf and the state current privilege.

      Note, effConf is the effective confidentiality label of the response—COWL flexibly declassifies responses (as much as the current privilege permits).

   5. If the state context confidentiality label subsumes effConf and int subsumes the state effective integrity label, return allowed.

   6. 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 invoking the parse label-expression algorithm with the directive value and self. If parsing failed, terminate the rest of these sub-steps.

      The user agent SHOULD report a warning that the server provided a malformed label directive.

   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, terminate the rest of these sub-steps.

      The user agent SHOULD report a warning that the server provided a malformed label directive.

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 invoking the parse label-expression algorithm with the directive value and self. If parsing failed, terminate the rest of these sub-steps.

      The user agent SHOULD report a warning that the server provided a malformed label directive.

   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, terminate the rest of these sub-steps.

      The user agent SHOULD report a warning that the server provided a malformed label directive.

5. Return conf, int, and priv.

4.12. Parse label expression

The parse label-expression algorithm takes a input representing a label-expression and a stringified origin URL self and returns the parsed Label. If at any point the algorithm says that it "fails", this means that it is aborted at that point and returns nothing. The user agent MUST use an algorithm equivalent to the following:

1. Let label be a new empty label.

2. If input is not a string, fail.

3. Strip and collapse whitespace from input.

4. Let AND expr be the remaining characters in input.

5. If AND expr is the string "'none'", return label and terminate this algorithm.

6. Split the AND expr string on "AND". Let AND tokens be the resulting list of tokens, if the splitting didn’t fail. Otherwise, fail.

7. For each token in AND tokens, run the following sub-steps:

   1. Let input be the token.

   2. If the number of elements in AND tokens is greater than 1:

      1. If first character of input is not "(" (UA+0028), fail.

      2. If last character of input is not ")" (UA+0029), fail.

      3. Remove the first and last characters from input.

   3. Else, if first character of input is "(" (UA+0028) or if last character of input is ")" (UA+0029):

      1. If first character of input is not "(" (UA+0028), fail.

      2. If last character of input is not ")" (UA+0029), fail.

      3. Remove the first and last characters from input.

   4. Let OR expr be the remaining characters in input.

   5. Let orExp be a new empty label.

   6. Split the string OR expr on "OR". Let OR tokens be the resulting list of tokens, if the splitting didn’t fail. Otherwise, fail.

   7. For each token in OR tokens, run the following sub-steps:

      1. Let prin be the token.

      2. If prin is the string "'self'", set prin be self.

      3. Set orExp to orExp.or(prin), if calling the or method didn’t throw an exception. Otherwise, fail.

         Note, the method throws an exception if prin is not a principal. Hence, this algorithm should fail.

   8. Set label to label.and(orExp).

8. Return label.

When a user agent has to split a string on particular delimiter characters delimiter, it MUST use an algorithm equivalent to the following:

1. Let input be the string being split.

2. Let position be a pointer into input, initially pointing at the start of the string.

3. Let delimiter length be the number of characters in delimiter.

4. Let tokens be the resulting list of tokens.

5. Strip leading and trailing whitespace.

6. If input is the empty string, fail.

7. While position is not past the end of input:

   1. Let s be the empty string.

   2. Skip whitespace.

   3. Let done be false.

   4. While done is false and position is not past the end of input:

      1. Collect a sequence of characters that are not space characters. Append the resulting sequence to s.

      2. If position points past the end of input, set done to true and end these sub-steps.

      3. Collect a sequence of characters that are space characters. Let ws be the resulting sequence.

      4. If the next delimiter length characters are an ASCII case-insensitive match for the string delimiter, then set done to true and advance position by delimiter length characters.

      5. Else, append ws to s.

   5. Append s to tokens.

8. Return tokens.