This document describes the Architecture for the third-party Telemetry Extensions Platform.
The Telemetry Extension Platform provides means for accessing Telemetry and Diagnostics data of a ChromeOS device. The Telemetry Extension Platform consists of 2 parts:
A Chrome headless extension for API access, background data gathering and processing (Telemetry Extension)
A companion Progressive Web App (PWA) to show UI to a user.
The Telemetry Extension uses Manifest V3 to benefit from using Service Workers instead of a background script. Only when the PWA is open, the Telemetry Extension periodically receives user driven requests from the PWA to fetch telemetry and run diagnostics routines. The PWA also has its own launch icon and it doesn’t have direct access to the telemetry and diagnostics API, but it communicates with the Telemetry Extension using message passing.
This image shows an overview of the architecture.
The Telemetry Extension's role is to handle requests from the UI and gather telemetry and diagnostics data. The Telemetry Extension has a service worker and does not have a launch icon. For this specific situation a new Chrome extension type was declared, the ChromeOS System extension. In a ChromeOS System extension, the service worker has direct access to normal web APIs. Most of the common Chrome Extension APIs are disabled (except chrome.runtime to communicate with the PWA) and access to the Telemetry API is granted either directly through os. or via DPSL.js the recommended way of using the API). Please note that each extension ID needs to be allowlisted by Google in the Chrome codebase to have access to APIs.
It is the role of the PWA to show UI to the user and communicate with the Telemetry Extension to get telemetry and diagnostics data. The PWA has a launch icon, UI, and access to web APIs.
The Company Products defined in Exhibit A will be granted the ability to call the Chrome OS Telemetry Extension APIs using the methods defined here.
(Update: Google provides clients with the ability to query the API by calling chrome.os.* directly. Migration guide can be found here.) DPSL.js stands for Diagnostic Processor Support Library for Javascript, it’s a JS wrapper around the underlying Telemetry Extensions APIs. It offers an abstracted way for querying the API and is developed by Google. The library is hosted on Github and published to npm, please refer to the documentation. These tables show an overview of all available API functions.
A Chrome extension and a PWA can communicate with each other using message passing. Only PWAs can initiate communication because a PWA is running only when the user launches it. The following example shows how the communication between the two components could look like. The PWA uses chrome.runtime.sendMessage to communicate with the Chrome extension:
// PWA code // The ID of the extension we want to talk to. var editorExtensionId = "abcdefghijklmnoabcdefhijklmnoabc"; // Make a simple request: chrome.runtime.sendMessage( /* extensionId */ editorExtensionId, /* message in JSON */ {openUrlInEditor: url}, /* callback */ function(response) { if (!response.success) handleError(url); });
The extension side can handle incoming requests as follows:
// Extension code chrome.runtime.onMessageExternal.addListener( function(request, sender, sendResponse) { if (sender.url == blocklistedWebsite) return; // don't allow this web page access if (request.openUrlInEditor) openUrl(request.openUrlInEditor); });
For an overview of all exposed function under chrome.os.telemetry and chrome.os.diagnostics, please visit this page. Some telemetry data requires special permissions to be accessed:
VpdInfo.serialNumber requires additional permission: “os.telemetry.serial_number” with string “Read Chrome OS device and component serial numbers”
OemData.oemData requires additional permission: “os.telemetry.serial_number” with string “Read Chrome OS device and component serial numbers”
Batteryinfo.serialNumber requires additional permission: “os.telemetry.serial_number” with string “Read Chrome OS device and component serial numbers”
MAC Address in InternetConnectivity requires additional permission: “os.telemetry.network_info” with string “Read ChromeOS network information”
In order for a Chrome extension to have access to telemetry and diagnostics APIs, the following requirements need to be satisfied:
The user must be either:
a. managed and the Telemetry extension was force-installed via policy, or
b. The user is the device owner (the first user of the device).
c. The user is in Shimless RMA flow.
The PWA UI associated with the Telemetry extension must be opened for the extension to have access to APIs.
The device hardware must belong to the OEM associated with the Telemetry extension (e.g. HP Support Assist only runs on HP devices).
Only an allowlisted extension ID can access Telemetry Extension APIs. Each allowlisted extension ID can be connected to one PWA origin. It is mandatory to declare one entry in externally_connectable.matches list. An example can be found here:
"externally_connectable": { "matches": ["https://third-party.com/*"] }
The externally_connectable key determines whether or not a website (or other Chrome extension) can initiate communication with a Telemetry Extension. A Telemetry Extension can always choose to communicate with sites indirectly via content scripts injected into a tab. Please note that no matter what, extensions should always validate and sanitize messages. An extension should never have a listener that evals random code sent in a message. This helps mitigate the damage a sender (whether untrusted or compromised) may be able to perform. This is also critical because other Chrome extensions may be running on the site that tries to connect to the Telemetry Extension and can initiate that connection.
Support for overriding the PWA origin and manufacturer to use while development and testing was added in version M98 and M105. The PWA origin option overrides the allowlisted PWA origin while the manufacturer overrides the actual device manufacturer fetched from cros_config. Here is what you need to do in order to access the flags (you can skip to step 3 if you already have read/write access to rootfs):
On your testing device, make sure you enable developer mode.
Make sure you have write access to rootfs, if not run /usr/share/vboot/bin/make_dev_ssd.sh --remove_rootfs_verification
Open /etc/chrome_dev.conf and add these lines to the end:
--telemetry-extension-pwa-origin-override-for-testing=<new-pwa-origin> --telemetry-extension-manufacturer-override-for-testing=<new-manufacturer>
After following those steps, the new PWA and the Telemetry Extension should be able to communicate via message passing.
The device serial number can be accessed using dpsl.telemetry.getVpdInfo() and the battery serial number is accessed using dpsl.telemetry.getOemDataInfo(). Because of the sensitive nature of serial numbers, this information is guarded using a runtime permission: os.telemetry.serial_number. For technical limitation, this is now a mandatory permission, meaning the chrome extension’s manifest.json needs to include it in the permissions list in order to have access to serial numbers.
The Telemetry Extension enforces https as the protocol for communicating with the PWA. During development, this leads to a rejection of a PWA hosted under http://localhost/ or another origin that does not have a valid certificate that is trusted by Chrome. The following steps describe how to set up a secure development PWA under crostini (Linux on ChromeOS). For this guide we assume localhost as the host. Please note that the openssl commands for this guide were taken from this blog post.
Settings>Developers>Linux development environment) and make sure that “My Files” are shared with Linux (right click on the “My Files” folder and then select “Share with Linux”).mnt/chromeos/.. and run the following command to create a root certificate:openssl genrsa -out CA.key -des3 2048
openssl req -x509 -sha256 -new -nodes -days 3650 -key CA.key -out CA.pem
localhost.ext with the following content:authorityKeyIdentifier = keyid,issuer basicConstraints = CA:FALSE keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment subjectAltName = @alt_names [alt_names] DNS.1 = localhost IP.1 = 127.0.0.1
openssl genrsa -out localhost.key -des3 2048 openssl req -new -key localhost.key -out localhost.csr
openssl x509 -req -in localhost.csr -CA ../CA.pem -CAkey ../CA.key -CAcreateserial -days 3650 -sha256 -extfile localhost.ext -out localhost.crt
openssl rsa -in localhost.key -out localhost.decrypted.key
You can now use the generated key and certificate for localhost in your development environment. In order for Chrome to trust the key used by your application, you need to add the CA root certificate to Chrome. Under Settings>Privacy and security>Security>Manage certificates you are able to set the root CA. Just select the Authorities tab and click Import. Select the generated CA.pem file and click open. Now your Chrome instance and testing environment trust each other.
Due to the powerful nature of this API there are limits on how the data can be utilized:
This API can only be used to receive telemetry data and diagnostic information from ChromeOS-based devices to provide Customer Support Services.
This API will only be used, access or otherwise process personal data or device identifiers at the Customer’s express direction in each instance.
Company will not access the ChromeOS API on an ongoing basis, or at recurring intervals, without express direction by the Customer.
Company will not store (on device or server), or use for geolocation purposes, the device SSID or BSSID.
Company will not use data obtained through the API for marketing purposes.
Company will provide and adhere to a privacy policy that clearly and accurately describes to Customers what data is collected and how the data is used and shared.
For information around configuration of certain cros-config values please visit:
Q: I found a bug, how do I report it?
A: Thank you for your contribution. Please create a new bug with the description and logs (if possible) on our bugtracker. You need a partner account to do that.
Q: Have a question?
A: Please reach out to [email protected].