• 首页
  • 狐文
  • 狐图
  • About
狐窝
OvO
  1. 首页
  2. 未分类
  3. 正文

Chrome WebUI 解释器相关资料

2020年09月10日 203点热度 0人点赞 0条评论

WebUI是chrome中的具有更高权限的页面,可以对chrome进行设置管理。

 

资料来源:

https://chromium.googlesource.com/chromium/src.git/+/master/docs/webui_explainer.md#chrome_urls

---------------------------------------------

WebUI Explainer

Contents

  • What is WebUI?
  • What's different from a web page?
  • How URLs work
    • protocol
    • hosts
  • C++ classes
    • WebUI
    • WebUIController
    • WebUIDataSource
    • WebUIMessageHandler
  • Browser (C++) → Renderer (JS)
    • WebUIMessageHandler::AllowJavascript()
    • WebUIMessageHandler::CallJavascriptFunction()
    • WebUIMessageHandler::FireWebUIListener()
    • WebUIMessageHandler::OnJavascriptAllowed()
    • WebUIMessageHandler::OnJavascriptDisallowed()
    • WebUIMessageHandler::RejectJavascriptCallback()
    • WebUIMessageHandler::ResolveJavascriptCallback()
  • Renderer (JS) → Browser (C++)
    • chrome.send()
    • cr.sendWithPromise()
  • Security considerations
  • See also

What is “WebUI”?

“WebUI” is a term used to loosely describe parts of Chrome's UI implemented with web technologies (i.e. HTML, CSS, JavaScript).

