chrome/common/extensions/api/enterprise_reporting_private.idl

// 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"), supportsPromises]
    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"), supportsPromises]
    static void getPersistentSecret(
        optional boolean resetSecret,
        GetPersistentSecretCallback callback);

    // Gets the device data for |id|. Sets $(ref:runtime.lastError) on failure.
    [platforms = ("win", "mac", "linux"), supportsPromises]
    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"), supportsPromises]
    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"), supportsPromises]
    static void getDeviceInfo(GetDeviceInfoCallback callback);

    // Gets the context information (including management status of the browser,
    // state of key security policies, browser version).
    [supportsPromises] static void getContextInfo(
        GetContextInfoCallback callback);

    // Returns the certificate that would be selected by the filters in the
    // AutoSelectCertificateForUrls policy for <code>url</code>.
    [supportsPromises] 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"), supportsPromises]
    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"), supportsPromises]
    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"), supportsPromises]
    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"), supportsPromises]
    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"), supportsPromises]
    static void getHotfixes(UserContext userContext, HotfixesCallback callback);
  };

};