Source: https://w3c.github.io/webappsec/specs/cowl/
Timestamp: 2019-04-21 02:21:37+00:00

Document:
This specification defines an API for specifying privacy and integrity policies on data, in the form of origin labels, and a mechanism for confining code according to such policies. This allows Web application authors and server operators to shared data with untrusted—buggy but not malicious—code (e.g., in a mashup scenario) yet impose restrictions on how the code can share the data further.
4.8 Should fetching request be blocked as COWL?
Mechanisms such as CORS and CSP can be used to mitigate these risks by giving authors control over whom they share data with. But, once data is shared, these mechanisms do not impose any restrictions on how the code that was granted access can further disseminate the data.
This document specifies an extension to the current model called Confinement with Origin Web Labels (COWL). COWL provides authors with APIs for specifying (mandatory) access control policies on data, including content, in terms of origin labels. These policies are enforced in a mandatory fashion, transitively, even once code has access to the data. For example, with COWL, the author of https://example.com can specify that a password is confidential to https://example.com (and thus should only be disclosed to https://example.com) before sharing it with a third-party password strength checking service. In turn, COWL ensures that the third-party service, which necessarily computes on the sensitive password, is confined and respects the policy on the password: COWL disallows it from disclosing the password to any origin other than https://example.com.
COWL enforces such policies by confining code at the context-level, according to the sensitivity (i.e., the label) of the data the code has observed. To reap the greatest benefits of COWL, authors will need to compartmentalize applications into multiple contexts (e.g., iframes).
In the existing model, any page served from an origin has the ambient, implicit authority of that origin. This documents generalizes this notion of authority and gives authors explicit control over it with privileges. For example, by default, a page whose origin is https://example.com has the privilege for https://example.com. This gives the page the authority to arbitrarily disseminate data sensitive to https://example.com; to be backwards-compatible, the page is not confined when reading data sensitive to https://example.com. However, COWL allows the author to run the page with "weaker" delegated privileges (e.g., one corresponding the current user at https://example.com) or to drop the privilege altogether.
COWL is intended to be used as a defense-in-depth mechanism that can restrict how untrusted—buggy but not malicious—code handles sensitive data. Given the complexities of browser implementations and presence of covert channels, malicious code may be able to exfiltrate data. Authors should still use discretionary access control mechanisms, such as CSP and CORS, to restrict access to the data in the first place.
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.
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.
Authors should be able to privilege separate applications by compartmentalizing them into separate contexts that have delegated privileges.
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).
// Register listener to receive a response from checker, etc.
Once the checker inspects the protected object, i.e., the password, COWL limits the iframe to communicating with origins that preserve the password’s confidentiality (in this case, https://example.com). This policy is enforced mandatorily, even if the https://untrusted.com iframe sends the password to yet another iframe.
Note, until the checker actually inspects the labeled password, it can freely communicate with any origins, e.g., with https://untrusted.com. This is important since the checker may need to fetch resources (e.g., regular expressions) to check the password strength. This is also safe—the checker has not inspected the sensitive password, and thus need not be confined.
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].
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.
COWL only allows a https://mashup.com context to read the sensitive response if the label restrictions of the response are respected, i.e., if the code can only communicate with https://provider.com.
Note, COWL only allows the code to inspect the response if the context labels, which dictate the context’s ability to communicate, are more restricting than the labels of the response. A more permissive approach, which does not require the context give up its ability to communicate arbitrarily is to use labeled JSON response. The mashup XHR example shows how authors can accomplish this.
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.
Having this privilege can be understood as having the authority of user1’s part of the https://university.edu origin. COWL ensures that the content of this user cannot interfere with the content of https://university.edu or another user e.g., user2. For example, the content cannot modify https://university.edu cookies or the DOM of another http://university.edu page.
This delegated privilege also ensures that the content cannot disseminate data sensitive to another user (e.g., user2) arbitrarily— without being confined, it can only disseminate user1’s data on http://university.edu. Of course, this requires the server operator to label sensitive data (e.g., when sending it to the user agent) appropriately (e.g., user2’s data is labeled Label("https://university.edu")._or("user2")).
Note, sub-domains should be used when possible to ensure that content is isolated using the Same-Origin Policy. But, even in such cases, COWL can provide a useful layer of defense.
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.
Note, while this ensures that the context code cannot, for instance, access the origin’s cookies, the author must still associate a confidentiality label with resources (e.g., HTTP responses) to ensure that data is properly protected.
In some cases it is useful for a particular context to have the privilege to disseminate certain category 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.
COWL provides developers with a way of imposing restrictions on how untrusted code can disseminate sensitive data. However, authors should avoid sharing sensitive data with malicious code, since such code may be able to exploit covert channels, which are present in most browsers, to leak the data. COWL can only prevent information leakage from code that (e.g., is buggy and) uses overt communication 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.
COWL should always be used as an additional layer of defense to other security mechanisms such as CSP, SRI, CORS, and iframe sandbox.
An origin label, or more succinctly a label, encodes either a confidentiality or integrity security policy as conjunctive normal form (AND’s and OR’s) formulae over origins. Labels can be associated with contexts or with structurally clonable objects.
When associated with a context, the label restricts the origins that the context can communicate with, as detailed in §3.3 Labeled Contexts.
The confidentiality label Label("https://a.com")._or("https://b.com"), when associated with a context, restricts the context to sending data to https://a.com or https://b.com, but no other origins. This context label reflects the fact the context may contain data that is sensitive to either https://a.com or https://b.com; it is thus only safe for it to communicate to these origins.
Note, because the context can communicate data to either origin, another context associated with the more restricting label Label("https://a.com") cannot send it data. Doing so would allow for data confidential to https://a.com to be leaked to https://b.com.
The integrity label Label("https://a.com").or("https://b.com"), when associated with a context, restricts the context to receiving data from (a context or server) that is at least as trustworthy as https://a.com or https://b.com. This context label ensures that the code running in the context can only be influenced by data which either https://a.com or https://b.com endorse.
When associated with an object, a confidentiality label specifies the origins to whom the object is sensitive, while an integrity label specifies the origins that endorse the object. Objects that have labels associated with them are called labeled objects. §3.4 Labeled Objects defines how labels are associated with objects.
Confidentiality: Label("https://example.com"). This label indicates that the object is sensitive to https://example.com.
Integrity: Label("https://a.com"). This label indicates that the object has been endorsed by https://a.com. If https://example.com received the message from an intermediary https://b.com context, this label reflects the fact that the object (produced by https://a.com) was not tampered.
Mathematically, a label is a conjunctive normal form formula over origins [DCLabels].
A label is in normal form if reducing it according to the label normal form reduction algorithm produces the same value.
Two labels are equivalent if their normal form values are mathematically equal.
A label A subsumes (or is more restricting than) another label B if the result of running the label subsumption algorithm on the normal forms of A and B returns true. Labels are partially ordered according to this subsumes relation.
The current confidentiality label is the confidentiality label associated with the current context. §3.3 Labeled Contexts specifies how labels are associated with contexts.
The current integrity label is the integrity label associated with the current context. §3.3 Labeled Contexts specifies how labels are associated with contexts.
When reading a labeled object, a context gets tainted, i.e., its context labels are updated by invoking context tainting algorithm, to reflect that it has read sensitive (of potentially different trustworthiness) data and should be confined accordingly.
A privilege is an unforgeable object that corresponds to a label. Privileges are associated with contexts and reflect their authority.
Privileges can be used to bypass confinement restrictions imposed by confidentiality labels. In particular, a privilege can be used to bypass the restrictions imposed by any label its corresponding label—the internal privilege label—subsumes.
Consider a context from https://a.com whose current confidentiality label is Label("https://a.com").and("https://b.com"). This label confines the context to only communicating with entities whose labels are at least as restricting as this label. For example, it restricts the context from communicating with a context labeled Label("https://b.com"), since doing so could leak https://a.com data to https://b.com. It similarly prevents the context from communicating with https://a.com.
But, suppose that the context’s current privilege corresponds to Label("https://a.com") (afterall, the context originated from https://a.com). Then, the context would be able to bypass some of the restrictions imposed by the context label. Specifically, the context would be able to communicate with https://b.com; the privilege confers it the right to declassify https://a.com data to https://b.com. Indeed, when taking this privilege into consideration, the effective confidentiality label of the context is Label("https://b.com").
Note, the privilege does not allow the context to bypass any label restrictions. For example, it does not allow the context to communicate with https://a.com since doing so could leak https://b.com data.
To be flexible, COWL uses the context privilege to remove certain restrictions imposed by the context label. To avoid accidentally leaking sensitive context data, authors should use LabeledObjects.
Privileges can also be used to bypass integrity restrictions imposed by integrity labels. In particular, a privilege can be used to endorse an otherwise untrustworthy labeled context (or labeled object) as to allow it to communicate with more trustworthy end-points (another context or server).
Consider an https://a.com context whose current integrity label is Label("https://a.com")._or("https://b.com"). This label confines the context to only communicating with entities that are at most as trustworthy as this label. For example, it restricts the context from communicating with a context whose current integrity label is Label("https://a.com"), since doing so would potentially corrupt https://a.com data (e.g., by allowing https://b.com to influence the computation).
But, if the context’s current privilege corresponds to Label("https://a.com"), the context would be able to bypass some of these integrity restrictions. Specifically, the context would be able to communicate with the more-trustworthy context (labeled Label("https://a.com")) since the privilege confers it the right to endorse (or vouch for) its context on behalf of https://a.com. Indeed, when taking privileges into account, the effective integrity label of the context is Label("https://a.com").
Note, the privilege cannot be used to bypass any integrity restrictions. For example, it does not allow the context to communicate with a context whose integrity label is Label(https://b.com).
Note, browsing contexts have a current privilege that, by default, corresponds to the origin of the context, as described in §3.3 Labeled Contexts. But, authors should set the current privilege to a delegated privilege to follow the principle of least privilege.
The current privilege is the privilege associated with the current context. §3.3 Labeled Contexts specifies how privileges are associated with contexts.
The effective confidentiality label is the label returned by the label downgrade algorithm when invoked with the current confidentiality label and current privilege.
The effective integrity label is the label returned by the label upgrade algorithm when invoked with the current integrity label and current privilege.
Code can take ownership of a privilege priv by setting the current privilege to the privilege produced via the combination of the current privilege and priv. In doing so, it is said that the context owns the privilege.
This sub-section is not normative.
COWL extends browsing contexts and Workers with labels and privileges, which are used when enforcing confinement, i.e., when restricting a context’s network and cross-context messaging communication. This document defines the necessary changes and extensions to existing browser constructs and algorithms to enforce confinement.
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.
Current WebIDL implementation requires an underscore for certain identifiers. Can we rename _or to or?
When invoking the Label() constructor, the user agent MUST return a new empty label.
If the origin argument is not a URL, the constructor MUST throw a TypeError exception [ECMA-262] and terminate this algorithm.
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.
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.
Let lab be the Label on which the method has been called.
If the priv argument is provided, let lab be lab.and(priv.asLabel()).
Return true if lab subsumes the other parameter and false otherwise.
Let O be the other argument.
Set O to the result of invoking the Label(other) constructor with other as an argument, if the constructor did not raise an exception.
Else, re-throw the exception and terminate this algorithm.
Return a new Label, in normal form, which is equivalent to adding O’s label set to the label set of the Label on which the method was invoked.
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.
Let JSON lset be a new JSON array.
Let JSON dset be a JSON array of strings, each corresponding an origin in dset.
Append JSON dset to the JSON lset array.
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.
If the argument is not a URL, the function MUST throw a TypeError exception [ECMA-262] and terminate this algorithm.
Else, set self to the self argument.
Let lab be a new empty label.
Let dset label be a new empty label.
If str is a "unique", let origin be a globally unique identifier.
Much like FreshPrivilege(), "unique" is used to create a label component that is globally unique.
Else, if str is "self" and self is not null, let origin be self.
Else, if str is a URL, let origin be str.
Else, throw a TypeError exception [ECMA-262] and terminate this algorithm.
Example labels. Intuition for each label’s semantics is given in the context of it being used as a confidentiality label (C) and integrity label (I).
// C: Data confidential to a.com.
// I: Data endorsed/trusted by a.com.
// C: Data confidential to b.com.
// I: Data endorsed/trusted by b.com.
// I: Data endorsed/trusted by a.com and b.com.
// C: Data confidential to either a.com or b.com.
// I: Data endorsed/trusted by either a.com or b.com.
Examples of label comparisons with intuition for the semantics.
// 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.
//    confidential than data that is only sensitive to a.com (b.com).
//    more trustworthy than data endorsed only by a.com (b.com).
//    data that is confidential to b.com (a.com).
//    data that is endorsed by b.com (a.com).
//    a.com or b.com can be read by an entity that can read a.com (b.com) data alone.
//    by either a.com or b.com necessarily trusts data endorsed by a.com (b.com) alone.
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.
Bikeshed does not allow WebIDL’s NamedConstructor. For now, inlining the constructor as a static method.
When invoking the Privilege() constructor, the user agent MUST return a new Privilege that has an internal privilege label set to Label().
Let unique Label be the label produced by invoking the Label(other) constructor with a globally unique identifier.
Return a new Privilege that has an internal privilege label set to unique Label.
The user agent MUST return the internal privilege label of the Privilege on which the method has been called.
Let internalLabel be the internal privilege label of the Privilege on which the method has been called.
Let otherLabel be the internal privilege label of the other argument.
If the internalLabel does not subsume the label argument, throw a SecurityError exception and terminate this algorithm.
Else, return a new Privilege that has an internal privilege label set to label.
Note, the Privilege constructors and the combine() and delegate() methods only provide ways for creating privileges. Context code must still take ownership of or set the current privilege to the privilege for it to be used (to bypass label restrictions).
To be backwards-compatible with the Same-Origin Policy, COWL grants each browsing context a default privilege that corresponds to their origin. For example, a page on https://example.com has a privilege whose internal privilege label is Label("https://example.com").
After this point, if the context reads data with a Label("https://example.com") confidentiality label, COWL will restrict it to communicating with https://example.com.
Consider an extension to the password strength checker example of §1.2.1 Confining untrusted third-party services that uses FreshPrivilege()s to ensure that the untrusted checker cannot communicate with any entity other than the parent context.
Once the https://untrusted.com context reads the password it will be tainted by the unique, internal privilege label of priv; the unique origin ensures that it cannot send the password to, for example, public parts of https://example.com. Indeed, only the owner of priv can disseminate the labeled password (result) arbitrarily.
At this point, the context can only arbitrarily disseminate data that is labeled Label("https://university.edu")._or("cowl://user1"); it cannot disseminate data that is sensitive to the university (e.g., which is labeled Label("https://university.edu")) or to another user (e.g., user2’s data is labeled Label("https://university.edu")._or("cowl://user2")).
The confinement mode status, which indicates whether or not COWL confinement is enabled and thus labels should be enforced in the current context.
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.
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.
Unless confinement mode is enabled, a context is not subject to confinement.
Unless the current confidentiality label and the current integrity label are non-empty labels, the context’s communication is unrestricted; code is only subject to the restrictions imposed by other mechanism such as the Same-Origin Policy and CSP.
Unless the current privilege is dropped or set to a delegated privilege, code can disseminate data sensitive to the browsing context’s origin, even when confinement mode is enabled. Such data is implicitly declassified using the context privilege. Authors should send LabeledObjects to explicitly communicate the sensitivity (and integrity) of the data they are sharing.
Each context’s COWL state is made available via the COWL interface defined below.
On getting, the user agent MUST return the current confidentiality label.
Let conf be the set confidentiality label.
Let canWrite be the result of invoking the write check algorithm with conf and the current integrity label.
If canWrite is false, throw a SecurityError exception and terminate this algorithm.
Else, set the current confidentiality label to conf.
On getting, the user agent MUST return the current integrity label.
Let int be the set integrity label.
Let canWrite be the result of invoking the write check algorithm with the current confidentiality label and int.
Else, set the current integrity label to int.
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.
On invocation, the user agent MUST enable confinement mode by setting the current context’s COWL state confinement mode status.
Below are several examples showing how to use the COWL API. The §3.2.3 Examples illustrate the use of context privileges.
At this point, no confinement restrictions are applied—COWL is backwards compatible with the existing model. But, the context labels can be set to restrict communication.
At this point, the context can only communicate with https://provider.com. The data provider can ensures that the context is appropriately labeled as such before it can inspect an HTTP response by setting response labels using the Sec-COWL response header.
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.
Let obj clone be the result of obtaining a structured clone of the obj argument.
Let conf be the confidentiality member of the labels argument, if it is set. Otherwise, let conf be the current confidentiality label.
Let int be the integrity member of the labels parameter, if it is set. Otherwise, let int be the current integrity label.
Let canWrite be the result of invoking the write check algorithm with the conf and int labels.
If canWrite is false, the constructor MUST throw a SecurityError exception and terminate this algorithm.
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.
Because COWL enforces labels at context boundaries, there is usually no reason to label an object and then use the labeled object within the same context. LabeledObjects are mainly useful for sending sensitive data to an untrusted context, e.g., via cross-document messaging, as a way to ensure that the data’s confidentiality and integrity (as specified by the labels) are respected by the untrusted context. Hence, the LabeledObject() constructor only accepts objects that can be structurally cloned.
On getting, the user agent MUST return the LabeledObject’s confidentiality label.
On getting, the user agent MUST return the LabeledObject’s integrity label.
Invoke the context tainting algorithm with the LabeledObject’s confidentiality and integrity labels.
The context can’t violate the confidentiality of the data (as specified by the confidentiality label) by communicating arbitrarily once it reads data labeled as such.
The context can’t violate the integrity of entities more trustworthy than the data. (The trustworthiness of the data is specified by the integrity label.) In particular, once the context reads the data and gets tainted, the rest of the computation is restricted to writing to entities that are at most as trustworthy as the data, since the read data may have influenced the computation.
Let obj be the protected object of the object on which the method was invoked.
Let conf be the confidentiality label of the object on which the method was invoked.
Let int be the integrity label of the object on which the method was invoked.
Let newConf be the confidentiality member of the labels argument, if it is set. Otherwise, let newConf be conf.
Let newInt be the integrity member of the labels parameter, if it is set. Otherwise, let newInt be int.
Let privs be the internal privilege label of the current context privileges.
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.
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.
Below are several examples showing the usage of LabeledObjects. §1.2.1 Confining untrusted third-party services gives an example of how LabeledObjects can be used to confine third-party libraries (e.g., a password strength checker). §3.6.1.1 Examples and §3.6.2.1 Examples show how LabeledObjects are used with the XMLHttpRequest constructor.
Note that before getting the first protectedObject, the iframe can communicate arbitrarily, e.g., to fetch map tiles. But once it inspects the confidential locations COWL confines the code—it restricts it to only communicating with https://police.gov. Importantly, it can keep receiving messages from its parent context via postMessage() to, for instance, move a car.
The author of https://example.com wishes to ensure that a particular JSON object conforms to a set of validation filters before submitting it to a remote server. (Consider, for example, a form validator that checks if an email address is valid.) To this end, it labels the JSON and sends the labeled object to (e.g., a Worker or iframe) that performs the validation.
// endorsed by the current (sub-)origin.
The author of https://example.com can then pass the endorsed object to other validators or end-point (e.g., a server), who can, in turn, further endorse the object or verify the origins that have endorsed it.
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.
the serialized context privilege’s internal privilege label given by the ctx-privilege directive.
ctx-directive-name  = "ctx-confidentiality" / "ctx-integrity" / "ctx-privilege"
data-directive-name = "data-confidentiality" / "data-integrity"
disjunction-set     = "[" [ source-expression *( "," [ source-expression ] ) ] "]"
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 .
The user agent MUST send a header field named Sec-COWL along with requests if confinement mode is enabled. The value of this header MUST contain the labeled context metadata of the context that performed the request. This labeled context metadata MUST include the current context confidentiality label, context integrity label, and context privileges. The user agent MAY send another header with this field name whose value is labeled data metadata (e.g., when sending labeled objects with XMLHttpRequest).
Request header from a http://a.com page that has read data sensitive to http://b.com.
A request sent from a public, untrustworthy http://university.edu context that owns a delegated privilege and a FreshPrivilege().
The header value may contain labeled context metadata which can be used to set the initial COWL state of a context; or it may contain labeled data metadata which specifies the sensitivity of the response (which COWL then uses to determine whether or not to block the response).
COWL blocks the response unless the current context’s labels are at least as restricting.
To process this header, the user agent MUST use the Process response to request as COWL algorithm when performing a fetch, as described in §3.7.1 Modifications to Fetch.
The XMLHttpRequest specification SHOULD contain the modifications described below to enable the rest of this specification’s work [XHR].
Let obj be the protected object of the lobj argument.
Let conf be the confidentiality label of the lobj argument.
Let int be the integrity label of the lobj argument.
Let privs be the current context privileges.
Let remoteConf be the label returned by the Label(origin) constructor called with the url associated with the request.
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.
Set the Content-Type header to `application/labeled-json`.
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.
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.
The server can then verify the integrity label of the request and ensure that, if the user agent is conformant, the data was endorsed by https://validator.com.
An XMLHttpRequest has associated response LabeledObject object.
If the response LabeledObject object is non-null, return it.
If responseType is not "labeled-json" or the final MIME type is not application/labeled-json, return null.
Let bytes be the response’s body.
If bytes is null, return null.
Let JSON text be the result of running utf-8 decode on byte stream bytes.
If the JSON object is missing any of the three entries: "object", "confidentiality", or "integrity" return null.
Let protected object be the value of the "object" entry.
Let self be the url associated with the response.
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.
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.
Let responseInt be the label returned by the Label(origin) constructor called with self.
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?
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.
Return the labeled JSON response.
↪ If responseType is "labeled-json"
Set response LabeledObject object to null.
§1.2.2 Sharing data with third-party mashups gives an example of a mashup scenario wherein the data provider uses the Sec-COWL HTTP response header to ensure that the mashup integrator can only read the HTTP response if it is sufficiently confined. A more permissive approach is to send a labeled JSON response.
The confidentiality label specifies that the object is confidential to https://provider.com and should not be disseminated arbitrarily.
Here, COWL sets the response to a new LabeledObject, but does not taint the context with the response label. Indeed the https://mashup.com integrator can perform many other requests to different origins. Only when the protected objects of these labeled objects are used will COWL taint the context and impose the label restrictions.
Once the receiver inspects the protectedObject of the response, COWL taints the context and ensures that it cannot communicate with anybody.
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.
If should fetching request be blocked as COWL returns blocked, set response to a network error.
If process response to request as COWL returns blocked, set response to a network error.
Let conf be the current context’s effective confidentiality label.
Let int be the current context’s effective integrity label.
Let dstState be the COWL state associated with the Document of the Window object on which the method was invoked.
If confinement mode for dstState is enabled, let dstConf be the dstState effective confidentiality label.
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).
Let dstInt be the dstState effective integrity label.
If dstConf does not subsume conf or if int does not subsume dstInt, then abort the remaining steps silently.
Let dstState be the COWL state associated with the owner of the target port the Message Port postMessage() was called on.
Let dstInt be the state effective integrity label.
If dstConf does not subsume conf or if int does not subsume dstInt, then abort the remaining steps.
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.
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.
Let lset be the label set of an empty label.
Remove every disjunction set in lset that dset is a subset of.
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.
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.
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.
Let privLabel be the internal privilege label of priv.
Let cur be a newly create Label whose label set is dset.
If privLabel does not subsume cur, add dset to lset.
Note, label downgrade removes every disjunction set permitted by priv. This is used to safely declassify data labeled label.
Note, label upgrade is the dual of label downgrade. This can be used to safely endorse data labeled label (and thus potentially already endorsed).
Let currentConf be the current context confidentiality label.
Let currentInt be the current context integrity label.
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.
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.
Let currentConf be the current context’s effective confidentiality label.
Let currentInt be the current context’s effective integrity label.
If objConf does not subsume currentConf or if currentInt does not subsumes objInt, return false.
If input is a Label object, let output be a newly constructed Label object with the same label set as that of input.
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.
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.
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?
Note: this algorithm is used to determine whether a request should be entirely blocked, because it may potentially leak sensitive data to an unauthorized server.
Let context be the client associated with the request.
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.
Let state be the COWL state retrieved via the environment settings object context.
If the state confinement mode is not enabled, return allowed and terminated this algorithm.
Let conf be the state effective confidentiality label.
Let dstConf be the Label created by invoking the Label(origin) constructor with the url associated with the request.
If dstConf subsumes conf, return allowed.
If the request is a navigation request and the request’s context frame type is top-level 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.
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.
If a request proceeds, we still might want to block the response based on the labeled data metadata of the response. For example, if the current confidentiality label does not subsume the confidentiality label of the response, the user agent MUST block the response since it could otherwise violate the confidentiality of the response data. (The dual holds for integrity.) This algorithm is used to make the determination of whether or not a response is blocked.
This algorithm is also used to set the COWL state for new documents and Workers according to server-supplied the labeled context metadata.
If the response’s header list has no header whose name is Sec-COWL, return allowed and terminate this algorithm.
Let destination be the request’s destination.
Let type be the request’s type.
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.
Let metadata be the first header whose name is Sec-COWL in the response’s header list.
Let self be the serialization of the origin retrieved via the environment settings object context.
Let conf, int, priv be the result of calling the parse labeled context metadata algorithm with metadata and self.
If either conf, int, or priv are null, return blocked.
Set the state context confidentiality label to conf.
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.
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?
Enable confinement mode for state.
Let conf and int be the results of calling the parse labeled data metadata with metadata and self.
If either conf or int is null, return blocked and terminate this algorithm.
If the state effective confidentiality label subsumes conf and int subsumes the state effective integrity label, return allowed.
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.
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.
If directive name is data-confidentiality and conf is null, let conf be label value.
Else, if directive name is data-integrity and int is null, let int be label value.
Else, ignore this instance of the directive and continue to the next token.
To make it easier for developers to debug applications, user agents SHOULD report the directives that were ignored.
If directive name is ctx-confidentiality and conf is null, let conf be label value.
Else, if directive name is ctx-integrity and int is null, let int be label value.
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.
Return conf, int, and priv.
Thanks to Dan Boneh, Brendan Eich, Brad Hill, Dave Herman, Bobby Holley, Brad Karp, Jonathan Kingston Petr Marchenko, David Mazières, Devon Rifkin, Alejandro Russo, and Brian Smith for influencing (directly or otherwise) the design of COWL and/or their comments on this document.

References: §3
 §1
 §3
 §3
 §3
 §3
 §3
 §3
 §1
 §3
 §1
 §3
 §3
 §4
 §4
 §3

§1