path: root/extensions/common/api/networking_private.idl

// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// The <code>chrome.networkingPrivate</code> API is used for configuring
// network connections (Cellular, Ethernet, VPN, WiFi or WiMAX). This private
// API is only valid if called from a browser or app associated with the
// primary user. See the Open Network Configuration (ONC) documentation for
// descriptions of properties:
// <a href="https://code.google.com/p/chromium/codesearch#chromium/src/components/onc/docs/onc_spec.html">
// src/components/onc/docs/onc_spec.html</a>, or the
// <a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/open-network-configuration">
// Open Network Configuration</a> page at chromium.org.
// <br><br>
// NOTE: Most dictionary properties and enum values use UpperCamelCase to match
// the ONC spec instead of the JavaScript lowerCamelCase convention.
// <br><br>
// "State" properties describe just the ONC properties returned by
// $(ref:networkingPrivate.getState) and $(ref:networkingPrivate.getNetworks).
// <br><br>
// "Config" properties describe just the ONC properties that can be configured
// through this API. NOTE: Not all configuration properties are exposed at this
// time, only those currently required by the Chrome Settings UI.
// TODO(stevenjb): Provide all configuration properties and types,
// crbug.com/380937.
// <br><br>
// TODO(stevenjb/pneubeck): Merge the ONC documentation with this document and
// use it as the ONC specification.

namespace networkingPrivate {
  enum ActivationStateType {
    Activated, Activating, NotActivated, PartiallyActivated
  };

  enum CaptivePortalStatus {
    Unknown, Offline, Online, Portal, ProxyAuthRequired
  };

  enum ConnectionStateType {
    Connected, Connecting, NotConnected
  };

  enum DeviceStateType {
    // Device is available but not initialized.
    Uninitialized,
    // Device is intialized but not enabled.
    Disabled,
    // Enabled state has been requested but has not completed.
    Enabling,
    // Device is enabled.
    Enabled
  };

  enum IPConfigType {
    DHCP, Static
  };

  enum NetworkType {
    All, Cellular, Ethernet, VPN, Wireless, WiFi, WiMAX
  };

  enum ProxySettingsType {
    Direct, Manual, PAC, WPAD
  };

  dictionary APNProperties {
    DOMString AccessPointName;
    DOMString? Language;
    DOMString? LocalizedName;
    DOMString? Name;
    DOMString? Password;
    DOMString? Username;
  };

  dictionary CellularConfigProperties {
    boolean? AutoConnect;
    APNProperties? APN;

    // Specifies which carrier to use for Cellular configurations that support
    // multiple carriers. May be set with $(ref:setProperties), but will be
    // ignored by $(ref:createConfiguration).
    DOMString? Carrier;
  };

  dictionary CellularSimState {
    // Whether or not a PIN should be required.
    boolean requirePin;

    // The current PIN (required for any change, even when the SIM is unlocked).
    DOMString currentPin;

    // If provided, change the PIN to |newPin|. |requirePin| must be true.
    DOMString? newPin;
  };

  dictionary CellularStateProperties {
    ActivationStateType? ActivationState;
    DOMString? NetworkTechnology;
    DOMString? RoamingState;
    boolean? SIMPresent;
    long? SignalStrength;
  };

  dictionary DeviceStateProperties {
    // Set if the device is enabled. True if the device is currently scanning.
    boolean? Scanning;

    // Set to the SIM lock type if the device type is Cellular and the device
    // is locked.
    DOMString? SimLockType;

    // Set to the SIM present state if the device type is Cellular.
    boolean? SimPresent;

    // The current state of the device.
    DeviceStateType State;

    // The network type associated with the device (Cellular, Ethernet, WiFi, or
    // WiMAX).
    NetworkType Type;
  };

  dictionary EthernetStateProperties {
    DOMString Authentication;
  };

  dictionary IPConfigProperties {
    DOMString? Gateway;
    DOMString? IPAddress;
    DOMString[]? NameServers;
    long? RoutingPrefix;
    DOMString? Type;
    DOMString? WebProxyAutoDiscoveryUrl;
  };

