Web Platform Security guidelines

Introduction

The Open Web Platform (OWP) is a fast evolving platform, with new features continuously expanding the scope of what the platform can do. It is also a particularly rich target for would-be attackers. In this context, all new features should be reviewed with particular care when it comes to their security implications. The goal of this document is to help feature teams go through the Security part of the S&P review process which ensures that their features meet the security requirements expected of a new Web Platform feature.

The guidelines in this document provide insight on how the Security teams think about the security implications of new Web Platform features. They are here to help feature teams think about security early on when designing their APIs. As new threats and new mitigations arise, we will update this document to reflect our updated recommendations.

Currently, this document is divided into three sets of guidelines: security boundaries, integration with security APIs and security UX. We have written those based on the Web Platform Security team experience of conducting security reviews, in partnership with other security teams at Google. This is based on concerns that have come up in security reviews, and a few items that we envision could be problematic.

The goal of this document is not to provide a checklist, where if every item in the list is checked a feature can be considered secure. If you find that your feature cannot meet some of the security guidelines on this list, please reach out to the Web Platform Security team earlier rather than later, and we can work together on how to support your feature’s needs in a secure manner.

Guidelines

General guidelines

Safe API design

Prefer simple APIs.

It is easier for developers to use higher-level and well laid out APIs. Try to make the easy thing the safe thing in new APIs.
If an API really needs potentially risky knobs, they should be well documented and ideally named to explicitly call out their risk (e.g., the subtle property in WebCrypto -- although this naming could be even more explicit).

Design with the web ecosystem in mind

Consider how your feature will interact with the whole web ecosystem. In particular, consider the interactions with workers (ServiceWorkers, SharedWorkers, DedicatedWorkers), Fenced Frames and with the back/forward cache.

Some features might need to be restricted in workers. For example, we have restricted access to features like camera/microphone/geolocation because we have no UI surface with which to explain the implication of an API to users.
Fenced Frames have particular privacy requirements that might require disabling a feature inside them. For example, CSP EE required particular integration as enforcing a CSP on a Fenced Frame would provide a communication channel with the Fenced Frame embedder.
The interaction of the feature with the back/forward cache might be a security concern. For example, audio and video capture should only be allowed in pages currently shown to the users, and not in pages located in the back/forward cache. See also the non-fully active part of the W3C security and privacy questionnaire.

Enterprise policies

New enterprise policies are not allowed to bypass existing web security policies/protections. Enterprise policies can only be added to bypass newly introduced security restrictions, to maintain compatibility of existing enterprise web apps. Enterprise policies should only ever bypass policy decisions made by the browser, and not policies requested by websites.

When the browser introduces a new security restriction, such as gating Shared Array Buffers behind crossOriginIsolation, it is ok to introduce an enterprise policy to bypass that restriction in order to maintain compatibility of existing enterprise web apps.
It is not ok to create an enterprise policy to bypass longstanding security restrictions that should be supported by existing apps. For example, it would not be ok to introduce an enterprise policy to bypass the same-origin policy.
Enterprise policies should only apply to new security restrictions introduced to the browser. Enterprise policies should not be used to relax security policies requested by the website themselves. For example, it would not be ok to introduce an enterprise policy that bypasses CSP.
See the Chrome Security FAQ for more information on enterprise policies.

Security boundaries

The security team maintains several security boundaries in the WebPlatform: origin, site, secure contexts, cross-origin isolated contexts. Before introducing a new security boundary to support your design, discuss it with the Web Platform Security team to ensure it's equally enforceable.

Maintaining a security boundary is complex, and might not even be possible (e.g. origins and Spectre). An API relying on a new form of security boundary should be thoroughly discussed with the Security team to check if the boundary is enforceable and the security guarantees can be met. For example, it is impossible to create an iframe that is fully isolated from its parent, due to the risk of Spectre attacks on platforms that do not support Site Isolation (low-end Android).

The origin boundary

The origin is the security boundary we aim to defend. We may make diverge from that (in both directions) in some cases, but those ought to be done in consultation with security folks.

The origin is the primary security boundary of the web, as per the Same-origin policy.
Note that unlike privacy, security is concerned with same-site but cross-origin interactions.
Maintaining a security boundary is complex, and might not even be possible (e.g. origins and Spectre). An API relying on a new form of security boundary should be thoroughly discussed with the Security team to check if the boundary is enforceable and the security guarantees can be met. For example, it is impossible to create an iframe that is fully isolated from its parent, due to the risk of Spectre attacks on platforms that do not support Site Isolation (low-end Android).

Encryption

Prefer secure contexts for new features.