Examples of WebUI in Chromium:

  • Settings (chrome://settings)
  • History (chrome://history)
  • Downloads (chrome://downloads)

This document explains how WebUI works.

What's different from a web page?

WebUIs are granted super powers so that they can manage Chrome itself. For example, it'd be very hard to implement the Settings UI without access to many different privacy and security sensitive services. Access to these services are not granted by default.

Only special URLs are granted WebUI “bindings” via the child security process.

Specifically, these bindings:

  • give a renderer access to load chrome: URLS
    • this is helpful for shared libraries, i.e. chrome://resources/
  • allow the browser to execute arbitrary JavaScript in that renderer via CallJavascriptFunction()
  • allow communicating from the renderer to the browser with chrome.send() and friends
  • ignore content settings regarding showing images or executing JavaScript

How chrome: URLs work

A chrome: URL loads a file from disk, memory, or can respond dynamically.

Because Chrome UIs generally need access to the browser (not just the current tab), much of the C++ that handles requests or takes actions lives in the browser process. The browser has many more privileges than a renderer (which is sandboxed and doesn't have file access), so access is only granted for certain URLs.

chrome: protocol

Chrome recognizes a list of special protocols, which it registers while starting up.

Examples:

  • devtools:
  • chrome-extensions:
  • chrome:
  • file:
  • view-source:

This document mainly cares about the chrome: protocol, but others can also be granted WebUI bindings or have special properties.

chrome: hosts

After registering the chrome: protocol, a set of factories are created. These factories contain a list of valid host names. A valid hostname generates a controller.

In the case of chrome: URLs, these factories are registered early in the browser process lifecycle.

// ChromeBrowserMainParts::PreMainMessageLoopRunImpl():
content::WebUIControllerFactory::RegisterFactory(
   ChromeWebUIControllerFactory::GetInstance());

When a URL is requested, a new renderer is created to load the URL, and a corresponding class in the browser is set up to handle messages from the renderer to the browser (a RenderFrameHost).

The URL of the request is inspected:

if (url.SchemeIs("chrome") && url.host_piece() == "donuts")  // chrome://donuts
  return &NewWebUI<DonutsUI>;
return nullptr;  // Not a known host; no special access.

and if a factory knows how to handle a host (returns a WebUIFactoryFunction), the navigation machinery grants the renderer process WebUI bindings via the child security policy.

// RenderFrameHostImpl::AllowBindings():
if (bindings_flags & BINDINGS_POLICY_WEB_UI) {
  ChildProcessSecurityPolicyImpl::GetInstance()->GrantWebUIBindings(
      GetProcess()->GetID());
}

The factory creates a WebUIController for a tab. Here's an example:

// Controller for chrome://donuts.
class DonutsUI : public content::WebUIController {
 public:
  DonutsUI(content::WebUI* web_ui) : content::WebUIController(web_ui) {
    content::WebUIDataSource* source =
        content::WebUIDataSource::Create("donuts");  // "donuts" == hostname
    source->AddString("mmmDonuts", "Mmm, donuts!");  // Translations.
    source->SetDefaultResource(IDR_DONUTS_HTML);  // Home page.
    content::WebUIDataSource::Add(source);

    // Handles messages from JavaScript to C++ via chrome.send().
    web_ui->AddMessageHandler(std::make_unique<OvenHandler>());
  }
};

If we assume the contents of IDR_DONUTS_HTML yields:

<h1>$i18n{mmmDonuts}</h1>

Visiting chrome://donuts should show in something like:

Delicious success.

By default $i18n{} escapes strings for HTML. $i18nRaw{} can be used for translations that embed HTML, and $i18nPolymer{} can be used for Polymer bindings. See this comment for more information.

C++ classes

WebUI

WebUI is a high-level class and pretty much all HTML-based Chrome UIs have one. WebUI lives in the browser process, and is owned by a RenderFrameHost. WebUIs have a concrete implementation (WebUIImpl) in content/ and are created in response to navigation events.

A WebUI knows very little about the page it's showing, and it owns a WebUIController that is set after creation based on the hostname of a requested URL.

A WebUI can handle messages itself, but often defers these duties to separate WebUIMessageHandlers, which are generally designed for handling messages on certain topics.

A WebUI can be created speculatively, and are generally fairly lightweight. Heavier duty stuff like hard initialization logic or accessing services that may have side effects are more commonly done in a WebUIController or WebUIMessageHandlers.

WebUI are created synchronously on the UI thread in response to a URL request, and are re-used where possible between navigations (i.e. refreshing a page). Because they run in a separate process and can exist before a corresponding renderer process has been created, special care is required to communicate with the renderer if reliable message passing is required.

WebUIController

A WebUIController is the brains of the operation, and is responsible for application-specific logic, setting up translations and resources, creating message handlers, and potentially responding to requests dynamically. In complex pages, logic is often split across multiple WebUIMessageHandlers instead of solely in the controller for organizational benefits.

A WebUIController is owned by a WebUI, and is created and set on an existing WebUI when the correct one is determined via URL inspection (i.e. chrome://settings creates a generic WebUI with a settings-specific WebUIController).

WebUIDataSource

WebUIMessageHandler

Because some pages have many messages or share code that sends messages, message handling is often split into discrete classes called WebUIMessageHandlers. These handlers respond to specific invocations from JavaScript.

So, the given C++ code:

void OvenHandler::RegisterMessages() {
  web_ui()->RegisterMessageHandler("bakeDonuts",
      base::Bind(&OvenHandler::HandleBakeDonuts, base::Unretained(this)));
}

void OvenHandler::HandleBakeDonuts(const base::ListValue* args) {
  AllowJavascript();

  CHECK_EQ(1u, args->GetSize());
  // JavaScript numbers are doubles.
  double num_donuts = args->GetList()[0].GetDouble();
  GetOven()->BakeDonuts(static_cast<int>(num_donuts));
}

Can be triggered in JavaScript with this example code:

$('bakeDonutsButton').onclick = function() {
  chrome.send('bakeDonuts', [5]);  // bake 5 donuts!
};

Browser (C++) → Renderer (JS)

WebUIMessageHandler::AllowJavascript()

A tab that has been used for settings UI may be reloaded, or may navigate to an external origin. In both cases, one does not want callbacks from C++ to Javascript to run. In the former case, the callbacks will occur when the Javascript doesn't expect them. In the latter case, sensitive information may be delivered to an untrusted origin.

Therefore each message handler maintains a boolean that describes whether delivering callbacks to Javascript is currently appropriate. This boolean is set by calling AllowJavascript, which should be done when handling a call from Javascript, because that indicates that the page is ready for the subsequent callback. (See design doc.) If the tab navigates or reloads, DisallowJavascript is called to clear the flag.

Therefore, before each callback from C++ to Javascript, the flag must be tested by calling IsJavascriptAllowed. If false, then the callback must be dropped. (When the flag is false, calling ResolveJavascriptCallback will crash. See design doc.)

Also beware of ABA issues: Consider the case where an asynchronous operation is started, the settings page is reloaded, and the user triggers another operation using the original message handler. The javascript_allowed_ boolean will be true, but the original callback should still be dropped because it relates to a operation that was discarded by the reload. (Reloading settings UI does not cause message handler objects to be deleted.)

Thus a message handler may override OnJavascriptDisallowed to learn when pending callbacks should be canceled.

In the JS:

window.onload = function() {
  app.initialize();
  chrome.send('startPilotLight');
};

In the C++:

void OvenHandler::HandleStartPilotLight(cont base::ListValue* /*args*/) {
  AllowJavascript();
  // CallJavascriptFunction() and FireWebUIListener() are now safe to do.
  GetOven()->StartPilotLight();
}

WebUIMessageHandler::CallJavascriptFunction()

When the browser process needs to tell the renderer/JS of an event or otherwise execute code, it can use CallJavascriptFunction().

void OvenHandler::OnPilotLightExtinguished() {
  CallJavascriptFunction("app.pilotLightExtinguished");
}

This works by crafting a string to be evaluated in the renderer. Any arguments to the call are serialized to JSON and the parameter list is wrapped with

// See WebUI::GetJavascriptCall() for specifics:
"functionCallName(" + argumentsAsJson + ")"

and sent to the renderer via a FrameMsg_JavaScriptExecuteRequest IPC message.

While this works, it implies that:

  • a global method must exist to successfully run the Javascript request
  • any method can be called with any parameter (far more access than required in practice)

^ These factors have resulted in less use of CallJavascriptFunction() in the webui codebase. This functionality can easily be accomplished with the following alternatives:

  • FireWebUIListener() allows easily notifying the page when an event occurs in C++ and is more loosely coupled (nothing blows up if the event dispatch is ignored). JS subscribes to notifications via cr.addWebUIListener.
  • ResolveJavascriptCallback and RejectJavascriptCallback are useful when Javascript requires a response to an inquiry about C++-canonical state (i.e. “Is Autofill enabled?”, “Is the user incognito?”)

WebUIMessageHandler::FireWebUIListener()

FireWebUIListener() is used to notify a registered set of listeners that an event has occurred. This is generally used for events that are not guaranteed to happen in timely manner, or may be caused to happen by unpredictable events (i.e. user actions).

Here‘s some example to detect a change to Chrome’s theme:

cr.addWebUIListener("theme-changed", refreshThemeStyles);

This Javascript event listener can be triggered in C++ via:

void MyHandler::OnThemeChanged() {
  FireWebUIListener("theme-changed");
}

Because it‘s not clear when a user might want to change their theme nor what theme they’ll choose, this is a good candidate for an event listener.

If you simply need to get a response in Javascript from C++, consider using cr.sendWithPromise() and ResolveJavascriptCallback.

WebUIMessageHandler::OnJavascriptAllowed()

OnJavascriptDisallowed() is a lifecycle method called in response to AllowJavascript(). It is a good place to register observers of global services or other callbacks that might call at unpredictable times.

For example:

class MyHandler : public content::WebUIMessageHandler {
  MyHandler() {
    GetGlobalService()->AddObserver(this);  // <-- DON'T DO THIS.
  }
  void OnGlobalServiceEvent() {
    FireWebUIListener("global-thing-happened");
  }
};

Because browser-side C++ handlers are created before a renderer is ready, the above code may result in calling FireWebUIListener before the renderer is ready, which may result in dropped updates or accidentally running Javascript in a renderer that has navigated to a new URL.

A safer way to set up communication is:

class MyHandler : public content::WebUIMessageHandler {
 public:
  MyHandler() : observer_(this) {}
  void OnJavascriptAllowed() override {
    observer_.Add(GetGlobalService());  // <-- DO THIS.
  }
  void OnJavascriptDisallowed() override {
    observer_.RemoveAll();  // <-- AND THIS.
  }
  ScopedObserver<MyHandler, GlobalService> observer_;  // <-- ALSO HANDY.

when a renderer has been created and the document has loaded enough to signal to the C++ that it's ready to respond to messages.

WebUIMessageHandler::OnJavascriptDisallowed()

OnJavascriptDisallowed is a lifecycle method called when it‘s unclear whether it’s safe to send JavaScript messsages to the renderer.

There's a number of situations that result in this method being called:

  • renderer doesn't exist yet
  • renderer exists but isn't ready
  • renderer is ready but application-specific JS isn't ready yet
  • tab refresh
  • renderer crash

Though it‘s possible to programmatically disable Javascript, it’s uncommon to need to do so.

Because there‘s no single strategy that works for all cases of a renderer’s state (i.e. queueing vs dropping messages), these lifecycle methods were introduced so a WebUI application can implement these decisions itself.

Often, it makes sense to disconnect from observers in OnJavascriptDisallowed():

void OvenHandler::OnJavascriptDisallowed() {
  scoped_oven_observer_.RemoveAll()
}

Because OnJavascriptDisallowed() is not guaranteed to be called before a WebUIMessageHandler's destructor, it is often advisable to use some form of scoped observer that automatically unsubscribes on destruction but can also imperatively unsubscribe in OnJavascriptDisallowed().

WebUIMessageHandler::RejectJavascriptCallback()

This method is called in response to cr.sendWithPromise() to reject the issued Promise. This runs the rejection (second) callback in the Promise's executor and any catch() callbacks in the chain.

void OvenHandler::HandleBakeDonuts(const base::ListValue* args) {
  AllowJavascript();
  if (!GetOven()->HasGas()) {
    RejectJavascriptCallback(args->GetList()[0],
                             base::StringValue("need gas to cook the donuts!"));
  }

This method is basically just a CallJavascriptFunction() wrapper that calls a global “cr.webUIResponse” method with a success value of false.

// WebUIMessageHandler::RejectJavascriptCallback():
CallJavascriptFunction("cr.webUIResponse", callback_id, base::Value(false),
                       response);

See also: ResolveJavascriptCallback

WebUIMessageHandler::ResolveJavascriptCallback()

This method is called in response to cr.sendWithPromise() to fulfill an issued Promise, often with a value. This results in runnings any fulfillment (first) callbacks in the associate Promise executor and any registered then() callbacks.

So, given this JS code:

cr.sendWithPromise('bakeDonuts').then(function(numDonutsBaked) {
  shop.donuts += numDonutsBaked;
});

Some handling C++ might do this:

void OvenHandler::HandleBakeDonuts(const base::ListValue* args) {
  AllowJavascript();
  double num_donuts_baked = GetOven()->BakeDonuts();
  ResolveJavascriptCallback(args->GetList()[0], num_donuts_baked);
}

Renderer (JS) → Browser (C++)

chrome.send()

When the JavaScript window object is created, a renderer is checked for WebUI bindings.

// RenderFrameImpl::DidClearWindowObject():
if (enabled_bindings_ & BINDINGS_POLICY_WEB_UI)
  WebUIExtension::Install(frame_);

If the bindings exist, a global chrome.send() function is exposed to the renderer:

// WebUIExtension::Install():
v8::Local<v8::Object> chrome = GetOrCreateChromeObject(isolate, context);
chrome->Set(gin::StringToSymbol(isolate, "send"),
            gin::CreateFunctionTemplate(
                isolate, base::Bind(&WebUIExtension::Send))->GetFunction());

The chrome.send() method takes a message name and argument list.

chrome.send('messageName', [arg1, arg2, ...]);

The message name and argument list are serialized to JSON and sent via the FrameHostMsg_WebUISend IPC message from the renderer to the browser.

// In the renderer (WebUIExtension::Send()):
render_frame->Send(new FrameHostMsg_WebUISend(render_frame->GetRoutingID(),
                                              frame->GetDocument().Url(),
                                              message, *content));
// In the browser (WebUIImpl::OnMessageReceived()):
IPC_MESSAGE_HANDLER(FrameHostMsg_WebUISend, OnWebUISend)

The browser-side code does a map lookup for the message name and calls the found callback with the deserialized arguments:

// WebUIImpl::ProcessWebUIMessage():
message_callbacks_.find(message)->second.Run(&args);

WebUI listeners are a convenient way for C++ to inform JavaScript of events.

Older WebUI code exposed public methods for event notification, similar to how responses to chrome.send() used to work. They both resulted in global namespace pollution, but it was additionally hard to stop listening for events in some cases. cr.addWebUIListener is preferred in new code.

Adding WebUI listeners creates and inserts a unique ID into a map in JavaScript, just like cr.sendWithPromise().

// addWebUIListener():
webUIListenerMap[eventName] = webUIListenerMap[eventName] || {};
webUIListenerMap[eventName][createUid()] = callback;

The C++ responds to a globally exposed function (cr.webUIListenerCallback) with an event name and a variable number of arguments.

// WebUIMessageHandler:
template <typename... Values>
void FireWebUIListener(const std::string& event_name, const Values&... values) {
  CallJavascriptFunction("cr.webUIListenerCallback", base::Value(event_name),
                         values...);
}

C++ handlers call this FireWebUIListener method when an event occurs that should be communicated to the JavaScript running in a tab.

void OvenHandler::OnBakingDonutsFinished(size_t num_donuts) {
  FireWebUIListener("donuts-baked", base::FundamentalValue(num_donuts));
}

JavaScript can listen for WebUI events via:

var donutsReady = 0;
cr.addWebUIListener('donuts-baked', function(numFreshlyBakedDonuts) {
  donutsReady += numFreshlyBakedDonuts;
});

cr.sendWithPromise()

cr.sendWithPromise() is a wrapper around chrome.send(). It's used when triggering a message requires a response:

chrome.send('getNumberOfDonuts');  // No easy way to get response!

In older WebUI pages, global methods were exposed simply so responses could be sent. This is discouraged as it pollutes the global namespace and is harder to make request specific or do from deeply nested code.

In newer WebUI pages, you see code like this:

cr.sendWithPromise('getNumberOfDonuts').then(function(numDonuts) {
  alert('Yay, there are ' + numDonuts + ' delicious donuts left!');
});

On the C++ side, the message registration is similar to chrome.send() except that the first argument in the message handler's list is a callback ID. That ID is passed to ResolveJavascriptCallback(), which ends up resolving the Promise in JavaScript and calling the then() function.

void DonutHandler::HandleGetNumberOfDonuts(const base::ListValue* args) {
  AllowJavascript();

  const base::Value& callback_id = args->GetList()[0];
  size_t num_donuts = GetOven()->GetNumberOfDonuts();
  ResolveJavascriptCallback(callback_id, base::FundamentalValue(num_donuts));
}

Under the covers, a map of Promises are kept in JavaScript.

The callback ID is just a namespaced, ever-increasing number. It's used to insert a Promise into the JS-side map when created.

// cr.sendWithPromise():
var id = methodName + '_' + uidCounter++;
chromeSendResolverMap[id] = new PromiseResolver;
chrome.send(methodName, [id].concat(args));

The corresponding number is used to look up a Promise and reject or resolve it when the outcome is known.

// cr.webUIResponse():
var resolver = chromeSendResolverMap[id];
if (success)
  resolver.resolve(response);
else
  resolver.reject(response);

This approach still relies on the C++ calling a globally exposed method, but reduces the surface to only a single global (cr.webUIResponse) instead of many. It also makes per-request responses easier, which is helpful when multiple are in flight.

Security considerations

Because WebUI pages are highly privileged, they are often targets for attack, 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 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.

See also

  • WebUI's C++ code follows the Chromium C++ styleguide.
  • WebUI's HTML/CSS/JS code follows the Chromium Web Development Style Guide
Powered by Gitiles| Privacy
标签: chrome chromium webui
最后更新:2020年09月10日

OvO

狐狸

点赞
< 上一篇
下一篇 >
最新 热点 随机
最新 热点 随机
brave编译打包时dump_syms报错Couldn't locate EXE or DLL file 使用Windows Kits创建PE 及精简镜像 Windows精简部署相关简易内容 APC UPS SUA1000ICH 踩坑记 TrueNAS SCALE虚拟机无法 Ping主机 TrueNas Scale libvirt-sock RDMA RoCE相关资料 Linux系统修改网卡名(eth0-3) Linux系统打开SRIOV 构建android内核时DTC工具中的多个定义错误 Windows 来宾系统提示“安全删除硬件” 修改jar的三种方法(反编译jar) 如何在 Debian 10上安装和配置 VNC Openwrt内SR-IOV网卡桥接问题 Linux下编译android 时报错loadlocale.c:130 windows 查看文件夹被那个进程占用 MongoDB中的多表关联 mongodb 学习记录
Linux下编译android 时报错loadlocale.c:130 iptables入门06(DNS端口53设置 Linux下查看SSD4K对齐EXT4分区开启Trim及验证的方法 Win下最爱效率利器:AutoHotKey 我的 fedora 調校手冊 让 Python 更加充分的使用 Sqlite3 几个常用 Linux 桌面/窗口管理器的内存占用对比 ZFS 调优指南 香蕉派关闭LED灯 android可禁用组件的通用规则 国内外几款好用的网络质量测试工具推荐 archlinux安装 npm install 警告 fsevents@1.0.14 世界,您好! Linux如何查看文件移动复制的进度 Python书籍推荐 Windows精简部署相关简易内容 Ubuntu缩放比例设置
标签聚合
https http e ssl linux git 路由 文件 网卡 下载 docker chrome com android 编译 密码

COPYRIGHT © 2020 狐窝. ALL RIGHTS RESERVED.

THEME KRATOS MADE BY VTROIS