[Documentation] Add Web Platform Security Guidelines
This CL adds documentation regarding a set of guidelines the Web
Platform Security team encourages Web Platform APIs to follow to
keep those APIs and the Web Platform secure.
Change-Id: I779ed48e272db76349d8b0371fee6c19b8e50720
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3695201
Reviewed-by: Chris Thompson <[email protected]>
Reviewed-by: Balazs Engedy <[email protected]>
Reviewed-by: Mike West <[email protected]>
Commit-Queue: Camille Lamy <[email protected]>
Reviewed-by: Adrian Taylor <[email protected]>
Reviewed-by: Rakina Zata Amni <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1067467}
diff --git a/docs/security/web-platform-security-guidelines.md b/docs/security/web-platform-security-guidelines.md
new file mode 100644
index 0000000..5aed42b
--- /dev/null
+++ b/docs/security/web-platform-security-guidelines.md
@@ -0,0 +1,444 @@
+# Web Platform Security guidelines
+
+[TOC]
+
+## 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
+
+<a name="TOC-safe-api-guidelines"></a>
+#### 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).
+
+<a name="TOC-design-with-the-web-ecosystem-in-mind"></a>
+#### 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](https://www.w3.org/TR/security-privacy-questionnaire/#non-fully-active)
+part of the W3C security and privacy questionnaire.
+
+<a name="TOC-enterprise-policies"></a>
+#### 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](https://chromium.googlesource.com/chromium/src/+/master/docs/security/faq.md#Are-enterprise-admins-considered-privileged)
+for more information on enterprise policies.
+
+### Security boundaries
+
+<a name="TOC-security-boundaries"></a>
+#### 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).
+
+<a name="TOC-the-origin-boundary"></a>
+#### 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](https://developer.mozilla.org/en-US/docs/Web/Security/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).
+
+<a name="TOC-encryption"></a>
+#### 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](https://chromium.googlesource.com/chromium/src/+/main/docs/security/faq.md#why-are-some-web-platform-features-only-available-in-https-page_loads)
+for more information.
+
+<a name="TOC-timer-resolution"></a>
+#### 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.
+
+<a name="TOC-accessing-data-of-cross-origin-subresources"></a>
+#### 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.
+
+<a name="TOC-side-channels"></a>
+#### 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.
+
+<a name="TOC-implementation-concerns"></a>
+#### 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](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/security/rule-of-2.md)),
+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).
+
+<a name="TOC-user-activation"></a>
+#### 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.
+
+<a name="TOC-navigation-and-document-lifetime"></a>
+#### 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
+
+<a name="TOC-document-load"></a>
+#### Document load
+
+> All changes to how a document is loaded should ensure they uphold the following
+> security policies:
+> [XFO](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options),
+> [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP),
+> [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy),
+> [COEP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy),
+> and [Private Network access](https://wicg.github.io/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.
+
+<a name="TOC-subresource-load"></a>
+#### Subresource load
+
+> All changes to how a resource is loaded should uphold the following
+> security policies:
+> [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP),
+> [COEP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy),
+> [CORP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy_(CORP)),
+> [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS),
+> [CORB](https://fetch.spec.whatwg.org/#corb),
+> [SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)
+> and [Private Network access](https://wicg.github.io/private-network-access/).
+
+* All of the policies above may block unsafe resource loads and must be
+properly applied to any subresource load.
+
+<a name="TOC-code-execution"></a>
+#### 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](https://github.com/WICG/import-maps/issues/105) had to be spelled
+as an extension to the
+`<script>` tag to avoid inadvertently creating CSP bypasses.
+
+<a name="TOC-CORS"></a>
+#### 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.
+
+<a name="TOC-mime-types"></a>
+#### MIME types
+
+> New resource types should require strict MIME type matching, and avoid
+> relying upon [sniffing](https://mimesniff.spec.whatwg.org/).
+
+* 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](https://chromium.googlesource.com/chromium/src/+/HEAD/services/network/cross_origin_read_blocking_explainer.md)
+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
+
+<a name="TOC-iframes"></a>
+#### 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.
+
+<a name="TOC-browser-controlled-surface"></a>
+#### 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.
+
+<a name="TOC-site-identity-and-security-indicators"></a>
+#### 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](https://chromium.googlesource.com/chromium/src/+/master/docs/security/faq.md#Certificates-Connection-Indicators)
+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.
+
+<a name="TOC-browser-controlled-ui"></a>
+#### 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.
+
+<a name="TOC-permissions"></a>
+#### 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.
+
+<a name="TOC-mixed-content"></a>
+#### 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).
+
+<a name="TOC-foreground-background-execution"></a>
+#### 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.
+