Any data sent over HTTP can be observed by others on the network and opens users to on-path attackers.
The same-origin policy the web security model is built upon is easily abused without cryptographical authentication of the servers we are talking to.
See the Chrome Security FAQ for more information.

Timer resolution

Explicit timers' granularity must be limited based on a context's cross-origin isolation status. Currently, isolated contexts can support timers coarsened to at least 5 microseconds, while unisolated contexts must coarsen timers to 100 microseconds or more. If an API allows the creation of timers with a precision higher than allowed in unisolated contexts, it should be restricted to crossOriginIsolated contexts.

High resolution timers open users to timing attacks such as Spectre. This is why their precision should be limited.
In crossOriginIsolated contexts, cross-origin resources are either loaded without credentials, or they opt into being embedded cross-origin into a context where they could potentially be read by their embedder. This means that cross-origin resources in a crossOriginIsolated context are either ok with a Spectre attack (opt-in model), or of no interest to an attacker (credentialless model). Because of this, we allow higher precision timers in crossOriginIsolated contexts.
APIs that can be used to create timers (e.g. SharedArrayBuffers) that are more precise than timers available in cross-origin isolated contexts should be gated behind crossOriginIsolation, in order to avoid introducing high resolution timers to the platform.

Accessing data of cross-origin subresources

New APIs that can access data from cross-origin subresources should be gated behind an appropriate mechanism depending on their surface:
CORS/TAO for access to a single resource.
crossOriginIsolation for access to the agent cluster.
crossOriginIsolation + frame opt-in mechanism for access to the whole page.

This kind of API bypasses the same-origin policy, which is the base of the Web security model. This is only acceptable if the cross-origin resources opt into sharing this data.
CORS or TAO are appropriate when divulging information about a single resource, e.g. load timings for a single resource.
crossOriginIsolation should be used when the API can divulge information about cross-origin resources located in the same agent cluster (roughly, the API is scoped to same-origin documents). For example, an API that measures the memory taken by all same-origin documents and their subresources.
If the API can divulge information from the resources located in the whole page, we will need an opt-in from documents outside the agent cluster, on top of crossOriginIsolation. For example, an API that streams a video of the page or takes a screenshot of the page. Alternatively, it might be acceptable to gate the API behind user interaction with a sufficiently informative UI element.

Side channels

Any new form of cross-origin communication or API should be carefully considered when it comes to side-channel attack risks.

Cross-origin communication channels and APIs can be abused to leak data from cross-origin resources. Any new addition should be carefully reviewed to assess the amount of data exposed. Note that unlike privacy, security is concerned with same-site but cross-origin communication and APIs.

Implementation concerns

Any new API whose implementation is particularly risky (e.g. requires new parsers, involves new codecs, requires particular isolation) should see the implementation reviewed in detail, in conjunction with the wider Chrome Security team.

New parsers and codecs are particularly risky pieces of code that are exposed to attacker-controlled inputs. Their implementations are subjected to particular rules (see the rule of two), and they must be fuzzed.
Proper isolation is hard to deploy, is heavily dependent on implementation and might face constraints on some platforms (e.g. low-end Android devices).

User activation

Consider requiring a feature be gated behind user activation if its UX could be abused by a document the user did not interact with.

Several features should only be available if the user chooses to interact with the document. If they could be abused otherwise, consider gating them behind user activation. For example, fullscreen is gated behind user activation, as it could be used to trick the user into believing they are on another page by mimicking the Chrome UI.
This helps match the platform with the user’s mental model.
Features which are security sensitive will likely need aditional protection beyond user activation. User activation is not a security boundary, it is a way to protect users from abusive UX behavior from sites.

Navigation and Document lifetime

Any feature that impacts the lifetime of documents or that modifies navigation is likely to have far-reaching security implications. Please discuss the implications with the Web Platform Security team as soon as possible.

Modifying the navigation stack could cause URL spoofing attacks.
Modifying the navigation stack or the document lifetime could result in wrong origin or security policies being applied to the document.

Integration with security policies

Document load

All changes to how a document is loaded should ensure they uphold the following security policies: XFO, CSP, COOP, COEP, and Private Network access.

XFO, CSP, COEP and Private Network access can block document load. This should be respected.
COOP can trigger a browsing context group switch which should be respected as well.
CSP, COEP and Private Network access are computed when loading a document and may apply to all of the document resources. Failure to integrate properly with them could result in the policies being bypassed.

Subresource load

All changes to how a resource is loaded should uphold the following security policies: CSP, COEP, CORP, CORS, CORB, SRI and Private Network access.

All of the policies above may block unsafe resource loads and must be properly applied to any subresource load.

Code execution

New ways of executing JavaScript code should integrate with CSP script-src.

New ways of executing JavaScript should defend themselves against XSS attacks by supporting CSP.

