tree: 0c05f68fc0b94f260776ce061341645061642557 [path history] [tgz]
  1. app/
  2. device_management_storage/
  3. images/
  4. mac/
  5. mojom/
  6. proto/
  7. telemetry_logger/
  8. test/
  9. branding.gni
  10. BUILD.gn
  11. buildflags.gni
  12. crash_client.cc
  13. crash_client.h
  14. crash_client_unittest.cc
  15. DEPS
  16. dm_client.cc
  17. dm_client.h
  18. dm_client_unittest.cc
  19. enterprise_companion.cc
  20. enterprise_companion.h
  21. enterprise_companion_branding.h.in
  22. enterprise_companion_client.cc
  23. enterprise_companion_client.h
  24. enterprise_companion_service.cc
  25. enterprise_companion_service.h
  26. enterprise_companion_service_stub.cc
  27. enterprise_companion_service_stub.h
  28. enterprise_companion_service_unittest.cc
  29. enterprise_companion_status.cc
  30. enterprise_companion_status.h
  31. enterprise_companion_status_unittest.cc
  32. enterprise_companion_version.h.in
  33. event_logger.cc
  34. event_logger.h
  35. event_logger_unittest.cc
  36. global_constants.cc
  37. global_constants.h
  38. installer.h
  39. installer_linux.cc
  40. installer_mac.mm
  41. installer_paths.h
  42. installer_paths_linux.cc
  43. installer_paths_mac.mm
  44. installer_paths_win.cc
  45. installer_posix.cc
  46. installer_posix.h
  47. installer_win.cc
  48. ipc_security.h
  49. ipc_security_linux.cc
  50. ipc_security_mac.cc
  51. ipc_security_win.cc
  52. ipc_support.cc
  53. ipc_support.h
  54. lock.cc
  55. lock.h
  56. main.cc
  57. OWNERS
  58. proxy_config_service.cc
  59. proxy_config_service.h
  60. proxy_config_service_unittest.cc
  61. README.md
  62. url_loader_factory_provider.cc
  63. url_loader_factory_provider.h
  64. url_loader_factory_provider_unittest.cc
chrome/enterprise_companion/README.md

Chrome Enterprise Companion App

Background

Chrome Enterprise Companion App (CECA) is an elevated daemon for MacOS and Windows that handles enterprise device management features which are not feasible to implement in the browser.