  dictionary IPSecProperties {
    DOMString AuthenticationType;
  };

  dictionary ProxyLocation {
    DOMString Host;
    long Port;
  };

  dictionary ManualProxySettings {
    ProxyLocation? HTTPProxy;
    ProxyLocation? SecureHTTPProxy;
    ProxyLocation? FTPProxy;
    ProxyLocation? SOCKS;
  };

  dictionary ProxySettings {
    ProxySettingsType Type;
    ManualProxySettings? Manual;
    DOMString[]? ExcludeDomains;
    DOMString? PAC;
  };

  dictionary OpenVPNProperties {
    DOMString? OTP;
    DOMString? Password;
    DOMString? UserAuthenticationType;
    DOMString? Username;
  };

  dictionary ThirdPartyVPNProperties {
    DOMString ExtensionID;
  };

  dictionary VPNConfigProperties {
    boolean? AutoConnect;
    DOMString? Host;
    OpenVPNProperties? OpenVPN;
    ThirdPartyVPNProperties? ThirdPartyVPN;
    DOMString? Type;
  };

  dictionary VPNStateProperties {
    DOMString Type;
    IPSecProperties? IPsec;
    ThirdPartyVPNProperties? ThirdPartyVPN;
  };

  dictionary WiFiConfigProperties {
    boolean? AutoConnect;
    DOMString? HexSSID;
    boolean? HiddenSSID;
    DOMString? Passphrase;
    DOMString? SSID;
    DOMString? Security;
  };

  dictionary WiFiStateProperties {
    DOMString Security;
    long? SignalStrength;
  };

  dictionary WiMaxConfigProperties {
    boolean? AutoConnect;
  };

  dictionary WiMAXStateProperties {
    long? SignalStrength;
  };

  dictionary NetworkConfigProperties {
    CellularConfigProperties? Cellular;
    DOMString? GUID;
    IPConfigType? IPAddressConfigType;
    DOMString? Name;
    IPConfigType? NameServersConfigType;
    long? Priority;
    ProxySettings? ProxySettings;
    IPConfigProperties? StaticIPConfig;
    NetworkType? Type;
    VPNConfigProperties? VPN;
    WiFiConfigProperties? WiFi;
    WiMaxConfigProperties? WiMAX;
  };

  dictionary NetworkStateProperties {
    CellularStateProperties? Cellular;
    boolean? Connectable;
    ConnectionStateType? ConnectionState;
    EthernetStateProperties? Ethernet;
    DOMString? ErrorState;
    DOMString GUID;
    DOMString? Name;
    long? Priority;
    DOMString? Source;
    NetworkType Type;
    VPNStateProperties? VPN;
    WiFiStateProperties? WiFi;
    WiMAXStateProperties? WiMAX;
  };

  dictionary VerificationProperties {
    // A string containing a PEM-encoded (including the 'BEGIN CERTIFICATE'
    // header and 'END CERTIFICATE' footer) X.509 certificate for use in
    // verifying the signed data.
    DOMString certificate;

    // An array of PEM-encoded X.509 intermediate certificate authority
    // certificates. Each PEM-encoded certificate is expected to have the
    // 'BEGIN CERTIFICATE' header and 'END CERTIFICATE' footer.
    DOMString[]? intermediateCertificates;

    // A string containing a base64-encoded RSAPublicKey ASN.1 structure,
    // representing the public key to be used by
    // $(ref:verifyAndEncryptCredentials) and $(ref:verifyAndEncryptData)
    // methods.
    DOMString publicKey;

    // A string containing a base64-encoded random binary data for use in
    // verifying the signed data.
    DOMString nonce;

    // A string containing the identifying data string signed by the device.
    DOMString signedData;

    // A string containing the serial number of the device.
    DOMString deviceSerial;

    // A string containing the SSID of the device. Should be empty for new
    // configurations.
    DOMString deviceSsid;

    // A string containing the BSSID of the device. Should be empty for new
    // configurations.
    DOMString deviceBssid;
  };