New ways of executing code should consider the cross-site scripting (XSS) risks. If any new risk is identified, the new API should integrate with CSP script-src and/or Trusted Types and/or Sanitizer.

New ways of executing code should consider whether they are open to XSS vulnerabilities. If they are, they should defend themselves against attacks by supporting CSP and/or Trusted Types and/or Sanitizer.
For example, the import map proposal had to be spelled as an extension to the <script> tag to avoid inadvertently creating CSP bypasses.

CORS

New types of elements should require CORS when loading resources.

CORS allows an origin to control how its authenticated data is embedded in other origins. In an ideal world, all cross-origin authenticated requests would require CORS, but this is impossible for compatibility reasons. However, new elements should not add a new source of non CORS requests to the platform.
Elements that are allowed to make cross-origin authenticated requests without CORS introduce a hole in the platform that may be exploited in a MIME mismatch attack to bypass CORS protections for resources that are normally loaded through Fetch or into elements that require CORS.

MIME types

New resource types should require strict MIME type matching, and avoid relying upon sniffing.

Mismatches between a resource‘s asserted MIME type and the way it’s used by the browser can cause security issues. For example, browsers currently attempt to execute practically anything via <script> tags because of widespread mislabeling of script resources as text/html or text/plain`, which can expose those resources to side-channel attacks like Spectre, and more direct XSSI attacks. CORB mitigates some, but not all, of these risks.
New resource types should avoid these risks entirely by specifying clear MIME types, and accepting only those resources that assert themselves to be of the proper type.

Security UX

Iframes

A document element should not be allowed to draw outside its frame.

A document drawing over its embedding frame allows it to perform clickjacking attacks and should never be allowed.
Drawing over the browser-controlled UX surface allows to perform all sorts of attacks. See the browser-controlled surface guideline below for more information.

Browser-controlled surface

Browser-controlled surfaces should not be drawn over. Converting a browser-controlled UX surface into a content-controlled surface can only be considered in specific cases and must be gated behind appropriate mechanisms.

Drawing over the omnibox allows to perform URL spoof attacks and should never be allowed. It can also lead to displaying incorrect SSL state information to the user.
It is possible to consider converting some of the browser-controlled surfaces into content-controlled surfaces in cases such as installed PWAs. This should still be gated behind explicit signals from the user, such as a permission grant or other in-context UI affordances that allow the user to toggle between modes.
Browser-controlled surfaces include the top browser chrome, but also the fullscreen disclosure bubble, Payment Handler dialogs, permission dialogs, etc.

Site identity and security indicators

Communicating site identity and security indicators should only be done through browser-controlled UI.

Security state and site identity are state tracked by the browser and it is difficult (at best) to show this information inside the content area in a trustworthy way. See the Chrome Security FAQ for more details.
Interstitials (e.g., SSL error pages) are shown in the content area but are browser controlled committed navigations.
Other security displays overlaid on the content area (e.g., autofill warnings) should be handled with care and should be controlled by the browser.

Browser-controlled UI

Changes to browser-controlled UI or new features that will require new browser-controlled UI should go through Chrome Browser security review.

Browser-controlled UI has many considerations around spoofing, abuse, etc.
New UI needs to be reviewed by various cross-functional groups (not just security).
This is especially true when the UI involves the user making a decision or the UI communicates site identity to the user in any way.

Permissions

Powerful new capabilities should in most cases integrate with Permissions-Policy and only be accessible to top-level frames by default. The Permissions Team should be brought in early to consult on new permissions.

Permissions often require users to make a trust decision about a site. In Chrome, the only visible site identity is the top-level frame (whose origin is shown in the Omnibox).
User confusion about subframe origins was a motivation for permission delegation, where top-level contexts must explicitly delegate their permissions to subframes, allowing the user to only have to reason about top-level frames.

Mixed content

New features should not be able to relax or work around mixed content restrictions.

Chrome now upgrades or blocks all mixed content (insecure resources or connections embedded in secure contexts). This greatly simplifies Chrome’s security state model.
Allowing new features to bypass these security restrictions can undermine other security features in Chrome which assume no mixed content (such as HTTPS-First Mode).

Foreground/background execution

Consider whether a new feature might be abusable or confusing to a user if a site can use it while in the background. Ensure that the user has sufficient context for something triggering and won’t be caught by surprise.

This will often co-occur with “Browser-controlled UI” (see above), but it is good to think about whether an API should be restricted to foreground tabs only if they have a risk of being surprising to the user when used by a page.
For example, we restrict HTML fullscreen to foreground contexts (and display a disclosure UI). APIs that trigger permission prompts should only show the prompts when the tab is in the foreground.