Originally, this project was developed to separate Chrome Browser Enterprise Cloud Management functionality from the ChromiumUpdater (//chrome/updater), allowing the development of related features to be decoupled from this high-risk surface.

Overview

CECA is a program that performs enrollment and policy fetching for cloud-managed Chrome browsers.

Design

Once installed, CECA operates as a daemon and is interacted with via the IPC interface it exposes. The server process hosts an engine that conducts most of the work, it is interacted with by client processes that issue commands to it.

Chrome Enterprise Companion App architecture diagram

CECA is installed system-wide and is launched by the Chromium Updater. When launched, the application attempts to acquire a single cross-process lock. If acquired, the application begins accepting incoming IPC connections and servicing RPCs from client processes. The application runs until it is requested to shut down via RPC.

RPC Interface

CECA’s functionality is driven by RPCs from client processes. Mojo provides the IDL, C++ bindings, and underlying IPC system. The interface definition is located in the mojom/ subdirectory.

CECA listens for incoming Mojo invitations on a platform-dependent interface (i.e. a named pipe on Windows, a mach port on Mac, or a socket on Linux). Clients are able to locate this interface via a statically defined name. Upon receiving an invitation, CECA may accept or reject it. If accepted, a Mojo connection is established and clients may perform RPCs. This process is abstracted by //components/named_mojo_ipc_server.

IPC Security

Although the scope of the RPC interface is limited, as CECA is an elevated process (running as SYSTEM on Windows, root on Mac and Linux), it is prudent that only authorized callers are allowed. The IPC interface is protected differently on each platform. On Windows, a security descriptor is configured on the interface’s named pipe allowing only access from SYSTEM. On Mac, an audit_token is used to verify that the caller has the same euid as the server. On Linux, the credentials of the calling process are read via SO_PEERCRED and the caller’s UID is compared to the server’s.

Policy Agent Functionality

CECA’s main functionality is to act as a policy agent for Chrome Browser Enterprise Cloud Management. This consists of two primary responsibilities: machine enrollment and policy fetching.

Background

Chrome Browser Enterprise Cloud Management allows system administrators to configure policies which control the behavior of the Chromium Updater and Browser. Administrators are provided enrollment tokens which can be used to authenticate a device as being managed by that organization. A policy agent uses the enrollment token to register the device with the Device Management Server (DM server). Upon enrollment, the DM Server provides the policy agent with a Device Management Token (DM token) that identifies the device and the organization it belongs to in future communication.

After enrollment, policy agents may request policies from DM Server, authenticating themselves via the DM token.

Implementation

CECA acts as a policy agent for the Chromium Updater and Chrome Browser. When the Chromium Updater performs its scheduled periodic tasks, it will request a policy fetch from CECA, launching the daemon if it is not already running. CECA will determine if the device is already enrolled via the presence of a DM token in storage. If not enrolled, CECA will look for an enrollment token in storage and attempt registration before continuing with the request. Next, CECA requests policies from DM Server, serializing the responses to a policy cache on disk which is subsequently read from by the Chromium Updater and Chrome Browser.

Device Management Storage

The enrollment token, DM token, and fetched policies are persisted on device. Token storage and the policy cache are collectively referred to as DM storage and are abstracted by device_management_storage/. The storage is implemented as follows:

Windows

The enrollment token is searched in the order:

  1. The EnrollmentToken REG_SZ value from HKLM\Software\Policies\{COMPANY_SHORTNAME}\CloudManagement

  2. The CloudManagementEnrollmentToken REG_SZ value from HKLM\Software\Policies\{COMPANY_SHORTNAME}\{BROWSER_NAME}

  3. The CloudManagementEnrollmentToken REG_SZ value from {CLIENTSTATE}\{UpdaterAppID} (the runtime enrollment token)

  4. The CloudManagementEnrollmentToken REG_SZ value from {CLIENTSTATE}\{430FD4D0-B729-4F61-AA34-91526481799D} (the legacy runtime enrollment token)

The DM token is stored in:

  • The dmtoken REG_BINARY value at path: HKLM\Software\WOW6432Node\{COMPANY_SHORTNAME}\Enrollment\

  • The dmtoken REG_BINARY value at path: HKLM64\Software\{COMPANY_SHORTNAME}\{BROWSER_NAME}\Enrollment\. This is for backward compatibility.

The EnrollmentMandatory REG_DWORD value is also read from HKLM\Software\Policies\{COMPANY_SHORTNAME}\CloudManagement.

Mac

The enrollment token is searched in the order:

  1. Managed Preference value with key CloudManagementEnrollmentToken in domain {MAC_BROWSER_BUNDLE_IDENTIFIER}.

  2. Managed Preference value with key EnrollmentToken in domain {MAC_BROWSER_BUNDLE_IDENTIFIER}.

File /Library/{COMPANY_SHORTNAME}/{BROWSER_NAME}/CloudManagementEnrollmentToken.

The DM token is stored in: /Library/Application Support/{COMPANY_SHORTNAME}/CloudManagement.

Linux

The enrollment token is stored in: /opt/{COMPANY_SHORTNAME}/{PRODUCT_FULLNAME}/CloudManagementEnrollmentToken

The DM token is stored in: /opt/{COMPANY_SHORTNAME}/{PRODUCT_FULLNAME}/CloudManagement

Installation

CECA bundles an installer into its executable which can be invoked via the --install command-line flag. When the installer launches, it instructs the currently running server process to shutdown via RPC, if one is running. It then acquires the cross-process lock before copying itself to the installation directory.

On Windows the application is distributed for both x86 and x86_64. If an existing installation for a different architecture is present, the installer will remove it before installing itself. The application is installed to %PROGRAMFILES% or %PROGRAMFILESX86% under {COMPANY_SHORTNAME}\{PRODUCT_FULLNAME}. E.g. C:\Program Files\Google\ChromeEnterpriseCompanion.

On Mac the application is distributed via a PKG installer which bundles the application binary and a postinstall script which launches CECA with the --install flag. The application is installed to /Library/Application Support/{COMPANY_SHORTNAME}/{PRODUCT_FULLNAME}.

On Linux the application is installed to /opt/{COMPANY_SHORTNAME_LOWERCASE}/{PRODUCT_FULLNAME_DASHED_LOWERCASE}.

CECA similarly bundles an uninstaller via the --uninstall command-line flag. When the Chromium Updater is uninstalled, CECA is too.

Networking

CECA requires networking for its communication with the DM server and transmission of telemetry. For compatibility with existing code in //components/policy/, the Chromium network stack is used.

Special care is taken to ensure that CECA can navigate through mandatory proxy configurations. On Windows, the logged-in user is guessed via the owner of explorer.exe and impersonated for the lifetime of the networking thread. On Mac, the logged-in user is guessed via querying the System Configuration dynamic store for console users and networking is delegated to a subprocess launched in their bootstrap namespace (i.e. via launchctl asuser).

Event Logging

CECA records information about the health of the service and transmits it to a remote logging endpoint over HTTPS. This information is used to monitor and improve the application. The information transmitted is defined by enterprise_companion_event.proto. Upon the first logging transmission, the server will respond with a logging cookie which identifies the device in future transmissions. This cookie is persisted in a file named logging_cookie in the application’s install directory.

Crash Reporting

CECA uses Crashpad for crash reporting. Each CECA process spawns a crash handler child process. CECA may upload its crash reports if and only if the Chromium Updater is permitted to send usage stats. CECA may attach its log file to the crash reports it uploads. Each crash handler process is capable of uploading crashes.

Testing

CECA defines a unit test target (enterprise_companion_tests) and an integration test target (enterprise_companion_integration_tests). Running the unit tests does not require any special permissions and the suites may be run concurrently. The integration tests must be run by an elevated user (an Administrator on Windows, root on Mac or Linux) and are executed serially.

The integration tests operate on a CECA binary instrumented for testing. The application-under-test binary’s target is enterprise_companion_test. The test binary allows for global constants to be overridden via an overrides.json file placed in the installation directory. This allows the integration tests to provide values such as the DM server URL, event logger timeout, and named pipe security descriptor. Additionally, the test binary allows alternative cryptographic keys to be used for validating responses from the DM server, thus allowing the integration tests to correctly mock responses.