summaryrefslogtreecommitdiff
path: root/chromium/docs/webui_explainer.md
diff options
context:
space:
mode:
authorAllan Sandfeld Jensen <allan.jensen@qt.io>2021-05-20 09:47:09 +0200
committerAllan Sandfeld Jensen <allan.jensen@qt.io>2021-06-07 11:15:42 +0000
commit189d4fd8fad9e3c776873be51938cd31a42b6177 (patch)
tree6497caeff5e383937996768766ab3bb2081a40b2 /chromium/docs/webui_explainer.md
parent8bc75099d364490b22f43a7ce366b366c08f4164 (diff)
downloadqtwebengine-chromium-189d4fd8fad9e3c776873be51938cd31a42b6177.tar.gz
BASELINE: Update Chromium to 90.0.4430.221
Change-Id: Iff4d9d18d2fcf1a576f3b1f453010f744a232920 Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>
Diffstat (limited to 'chromium/docs/webui_explainer.md')
-rw-r--r--chromium/docs/webui_explainer.md84
1 files changed, 45 insertions, 39 deletions
diff --git a/chromium/docs/webui_explainer.md b/chromium/docs/webui_explainer.md
index f62e208a4c7..fbbb482b1aa 100644
--- a/chromium/docs/webui_explainer.md
+++ b/chromium/docs/webui_explainer.md
@@ -258,8 +258,10 @@ So, the given C++ code:
```c++
void OvenHandler::RegisterMessages() {
- web_ui()->RegisterMessageHandler("bakeDonuts",
- base::Bind(&OvenHandler::HandleBakeDonuts, base::Unretained(this)));
+ web_ui()->RegisterMessageCallback(
+ "bakeDonuts",
+ base::BindRepeating(&OvenHandler::HandleBakeDonuts,
+ base::Unretained(this)));
}
void OvenHandler::HandleBakeDonuts(const base::ListValue* args) {
@@ -359,11 +361,11 @@ chrome/browser/ui/webui/webui\_util.\* contains a number of methods to simplify
common configuration tasks.
<a name="AddLocalizedStringsBulk"></a>
-### webui::AddLocalizedStringsBulk()
+### WebUIDataSource::AddLocalizedStrings()
Many Web UI data sources need to be set up with a large number of localized
strings. Instead of repeatedly calling <code>AddLocalizedString()</code>, create
-an array of all the strings and use <code>AddLocalizedStringsBulk()</code>:
+an array of all the strings and use <code>AddLocalizedStrings()</code>:
```c++
static constexpr webui::LocalizedString kStrings[] = {
@@ -372,16 +374,15 @@ an array of all the strings and use <code>AddLocalizedStringsBulk()</code>:
{"ariaRoleDescription", IDS_HISTORY_ARIA_ROLE_DESCRIPTION},
{"bookmarked", IDS_HISTORY_ENTRY_BOOKMARKED},
};
- AddLocalizedStringsBulk(source, kStrings);
+ source->AddLocalizedStrings(kStrings);
```
-<a name="AddResourcePathsBulk"></a>
-### webui::AddResourcePathsBulk()
+<a name="AddResourcePaths"></a>
+### WebUIDataSource::AddResourcePaths()
Similar to the localized strings, many Web UIs need to add a large number of
-resource paths. In this case, use <code>AddResourcePathsBulk()</code> to
-replace repeated calls to <code>AddResourcePath()</code>. There are two
-versions. One works almost identically to the strings case:
+resource paths. In this case, use <code>AddResourcePaths()</code> to
+replace repeated calls to <code>AddResourcePath()</code>.
```c++
static constexpr webui::ResourcePath kPdfResources[] = {
@@ -389,20 +390,18 @@ versions. One works almost identically to the strings case:
{"pdf/constants.js", IDR_PDF_CONSTANTS_JS},
{"pdf/controller.js", IDR_PDF_CONTROLLER_JS},
};
- webui::AddResourcePathsBulk(source, kStrings);
+ source->AddResourcePaths(kStrings);
```
-The second version instead accepts a span of <code>GritResourceMap</code> so
-that it can directly use constants defined by autogenerated grit resources map
-header files. For example, the autogenerated print\_preview\_resources\_map.h
-header defines a <code>GritResourceMap</code> named
-<code>kPrintPreviewResources</code> and a
-<code>size\_t kPrintPreviewResourcesSize</code>. All the resources in this
+The same method can be leveraged for cases that directly use constants defined
+by autogenerated grit resources map header files. For example, the autogenerated
+print\_preview\_resources\_map.h header defines a
+<code>webui::ResourcePath</code> array named <code>kPrintPreviewResources</code>
+and a <code>size\_t kPrintPreviewResourcesSize</code>. All the resources in this
resource map can be added as follows:
```c++
- webui::AddResourcePathsBulk(
- source,
+ source->AddResourcePaths(
base::make_span(kPrintPreviewResources, kPrintPreviewResourcesSize));
```
@@ -727,7 +726,8 @@ renderer:
v8::Local<v8::Object> chrome = GetOrCreateChromeObject(isolate, context);
chrome->Set(gin::StringToSymbol(isolate, "send"),
gin::CreateFunctionTemplate(
- isolate, base::Bind(&WebUIExtension::Send))->GetFunction());
+ isolate,
+ base::BindRepeating(&WebUIExtension::Send))->GetFunction());
```
The `chrome.send()` method takes a message name and argument list.
@@ -883,28 +883,34 @@ since taking control of a WebUI page can sometimes be sufficient to escape
Chrome's sandbox. To make sure that the special powers granted to WebUI pages
are safe, WebUI pages are restricted in what they can do:
-* WebUI pages cannot embed http/https resources or frames
+* WebUI pages cannot embed http/https resources
* WebUI pages cannot issue http/https fetches
In the rare case that a WebUI page really needs to include web content, the safe
-way to do this is by using a `<webview>` tag. Using a `<webview>` tag is more
-secure than using an iframe for multiple reasons, even if Site Isolation and
-out-of-process iframes keep the web content out of the privileged WebUI process.
-
-First, the content inside the `<webview>` tag has a much reduced attack surface,
-since it does not have a window reference to its embedder or any other frames.
-Only postMessage channel is supported, and this needs to be initiated by the
-embedder, not the guest.
-
-Second, the content inside the `<webview>` tag is hosted in a separate
-StoragePartition. Thus, cookies and other persistent storage for both the WebUI
-page and other browser tabs are inaccessible to it.
-
-This greater level of isolation makes it safer to load possibly untrustworthy or
-compromised web content, reducing the risk of sandbox escapes.
-
-For an example of switching from iframe to webview tag see
-https://crrev.com/c/710738.
+way to do this is by using an `<iframe>` tag. Chrome's security model gives
+process isolation between the WebUI and the web content. However, some extra
+precautions need to be taken, because there are properties of the page that are
+accessible cross-origin and malicious code can take advantage of such data to
+attack the WebUI. Here are some things to keep in mind:
+
+* The WebUI page can receive postMessage payloads from the web and should
+ ensure it verifies any messages as they are not trustworthy.
+* The entire frame tree is visible to the embedded web content, including
+ ancestor origins.
+* The web content runs in the same StoragePartition and Profile as the WebUI,
+ which reflect where the WebUI page was loaded (e.g., the default profile,
+ Incognito, etc). The corresponding user credentials will thus be available to
+ the web content inside the WebUI, possibly showing the user as signed in.
+
+Note: WebUIs have a default Content Security Policy which disallows embedding
+any frames. If you want to include any web content in an <iframe> you will need
+to update the policy for your WebUI. When doing so, allow only known origins and
+avoid making the policy more permissive than strictly necessary.
+
+Alternatively, a `<webview>` tag can be used, which runs in a separate
+StoragePartition, a separate frame tree, and restricts postMessage communication
+by default. However, `<webview>` does not support Site Isolation and
+therefore it is not advisable to use for any sensitive content.
## See also