This is the functional specification for Chromium Updater. It describes the externally observable behavior of the updater, including APIs and UI.
The metainstaller (UpdaterSetup) is a small executable that contains a compressed copy of the updater as a resource, extracts it, and triggers installation of the updater / an app. The metainstaller is downloaded by the user and can be run from any directory.
The size of the metainstaller is less than 1500KiB.
The metainstaller may have a tag attached to it. The tag is a piece of unsigned data from which the metainstaller extracts the ID of the application to be installed, along with the application's brand code, usage-stats opt-in status, and any additional parameters to be associated with the application.
On Windows, the tag is embedded in one of the certificates in the metainstaller PE. The tag is supported for both EXE and MSI formats.
The brand code is a string of up to 4 characters long. The brand code is persisted during the install, over-installs, and updates.
TODO(crbug.com/1328903) - document the rest of the tag format.
The metainstaller parses its tag and re-launches itself at high integrity if installing an application with needsadmin=true or needsadmin=prefers.
Metainstaller localization presents the metainstaller UI with the user's preferred language on the current system. Every string shown in the UI is translated.
The bundle installer allows installation of more than one application. The bundle installer is typically used in software distribution scenarios.
TODO(crbug.com/1035895): Document bundled installers.
TODO(crbug.com/1035895): Document the standalone installer, including building a standalone installer for a given application.
Applications on macOS frequently install via “drag-install”, and then install the updater using a standalone installer on the application's first-run. The updater app can be embedded in a macOS application bundle as a helper and then invoked with appropriate command line arguments to install itself.
TODO(crbug.com/1327497) - document.
The updater is installed in one of the following modes (or scopes):
Per-machine and per-user instances of the updater can run side by side.
Depending on the scope, the updater is installed at:
%LOCAL_APP_DATA%\{COMPANY}\{UPDATERNAME}\{VERSION}\updater.exe%PROGRAM_FILES%\{COMPANY}\{UPDATERNAME}\{VERSION}\updater.exe~/Library/{COMPANY}/{UPDATERNAME}/{VERSION}/{UPDATERNAME}.app/Library/{COMPANY}/{UPDATERNAME}/{VERSION}/{UPDATERNAME}.appThe updater's functionality is split between several processes. The mode of a process is determined by command-line arguments:
OfflineManifest.gup or <app-id>.gup. The file contains the update check response in XML format.--handoff above.update, the server answers RPC messages on the UpdateService interface only.update-internal, the server answers RPC messages on the UpdateServiceInternal interface only.SERVICE_AUTO_START) or when CoCreate is called on one of several CLSIDs that the server supports.ServiceMain by the SCM when CoCreate is called on one of several CLSIDs that the server supports. This is used for:If none of the above arguments are set, the updater exits with an error.
Additionally, the mode may be modified by combining it with:
The updater communicates with update servers using the Omaha Protocol.
It is not possible to MITM the updater even if the network (including TLS) is compromised. The integrity of the client-server communication is guaranteed by the Client Update Protocol (CUP).
The updater does not retry an update check that transacted with the backend, even if the response was erroneous (misformatted or unparsable), until the next normally scheduled update check.
The updater sends DoS mitigation headers in requests to the server.
When the server responds with an X-Retry-After header, the client does not issue another update check until the specified period has passed (maximum 24 hours).
X-Retry-After was received in the background case, a foreground update is still permitted (but not if it was received in response to a foreground update).TODO(crbug.com/1329868) - implement the algorithm. The updater scatters its routine updates:
UpdateCheckMs feature.DisableUpdateAppsHourlyJitter in UpdateDev.UpdateDev value can set the jitter time to a constant value, in the same [0, 60) seconds range. The name of the value is AutoUpdateJitterMs and it represents the time to wait before an update check is made in milliseconds.TODO(crbug.com/1329328) - document the client responsibilities.
The updater accepts updates packaged as CRX₃ files. All files are signed with a publisher key. The corresponding public key is hardcoded into the updater.
The updater handles the installation of new applications. The updater can download, install, and update an applications when the application is running.
One or more applications can be installed at once, as a bundle.
Before installing, the integrity of the payload if verified. The payloads are stored in secure locations of the file system for per-system installs.
Considering network connectivity, there are two scenarios for installing an application:
An online install is done with a metainstaller. Every time an online installer runs, it sends an install event ping. The update check and the install event ping have the same session id. The install ping is lost if the network is unreachable for any reason, or the program has crashed.
This type of installs is done with a [standalone/offline installer] (#Standalone-Installer). This is an installer which embeds all data required to install the application, including the payload and various configuration data needed by the application setup. Such an install completes even if a network connection is not available.
There are a couple of scenarios where the standalone/offline installer is used:
installdataindex provides a mechanism to specify configuration data which is passed to the application installer.
TODO(crbug.com/1035895): Document UI/UX
If the installation fails, the updater shows an error message with a “Help” button. Clicking the help button opens a web page in the user's default browser. The page is opened with a query string: ?product={AppId}&errorcode={ErrorCode}.
TODO(crbug.com/1139014): Document OEM.
The installsource identifies the originator of an install. It is provided on the command line of the metainstaller. TODO(crbug.com/1327491) - is this needed? If yes, document the algorithm.
As part of installing or updating an application, the updater executes the application's installer. The API for the application installer is platform- specific.
The macOS API is defined here.
TODO(crbug.com/1035895): Document Windows installer APIs
To maintain backwards compatibility with Omaha and Keystone, the updater installs small versions of those programs that implement a subset of their APIs.
The updater installs a Keystone-like application that contains these shims:
Both the Keystone and Keystone Agent executables simply exit immediately when run.
The ksinstall executable expects to be called with --uninstall and possibly --system. If so, it deletes the Keystone shim (but not the overall updater) from the file system. Otherwise, it exits with a non-zero exit code.
The ksadmin shim is frequently called by applications and handles a variety of command lines:
Some of these actions accept parameters:
On Windows, the updater replaces Omaha's files with a copy of the updater, and keeps the Omaha registry entry (CLIENTS/{430FD4D0-B729-4F61-AA34-91526481799D}) up-to-date with the latest pv value. Additionally, the updater replaces the Omaha uninstall command line with its own.
Enterprise policies can prevent the installation of applications:
Refer to chrome/updater/protos/omaha_settings.proto for more details.
needsadminneedsadmin is one of the install parameters that can be specified for first installs via the metainstaller tag. needsadmin is used to indicate whether the application needs admin rights to install.
For example, here is a command line for the Updater on Windows that includes:
UpdaterSetup.exe --install --tag="appguid=YourAppID&needsadmin=False"
In this case, the updater client understands that the application installer needs to install the application on a per-user basis for the current user.
needsadmin has the following supported values:
true: the application supports being installed systemwide and once installed, is available to all users on the system.false: the application supports only user installs.prefers: the application installation is first attempted systemwide. If the user refuses the UAC prompt however, the application is then only installed for the current user. The application installer needs to be able to support the installation as system, or per-user, or both modes.installdataindexinstalldataindex is one of the install parameters that can be specified for first installs on the command line or via the metainstaller tag.
For example, here is a typical command line for the Updater on Windows:
UpdaterSetup.exe /install "appguid=YourAppID&appname=YourAppName&needsadmin=False&lang=en&installdataindex =verboselog"
In this case, the updater client sends the installdataindex of verboselog to the update server.
This is how a JSON request from the updater client may look like:
{
"request":{
"@os":"win",
"@updater":"updater",
"acceptformat":"crx3",
"app":[
{
"appid":"YourAppID",
"data":[
{
"index":"verboselog",
"name":"install"
}
],
"enabled":true,
"installsource":"ondemand",
"ping":{
"r":-2
},
"updatecheck":{
"sameversionupdate":true
},
"version":"0.1"
}
],
"arch":"x86",
"dedup":"cr",
"domainjoined":true,
"hw":{
"avx":true,
"physmemory":32,
"sse":true,
"sse2":true,
"sse3":true,
"sse41":true,
"sse42":true,
"ssse3":true
},
"ismachine":false,
"lang":"en-US",
"nacl_arch":"x86-64",
"os":{
"arch":"x86_64",
"platform":"Windows",
"version":"10.0.19042.1586"
},
"prodversion":"101.0.4949.0",
"protocol":"3.1",
"requestid":"{6b417770-1f68-4d52-8843-356760c84d33}",
"sessionid":"{37775211-4487-48d5-845d-35a1d71b03bc}",
"updaterversion":"101.0.4949.0",
"wow64":true
}
}
The server retrieves the data corresponding to installdataindex=verboselog and returns it back to the updater client.
This is how a JSON response from the update server may look like:
"response":{
"protocol":"3.1",
"app":[
{"appid":"12345",
"data":[{
"status":"ok",
"name":"install",
"index":"verboselog",
"#text":"{\"logging\":{\"verbose\":true}}"
}],
"updatecheck":{
"status":"ok",
"urls":{"url":[{"codebase":"http://example.com/"},
{"codebasediff":"http://diff.example.com/"}]},
"manifest":{
"version":"1.2.3.4",
"prodversionmin":"2.0.143.0",
"run":"UpdaterSetup.exe",
"arguments":"--arg1 --arg2",
"packages":{"package":[{"name":"extension_1_2_3_4.crx"}]}}
}
}
]
}
The updater client writes this data to a temporary file in the same directory as the application installer. This is for security reasons, since writing the data to the temp directory could potentially allow a man-in-the-middle attack.
The updater client provides the temporary file as a parameter to the application installer.
Let's say, as shown above, that the update server responds with these example file contents:
{"logging":{"verbose":true}}
The updater client creates a temporary file, say c:\my path\temporaryfile.dat (assuming the application installer is running from c:\my path\YesExe.exe), with the following file contents:
\xEF\xBB\xBF{"logging":{"verbose":true}}
and then provide the file as a parameter to the application installer:
"c:\my path\YesExe.exe" --installerdata="c:\my path\temporaryfile.dat"
EF BB BF.INSTALLERDATA="pathtofile".--installerdata="pathtofile".INSTALLERDATA="pathtofile".There is no limit for the number of retries to update an application if the update fails repeatedly.
The client records the cohort, cohortname, and cohorthint values from the server in each update response (even if there is no-update) and reports them on subsequent update checks.
TODO(crbug.com/1035895): Document differential updates.
The updater runs periodic tasks every hour, checking its own status, detecting application uninstalls, and potential checking for updates (if it has been at least 5 hours since the last update check).
For internal users, the period of the scheduled tasks is 30 minutes.
TODO(crbug.com/1328943) - document the jitter for starting updates.
The update tasks are scheduled using the OS task scheduler.
The time resolution for tasks is 1 minute. Tasks are set to run 5 minutes after they've been created.
TODO(crbug.com/1328935) - built in task scheduler as a failover mechanism
TODO(crbug.com/1035895): Does the updater run at user login on Windows?
The updater exposes an RPC interface for any user to trigger an update check. The update can be triggered by any user on the system, even in the system scope.
The caller provides the ID of the item to update, the install data index to request, the priority, whether a same-version update (repair) is permitted, and callbacks to monitor the progress and completion of the operation.
The interface provides the version of the update, if an update is available.
Regardless of the normal update check timing, the update check is attempted immediately.
The updater exposes an RPC interface for users to register an application with the updater. Unlike on-demand updates, cross-user application registration is not permitted.
If the application is already installed, it is registered with the version present on disk. If it has not yet been installed, a version of 0 is used.
Applications can report whether they are actively used or not through the updater. Update servers can then aggregate this information to produce user counts.
Software can be installed or updated only if the user has agreed to the Terms of Service. The updater only runs if the user has accepted the ToS for at least one application.
TODO(crbug.com/1035895): Document EULA signals.
The updater may upload its crash reports and send usage stats if and only if any piece of software it manages is permitted to send usage stats.
HKCU\SOFTWARE\{Company}\Update\ClientState\{APPID} → usagestats (DWORD): 1 or HKLM\SOFTWARE\{Company}\Update\ClientStateMedium\{APPID} → usagestats (DWORD): 1IsUploadEnabled to true for a crashpad database maintained in a “Crashpad” subdirectory of their application data directory.TODO(crbug.com/1035895): Document relevant enterprise policies.
ADMX templates are provided.
When the updater installs an application (an installer is run) it sends an event with "eventtype": 2 indicating the outcome of installation. The updater does not send such a ping for its own installation.
When the updater updates an application (including itself) it sends an event with "eventtype": 3 indicating the outcome of update operation.
When the updater detects the uninstallation of an application, it sends an event with "eventtype": 4 to notify the server of the uninstallation.
When the updater attempts to download a file, it sends an event with "eventtype": 14 describing the parameters and outcome of the download.
Multiple events associated with an update session are bundled together into a single request.
There could be multiple URLs for a given application payload. The URLs are tried in the order they are returned in the update response.
The integrity and authenticity of the payload is verified.
There is no download cache. Payloads are re-downloaded for applications which fail to install.
TODO(crbug.com/1035895): Document updater crash reporting.
The feature allows installed products to pre-register and later run command lines in the format c:\path-to-exe\exe.exe {params} (elevated for system applications). {params} is optional and can also include replaceable parameters substituted at runtime.
The program path is always an absolute path. Additionally, for system applications, the program path is also a child of %ProgramFiles% or %ProgramFiles(x86)%. For instance:
c:\path-to-exe\exe.exe is an invalid path."c:\Program Files\subdir\exe.exe" is a valid path."c:\Program Files (x86)\subdir\exe.exe" is also a valid path.App commands are registered in the registry with the following formats:
Update\Clients\{`app_id`}\Commands\`command_id`
REG_SZ "CommandLine" == {command format}
Update\Clients\{`app_id`}
REG_SZ `command_id` == {command format}
Example {command format}: c:\path-to\echo.exe %1 %2 %3 StaticParam4
As shown above, {command format} needs to be the complete path to an executable followed by optional parameters.
Once registered, commands may be invoked using the execute method in the IAppCommandWeb interface.
interface IAppCommandWeb : IDispatch {
// Use values from the AppCommandStatus enum.
[propget] HRESULT status([out, retval] UINT*);
[propget] HRESULT exitCode([out, retval] DWORD*);
[propget] HRESULT output([out, retval] BSTR*);
HRESULT execute([in, optional] VARIANT parameter1,
[in, optional] VARIANT parameter2,
[in, optional] VARIANT parameter3,
[in, optional] VARIANT parameter4,
[in, optional] VARIANT parameter5,
[in, optional] VARIANT parameter6,
[in, optional] VARIANT parameter7,
[in, optional] VARIANT parameter8,
[in, optional] VARIANT parameter9);
};
Here is a code snippet a client may use, with error checking omitted:
var bundle = update3WebServer.createAppBundleWeb(); bundle.initialize(); bundle.createInstalledApp(appGuid); var app = bundle.appWeb(0); cmd = app.command(command); cmd.execute();
Parameters placeholders (%1-%9) are filled by the numbered parameters in IAppCommandWeb::execute. Placeholders without corresponding parameters cause the execution to fail.
Clients may poll for the execution status of commands that they have invoked by using the status method of IAppCommandWeb. When the status is COMMAND_STATUS_COMPLETE, the exitCode method can be used to get the process exit code.
%ProgramFiles% for security, since it runs elevated.% followed by a digit. Literal % characters are escaped by doubling them.For example, if parameters to IAppCommandWeb::execute are AA and BB respectively, a command format of: echo.exe %1 %%2 %%%2 becomes the command line echo.exe AA %2 %BB
On Mac and Linux, if the application was registered with an existence path checker and no file at that path exists (or if the file at that path is owned by another user), the updater considers the application uninstalled, sends the ping, and stops trying to keep it up to date.
On Windows, if the ClientState entry for for the application is deleted, the app is considered uninstalled.
On Windows, the updater registers a “UninstallCmdLine” under the Software\ {Company}\Updater key. This command line can be invoked by application uninstallers to cause the updater to update its registrations. The updater also checks for uninstallations in every periodic task execution.
When the last registered application is uninstalled, the updater uninstalls itself immediately. The updater also uninstalls itself if it has started 24 times but never had a product (besides itself) registered for updates.
The updater uninstaller removes all updater files, registry keys, RPC hooks, scheduled tasks, and so forth from the file system, except that it leaves a small log file in its data directory.
Building the updater produces both a production-ready updater executable and a version of the executable used for the purposes of testing. The test executable is identical to the production one except that it allows cetain constants to be overridden by the execution environment:
url: Update check & ping-back URL.use_cup: Whether CUP is used at all.cup_public_key: An unarmored PEM-encoded ASN.1 SubjectPublicKeyInfo with the ecPublicKey algorithm and containing a named elliptic curve.group_policies: Allows setting group policies, such as install and update policies.Windows: these overrides exist in registry, under HKLM\Software\{Company}\Update\Clients\ClientState\UpdateDev.
macOS: these overrides exist in user defaults, in the {MAC_BUNDLE_IDENTIFIER} suite. For system installs, the defaults are those of the root user.
TODO(crbug.com/1035895): Document tagging tools.