// Copyright 2018 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Private API for reporting Chrome browser status to admin console.
namespace enterprise.reportingPrivate {
// Invoked by <code>UploadChromeDesktopReport</code> when the upload is
// finished.
// Also Invoked by <code>setDeviceData</code> when data is stored.
[platforms = ("win", "mac", "linux")]
callback DoneCallback = void();
// Invoked by <code>getDeviceId</code> to return the ID.
[platforms = ("win", "mac", "linux")]
callback GetDeviceIdCallback = void(DOMString id);
// Invoked by <code>getPersistentSecret</code> to return the secret.
[platforms = ("win", "mac")]
callback GetPersistentSecretCallback = void(ArrayBuffer secret);
// Invoked by <code>getDeviceDataCallback</code> to return the device data.
[platforms = ("win", "mac", "linux")]
callback GetDeviceDataCallback = void(ArrayBuffer data);
// Possible states a particular device setting can be in.
[platforms = ("win", "mac", "linux")]
enum SettingValue { UNKNOWN, DISABLED, ENABLED };
// Device info fields returned by the getDeviceInfo API.
[platforms = ("win", "mac", "linux")]
dictionary DeviceInfo {
DOMString osName;
DOMString osVersion;
DOMString deviceHostName;
DOMString deviceModel;
DOMString serialNumber;
SettingValue screenLockSecured;
SettingValue diskEncrypted;
DOMString[] macAddresses;
DOMString? windowsMachineDomain;
DOMString? windowsUserDomain;
DOMString securityPatchLevel;
// This value is only returned on Windows for now.
SettingValue? secureBootEnabled;
};
// Invoked by <code>getDeviceInfo</code> to return device information.
[platforms = ("win", "mac", "linux")]
callback GetDeviceInfoCallback = void(DeviceInfo deviceInfo);
// Possible states for the EnterpriseRealTimeUrlCheckMode policy.
enum RealtimeUrlCheckMode { DISABLED, ENABLED_MAIN_FRAME };
// Possible states for the SafeBrowsingProtectionLevel policy.
enum SafeBrowsingLevel { DISABLED, STANDARD, ENHANCED };
// Possible states for the PasswordProtectionWarningTrigger policy
enum PasswordProtectionTrigger {
PASSWORD_PROTECTION_OFF,
PASSWORD_REUSE,
PHISHING_REUSE,
POLICY_UNSET
};
// Context info fields returned by the getContextInfo API.
dictionary ContextInfo {
DOMString[] browserAffiliationIds;
DOMString[] profileAffiliationIds;
DOMString[] onFileAttachedProviders;
DOMString[] onFileDownloadedProviders;
DOMString[] onBulkDataEntryProviders;
DOMString[] onPrintProviders;
RealtimeUrlCheckMode realtimeUrlCheckMode;
DOMString[] onSecurityEventProviders;
DOMString browserVersion;
SafeBrowsingLevel safeBrowsingProtectionLevel;
boolean siteIsolationEnabled;
boolean builtInDnsClientEnabled;
PasswordProtectionTrigger passwordProtectionWarningTrigger;
boolean chromeRemoteDesktopAppBlocked;
boolean? thirdPartyBlockingEnabled;
SettingValue osFirewall;
DOMString[] systemDnsServers;
DOMString? enterpriseProfileId;
};
// Invoked by <code>getContextInfo</code> to return context information.
callback GetContextInfoCallback = void(ContextInfo contextInfo);
// The status passed to the callback of <code>getCertificate</code> to
// indicate if the required policy is set.
enum CertificateStatus { OK, POLICY_UNSET };
// The certificate, if one meets the requirements, returned by the
// $(ref:getCertificate) API. <code>encodedCertificate</code> will be
// the DER encoding (binary encoding following X.690 Distinguished Encoding
// Rules) of the X.509 certificate.
dictionary Certificate {
CertificateStatus status;
ArrayBuffer? encodedCertificate;
};
// Invoked by <code>getCertificate</code> to return the selected certificate.
callback CertificateCallback = void(Certificate certificate);
// Captures the type of event so it can be associated with user or device in
// Chrome for reporting purposes
[platforms = ("chromeos", "lacros")]
enum EventType { DEVICE, USER };
// Composite object that captures the information we need to report events.
// Some fields like the record and priority are serialized to avoid any
// dependency on proto definitions here, given the fact that they will likely
// change in the future. These will be deserialized and validated in Chrome.
[platforms = ("chromeos", "lacros")]
dictionary EnqueueRecordRequest {
// Serialized record data binary based on the proto definition in
// //components/reporting/proto/synced/record.proto.
[instanceOf=Uint8Array] ArrayBufferView recordData;
// Serialized priority based on the proto definition in
// //components/reporting/proto/synced/record_constants.proto. Used to
// determine which records are shed first.
long priority;
EventType eventType;
};
// Context object containing the content-area user's ID for whom the signals
// collection request is for. This will be used to identify the organization
// in which the user is, and can then be used to determine their affiliation
// with the current browser management state.
[platforms = ("win")]
dictionary UserContext {
DOMString userId;
};
// Enumeration of the various states an AntiVirus software product can be in.
[platforms = ("win")]
enum AntiVirusProductState { ON, OFF, SNOOZED, EXPIRED };
// Metadata about a specific AntiVirus software product.
[platforms = ("win")]
dictionary AntiVirusSignal {
DOMString displayName;
DOMString productId;
AntiVirusProductState state;
};
// Invoked by <code>getAvInfo</code> to return information about installed
// AntiVirus software.
[platforms = ("win")]
callback AvInfoCallback = void(AntiVirusSignal[] avSignals);
// ID of an installed hotfix system update.
[platforms = ("win")]
dictionary HotfixSignal {
DOMString hotfixId;
};
// Invoked by <code>getHotfixes</code> to return the IDs of installed hotfix
// system updates.
[platforms = ("win")]
callback HotfixesCallback = void(HotfixSignal[] hotfixSignals);
// Used to indicate whether a given signal was correctly found or not, or
// indicate a reason for not being able to find it.
[platforms = ("win", "mac", "linux")]
enum PresenceValue {
// Was unable to determine whether the signal source exists or not. This
// typically indicates that a failure occurred before even trying to assess
// its presence.
UNSPECIFIED,
// Current user does not have access to the signal's source.
ACCESS_DENIED,
// The resource was not found.
NOT_FOUND,
// The resource was found.
FOUND
};
// Parameter used to collect information about a specific file system
// resource.
[platforms = ("win", "mac", "linux")]
dictionary GetFileSystemInfoOptions {
DOMString path;
boolean computeSha256;
boolean computeExecutableMetadata;
};
[platforms = ("win", "mac", "linux")]
dictionary GetFileSystemInfoRequest {
// Information about the for whom the signal collection request is for.
UserContext userContext;
// Collection of parameters used to conduct signals collection about
// specific file system resources.
GetFileSystemInfoOptions[] options;
};
[platforms = ("win", "mac", "linux")]
dictionary GetFileSystemInfoResponse {
// Path to the file system object for whom those signals were collected.
DOMString path;
// Value indicating whether the specific resource could be found or not.
PresenceValue presence;
// Sha256 hash of a file's bytes. Ignored when path points to a
// directory. Collected only when computeSha256 is set to true in the
// given signals collection parameters.
DOMString? sha256Hash;
// Set of properties only relevant for executable files. Will only be
// collected if computeExecutableMetadata is set to true in the given
// signals collection parameters and if path points to an executable file.
// Is true if a currently running process was spawned from this file.
boolean? isRunning;
// SHA-256 hashes of the public keys of the certificates used to sign the
// executable. A hash is computed over the DER-encoded SubjectPublicKeyInfo
// representation of the key.
DOMString[]? publicKeysHashes;
// Product name of this executable.
DOMString? productName;
// Version of this executable.
DOMString? version;
};
[platforms = ("win", "mac", "linux")]
callback FileSystemInfoCallback =
void(GetFileSystemInfoResponse[] fileSystemSignals);
[platforms = ("win")]
enum RegistryHive {
HKEY_CLASSES_ROOT,
HKEY_LOCAL_MACHINE,
HKEY_CURRENT_USER
};
[platforms = ("win", "mac")]
dictionary GetSettingsOptions {
// Path to a collection of settings.
// On Windows it would be the path to the reg key inside the hive.
// On Mac it would be the path to the plist file.
DOMString path;
// Key specifying the setting entry we're looking for.
// On Windows, that will be the registry key itself.
// On Mac, this is a key path used to retrieve a value from
// valueForKeyPath:.
DOMString key;
// When set to true, the retrieved signal will also include the setting's
// value. When false, the signal will only contain the setting's
// presence.
// Supported setting types on Windows:
// - REG_SZ
// - REG_DWORD
// - REG_QWORD
// Supported setting types on Mac:
// - NSString
// - NSNumber
boolean getValue;
// Windows registry hive containing the desired value.
// Required value on Windows, will be ignored on other platforms.
RegistryHive? hive;
};
[platforms = ("win", "mac")]
dictionary GetSettingsRequest {
// Information about the for whom the signal collection request is for.
UserContext userContext;
// Collection of parameters used to conduct signals collection about
// specific settings of the system.
GetSettingsOptions[] options;
};
[platforms = ("win", "mac")]
dictionary GetSettingsResponse {
// Path as given in the corresponding <code>GetSettingsOptions</code>
// request.
DOMString path;
// Key as given in the corresponding <code>GetSettingsOptions</code>
// request.
DOMString key;
// Hive as given in the corresponding <code>GetSettingsOptions</code>
// request.
// Present on Windows only.
RegistryHive? hive;
// Value indicating whether the specific resource could be found or not.
PresenceValue presence;
// JSON-stringified value of the setting. Only set if <code>getValue</code>
// was true in the corresponding request, and if the setting value was
// retrievable.
DOMString? value;
};
[platforms = ("win", "mac")]
callback SettingsCallback =
void(GetSettingsResponse[] settings);
interface Functions {
// Gets the identity of device that Chrome browser is running on. The ID is
// retrieved from the local device and used by the Google admin console.
[platforms = ("win", "mac", "linux")]
static void getDeviceId(optional GetDeviceIdCallback callback);
// Gets a randomly generated persistent secret (symmetric key) that
// can be used to encrypt the data stored with |setDeviceData|. If the
// optional parameter |forceCreation| is set to true the secret is recreated
// in case of any failure to retrieve the currently stored one. Sets
// $(ref:runtime.lastError) on failure.
[platforms = ("win", "mac")]
static void getPersistentSecret(
optional boolean resetSecret,
GetPersistentSecretCallback callback);
// Gets the device data for |id|. Sets $(ref:runtime.lastError) on failure.
[platforms = ("win", "mac", "linux")]
static void getDeviceData(DOMString id, GetDeviceDataCallback callback);
// Sets the device data for |id|. Sets $(ref:runtime.lastError) on failure.
// If the |data| parameter is undefined and there is already data
// associated with |id| it will be cleared.
[platforms = ("win", "mac", "linux")]
static void setDeviceData(
DOMString id,
optional ArrayBuffer data,
optional DoneCallback callback);
// Gets the device information (including disk encryption status,
// screen lock status, serial number, model).
[platforms = ("win", "mac", "linux")]
static void getDeviceInfo(GetDeviceInfoCallback callback);
// Gets the context information (including management status of the browser,
// state of key security policies, browser version).
static void getContextInfo(
GetContextInfoCallback callback);
// Returns the certificate that would be selected by the filters in the
// AutoSelectCertificateForUrls policy for <code>url</code>.
static void getCertificate(
DOMString url,
CertificateCallback callback);
// Enqueues a record for upload to the reporting service
// |request|: Composite object that captures everything
// we need for uploading records.
// |callback|: Callback that is triggered upon completion
[platforms = ("chromeos", "lacros")]
static void enqueueRecord(
EnqueueRecordRequest request,
optional DoneCallback callback);
// Gets information about file system resources, specified by the contents
// of <code>request</code>, on the current device. <code>request</code> must
// hold a user context to be used to verify the affiliation between the
// user's organization and the organization managing the browser. If the
// management or affiliation states are not suitable, no results will be
// returned.
[platforms = ("win", "mac", "linux")]
static void getFileSystemInfo(
GetFileSystemInfoRequest request,
FileSystemInfoCallback callback);
// Gets information about system settings specified by the contents of
// <code>request</code>. <code>request</code> must hold a user context to be
// used to verify the affiliation between the user's organization and the
// organization managing the browser. If the management or affiliation
// states are not suitable, no results will be returned.
[platforms = ("win", "mac")]
static void getSettings(
GetSettingsRequest request,
SettingsCallback callback);
// Gets information about AntiVirus software installed on the current
// device. <code>userContext</code> is used to verify the affiliation
// between the user's organization and the organization managing the
// browser. If the management, or affiliation, state is not suitable, no
// results will be returned.
[platforms = ("win")]
static void getAvInfo(UserContext userContext, AvInfoCallback callback);
// Gets information about hotfix system updates installed on the current
// device. <code>userContext</code> is used to verify the affiliation
// between the user's organization and the organization managing the
// browser. If the management, or affiliation, state is not suitable, no
// results will be returned.
[platforms = ("win")]
static void getHotfixes(UserContext userContext, HotfixesCallback callback);
};
};
Codebase Browser
chromium