  dictionary NetworkFilter {
    // The type of networks to return.
    NetworkType networkType;

    // If true, only include visible (physically connected or in-range)
    // networks. Defaults to 'false'.
    boolean? visible;

    // If true, only include configured (saved) networks. Defaults to 'false'.
    boolean? configured;

    // Maximum number of networks to return. Defaults to 1000 if unspecified.
    // Use 0 for no limit.
    long? limit;
  };

  callback VoidCallback = void();
  callback BooleanCallback = void(boolean result);
  callback StringCallback = void(DOMString result);
  // TODO(stevenjb): Use NetworkProperties for |result| once defined.
  callback GetPropertiesCallback = void(object result);
  // TODO(stevenjb): Use ManagedNetworkProperties for |result| once defined.
  callback GetManagedPropertiesCallback = void(object result);
  callback GetStatePropertiesCallback = void(NetworkStateProperties result);
  callback GetNetworksCallback = void(NetworkStateProperties[] result);
  callback GetDeviceStatesCallback = void(DeviceStateProperties[] result);
  callback GetEnabledNetworkTypesCallback = void(NetworkType[] result);
  callback CaptivePortalStatusCallback = void(CaptivePortalStatus result);

  // These functions all report failures via chrome.runtime.lastError.
  interface Functions {
    // Gets all the properties of the network with id networkGuid. Includes all
    // properties of the network (read-only and read/write values).
    // |networkGuid|: The GUID of the network to get properties for.
    // |callback|: Called with the network properties when received.
    static void getProperties(DOMString networkGuid,
                              GetPropertiesCallback callback);

    // Gets the merged properties of the network with id networkGuid from the
    // sources: User settings, shared settings, user policy, device policy and
    // the currently active settings.
    // |networkGuid|: The GUID of the network to get properties for.
    // |callback|: Called with the managed network properties when received.
    static void getManagedProperties(DOMString networkGuid,
                                     GetManagedPropertiesCallback callback);

    // Gets the cached read-only properties of the network with id networkGuid.
    // This is meant to be a higher performance function than
    // $(ref:getProperties), which requires a round trip to query the networking
    // subsystem. The following properties are returned for all networks: GUID,
    // Type, Name, WiFi.Security. Additional properties are provided for visible
    // networks: ConnectionState, ErrorState, WiFi.SignalStrength,
    // Cellular.NetworkTechnology, Cellular.ActivationState,
    // Cellular.RoamingState.
    // |networkGuid|: The GUID of the network to get properties for.
    // |callback|: Called immediately with the network state properties.
    static void getState(DOMString networkGuid,
                         GetStatePropertiesCallback callback);

    // Sets the properties of the network with id networkGuid.
    // |networkGuid|: The GUID of the network to set properties for.
    // |properties|: The properties to set.
    // |callback|: Called when the operation has completed.
    static void setProperties(DOMString networkGuid,
                              NetworkConfigProperties properties,
                              optional VoidCallback callback);

    // Creates a new network configuration from properties. If a matching
    // configured network already exists, this will fail. Otherwise returns the
    // guid of the new network.
    // |shared|: If true, share this network configuration with other users.
    // |properties|: The properties to configure the new network with.
    // |callback|: Called with the GUID for the new network configuration once
    //     the network has been created.
    static void createNetwork(boolean shared,
                              NetworkConfigProperties properties,
                              optional StringCallback callback);

    // Forgets a network configuration by clearing any configured properties for
    // the network with GUID 'networkGuid'. This may also include any other
    // networks with matching identifiers (e.g. WiFi SSID and Security). If no
    // such configuration exists, an error will be set and the operation will
    // fail.
    // |networkGuid|: The GUID of the network to forget.
    // |callback|: Called when the operation has completed.
    static void forgetNetwork(DOMString networkGuid,
                              optional VoidCallback callback);

    // Returns a list of network objects with the same properties provided by
    // $(ref:networkingPrivate.getState). A filter is provided to specify the
    // type of networks returned and to limit the number of networks. Networks
    // are ordered by the system based on their priority, with connected or
    // connecting networks listed first.
    // |filter|: Describes which networks to return.
    // |callback|: Called with a dictionary of networks and their state
    //     properties when received.
    static void getNetworks(NetworkFilter filter,
                            GetNetworksCallback callback);

    // Deprecated. Please use $(ref:networkingPrivate.getNetworks) with
    // filter.visible = true instead.
    [deprecated="Use getNetworks."] static void getVisibleNetworks(
        NetworkType networkType,
        GetNetworksCallback callback);

    // Deprecated. Please use $(ref:networkingPrivate.getDeviceStates) instead.
    [deprecated="Use getDeviceStates."] static void getEnabledNetworkTypes(
        GetEnabledNetworkTypesCallback callback);

    // Returns a list of $(ref:networkingPrivate.DeviceStateProperties) objects.
    // |callback|: Called with a list of devices and their state.
    static void getDeviceStates(GetDeviceStatesCallback callback);

    // Enables any devices matching the specified network type. Note, the type
    // might represent multiple network types (e.g. 'Wireless').
    // |networkType|: The type of network to enable.
    static void enableNetworkType(NetworkType networkType);

    // Disables any devices matching the specified network type. See note for
    // $(ref:networkingPrivate.enableNetworkType).
    // |networkType|: The type of network to disable.
    static void disableNetworkType(NetworkType networkType);

    // Requests that the networking subsystem scan for new networks and
    // update the list returned by $(ref:getVisibleNetworks). This is only a
    // request: the network subsystem can choose to ignore it.  If the list
    // is updated, then the $(ref:onNetworkListChanged) event will be fired.
    static void requestNetworkScan();

    // Starts a connection to the network with networkGuid.
    // |networkGuid|: The GUID of the network to connect to.
    // |callback|: Called when the connect request has been sent. Note: the
    //     connection may not have completed. Observe $(ref:onNetworksChanged)
    //     to be notified when a network state changes.
    static void startConnect(DOMString networkGuid,
                             optional VoidCallback callback);

    // Starts a disconnect from the network with networkGuid.
    // |networkGuid|: The GUID of the network to disconnect from.
    // |callback|: Called when the disconnect request has been sent. See note
    //     for $(ref:startConnect).
    static void startDisconnect(DOMString networkGuid,
                                optional VoidCallback callback);

    // Starts activation of the Cellular network with networkGuid. If called
    // for a network that is already activated, or for a network with a carrier
    // that can not be directly activated, this will show the account details
    // page for the carrier if possible.
    // |networkGuid|: The GUID of the Cellular network to activate.
    // |carrier|: Optional name of carrier to activate.
    // |callback|: Called when the activation request has been sent. See note
    //     for $(ref:startConnect).
    static void startActivate(DOMString networkGuid,
                              optional DOMString carrier,
                              optional VoidCallback callback);

    // Verifies that the device is a trusted device.
    // |properties|: Properties of the destination to use in verifying that it
    //     is a trusted device.
    // |callback|: A callback function that indicates whether or not the device
    //     is a trusted device.
    static void verifyDestination(VerificationProperties properties,
                                  BooleanCallback callback);

    // Verifies that the device is a trusted device and retrieves encrypted
    // network credentials.
    // |properties|: Properties of the destination to use in verifying that it
    //     is a trusted device.
    // |networkGuid|: The GUID of the Cellular network to activate.
    // |callback|: A callback function that receives base64-encoded encrypted
    //     credential data to send to a trusted device.
    static void verifyAndEncryptCredentials(VerificationProperties properties,
                                            DOMString networkGuid,
                                            StringCallback callback);

    // Verifies that the device is a trusted device and encrypts supplied
    // data with device public key.
    // |properties|: Properties of the destination to use in verifying that it
    //     is a trusted device.
    // |data|: A string containing the base64-encoded data to encrypt.
    // |callback|: A callback function that receives base64-encoded encrypted
    //     data to send to a trusted device.
    static void verifyAndEncryptData(VerificationProperties properties,
                                     DOMString data,
                                     StringCallback callback);

    // Enables TDLS for WiFi traffic with a specified peer if available.
    // |ip_or_mac_address|: The IP or MAC address of the peer with which to
    //     enable a TDLS connection.
    // |enabled| If true, enable TDLS, otherwise disable TDLS.
    // |callback|: A callback function that receives a string with an error or
    //     the current TDLS status. 'Failed' indicates that the request failed
    //     (e.g. MAC address lookup failed). 'Timeout' indicates that the lookup
    //     timed out. Otherwise a valid status is returned (see
    //     $(ref:getWifiTDLSStatus)).
    static void setWifiTDLSEnabledState(DOMString ip_or_mac_address,
                                        boolean enabled,
                                        optional StringCallback callback);

    // Returns the current TDLS status for the specified peer.
    // |ip_or_mac_address|: The IP or MAC address of the peer.
    // |callback|: A callback function that receives a string with the current
    //     TDLS status which can be 'Connected', 'Disabled', 'Disconnected',
    //     'Nonexistent', or 'Unknown'.
    static void getWifiTDLSStatus(DOMString ip_or_mac_address,
                                  StringCallback callback);

    // Returns captive portal status for the network matching 'networkGuid'.
    // |networkGuid|: The GUID of the network to get captive portal status for.
    // |callback|: A callback function that returns the results of the query for
    //     network captive portal status.
    static void getCaptivePortalStatus(DOMString networkGuid,
                                       CaptivePortalStatusCallback callback);

    // Unlocks a Cellular SIM card.
    // * If the SIM is PIN locked, |pin| will be used to unlock the SIM and
    //   the |puk| argument will be ignored if provided.
    // * If the SIM is PUK locked, |puk| and |pin| must be provided. If the
    //   operation succeds (|puk| is valid), the PIN will be set to |pin|.
    //   (If |pin| is empty or invalid the operation will fail).
    // |networkGuid|: The GUID of the cellular network to unlock.
    // |pin|: The current SIM PIN, or the new PIN if PUK is provided.
    // |puk|: The operator provided PUK for unblocking a blocked SIM.
    // |callback|: Called when the operation has completed.
    static void unlockCellularSim(DOMString networkGuid,
                                  DOMString pin,
                                  optional DOMString puk,
                                  optional VoidCallback callback);

    // Sets whether or not SIM locking is enabled (i.e a PIN will be required
    // when the device is powered) and changes the PIN if a new PIN is
    // specified. If the new PIN is provided but not valid (e.g. too short)
    // the operation will fail. This will not lock the SIM; that is handled
    // automatically by the device. NOTE: If the SIM is locked, it must first be
    // unlocked with unlockCellularSim() before this can be called (otherwise it
    // will fail and chrome.runtime.lastError will be set to Error.SimLocked).
    // |networkGuid|: The GUID of the cellular network to set the SIM state of.
    // |simState|: The SIM state to set.
    // |callback|: Called when the operation has completed.
    static void setCellularSimState(DOMString networkGuid,
                                    CellularSimState simState,
                                    optional VoidCallback callback);
  };

  interface Events {
    // Fired when the properties change on any of the networks.  Sends a list of
    // GUIDs for networks whose properties have changed.
    static void onNetworksChanged(DOMString[] changes);

    // Fired when the list of networks has changed.  Sends a complete list of
    // GUIDs for all the current networks.
    static void onNetworkListChanged(DOMString[] changes);

    // Fired when the list of devices has changed or any device state properties
    // have changed.
    static void onDeviceStateListChanged();

    // Fired when a portal detection for a network completes. Sends the guid of
    // the network and the corresponding captive portal status.
    static void onPortalDetectionCompleted(DOMString networkGuid,
                                           CaptivePortalStatus status);
  };
};