extensions/common/api/networking_private.idl

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // The <code>chrome.networkingPrivate</code> API is used for configuring
   6 // network connections (Cellular, Ethernet, VPN, WiFi or WiMAX). This private
   7 // API is only valid if called from a browser or app associated with the
   8 // primary user. See the Open Network Configuration (ONC) documentation for
   9 // descriptions of properties:
  10 // <a href="https://code.google.com/p/chromium/codesearch#chromium/src/components/onc/docs/onc_spec.html">
  11 // src/components/onc/docs/onc_spec.html</a>, or the
  12 // <a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/open-network-configuration">
  13 // Open Network Configuration</a> page at chromium.org.
  14 // <br><br>
  15 // NOTE: Most dictionary properties and enum values use UpperCamelCase to match
  16 // the ONC spec instead of the JavaScript lowerCamelCase convention.
  17 // <br><br>
  18 // "State" properties describe just the ONC properties returned by
  19 // $(ref:networkingPrivate.getState) and $(ref:networkingPrivate.getNetworks).
  20 // <br><br>
  21 // "Config" properties describe just the ONC properties that can be configured
  22 // through this API. NOTE: Not all configuration properties are exposed at this
  23 // time, only those currently required by the Chrome Settings UI.
  24 // TODO(stevenjb): Provide all configuration properties and types,
  25 // crbug.com/380937.
  26 // <br><br>
  27 // TODO(stevenjb/pneubeck): Merge the ONC documentation with this document and
  28 // use it as the ONC specification.
  29
  30 namespace networkingPrivate {
  31   enum ActivationStateType {
  32     Activated, Activating, NotActivated, PartiallyActivated
  33   };
  34
  35   enum CaptivePortalStatus {
  36     Unknown, Offline, Online, Portal, ProxyAuthRequired
  37   };
  38
  39   enum ConnectionStateType {
  40     Connected, Connecting, NotConnected
  41   };
  42
  43   enum DeviceStateType {
  44     // Device is available but not initialized.
  45     Uninitialized,
  46     // Device is intialized but not enabled.
  47     Disabled,
  48     // Enabled state has been requested but has not completed.
  49     Enabling,
  50     // Device is enabled.
  51     Enabled
  52   };
  53
  54   enum IPConfigType {
  55     DHCP, Static
  56   };
  57
  58   enum NetworkType {
  59     All, Cellular, Ethernet, VPN, Wireless, WiFi, WiMAX
  60   };
  61
  62   enum ProxySettingsType {
  63     Direct, Manual, PAC, WPAD
  64   };
  65
  66   dictionary APNProperties {
  67     DOMString AccessPointName;
  68     DOMString? Language;
  69     DOMString? LocalizedName;
  70     DOMString? Name;
  71     DOMString? Password;
  72     DOMString? Username;
  73   };
  74
  75   dictionary CellularConfigProperties {
  76     boolean? AutoConnect;
  77     APNProperties? APN;
  78
  79     // Specifies which carrier to use for Cellular configurations that support
  80     // multiple carriers. May be set with $(ref:setProperties), but will be
  81     // ignored by $(ref:createConfiguration).
  82     DOMString? Carrier;
  83   };
  84
  85   dictionary CellularSimState {
  86     // Whether or not a PIN should be required.
  87     boolean requirePin;
  88
  89     // The current PIN (required for any change, even when the SIM is unlocked).
  90     DOMString currentPin;
  91
  92     // If provided, change the PIN to |newPin|. |requirePin| must be true.
  93     DOMString? newPin;
  94   };
  95
  96   dictionary CellularStateProperties {
  97     ActivationStateType? ActivationState;
  98     DOMString? NetworkTechnology;
  99     DOMString? RoamingState;
 100     boolean? SIMPresent;
 101     long? SignalStrength;
 102   };
 103
 104   dictionary DeviceStateProperties {
 105     // Set if the device is enabled. True if the device is currently scanning.
 106     boolean? Scanning;
 107
 108     // The current state of the device.
 109     DeviceStateType State;
 110
 111     // The network type associated with the device (Cellular, Ethernet, WiFi, or
 112     // WiMAX).
 113     NetworkType Type;
 114   };
 115
 116   dictionary EthernetStateProperties {
 117     DOMString Authentication;
 118   };
 119
 120   dictionary IPConfigProperties {
 121     DOMString? Gateway;
 122     DOMString? IPAddress;
 123     DOMString[]? NameServers;
 124     long? RoutingPrefix;
 125     DOMString? Type;
 126     DOMString? WebProxyAutoDiscoveryUrl;
 127   };
 128
 129   dictionary IPSecProperties {
 130     DOMString AuthenticationType;
 131   };
 132
 133   dictionary ProxyLocation {
 134     DOMString Host;
 135     long Port;
 136   };
 137
 138   dictionary ManualProxySettings {
 139     ProxyLocation? HTTPProxy;
 140     ProxyLocation? SecureHTTPProxy;
 141     ProxyLocation? FTPProxy;
 142     ProxyLocation? SOCKS;
 143   };
 144
 145   dictionary ProxySettings {
 146     ProxySettingsType Type;
 147     ManualProxySettings? Manual;
 148     DOMString[]? ExcludeDomains;
 149     DOMString? PAC;
 150   };
 151
 152   dictionary OpenVPNProperties {
 153     DOMString? OTP;
 154     DOMString? Password;
 155     DOMString? UserAuthenticationType;
 156     DOMString? Username;
 157   };
 158
 159   dictionary ThirdPartyVPNProperties {
 160     DOMString ExtensionID;
 161   };
 162
 163   dictionary VPNConfigProperties {
 164     boolean? AutoConnect;
 165     DOMString? Host;
 166     OpenVPNProperties? OpenVPN;
 167     ThirdPartyVPNProperties? ThirdPartyVPN;
 168     DOMString? Type;
 169   };
 170
 171   dictionary VPNStateProperties {
 172     DOMString Type;
 173     IPSecProperties? IPsec;
 174     ThirdPartyVPNProperties? ThirdPartyVPN;
 175   };
 176
 177   dictionary WiFiConfigProperties {
 178     boolean? AutoConnect;
 179     DOMString? HexSSID;
 180     boolean? HiddenSSID;
 181     DOMString? Passphrase;
 182     DOMString? SSID;
 183     DOMString? Security;
 184   };
 185
 186   dictionary WiFiStateProperties {
 187     DOMString Security;
 188     long? SignalStrength;
 189   };
 190
 191   dictionary WiMaxConfigProperties {
 192     boolean? AutoConnect;
 193   };
 194
 195   dictionary WiMAXStateProperties {
 196     long? SignalStrength;
 197   };
 198
 199   dictionary NetworkConfigProperties {
 200     CellularConfigProperties? Cellular;
 201     DOMString? GUID;
 202     IPConfigType? IPAddressConfigType;
 203     DOMString? Name;
 204     IPConfigType? NameServersConfigType;
 205     long? Priority;
 206     ProxySettings? ProxySettings;
 207     IPConfigProperties? StaticIPConfig;
 208     NetworkType? Type;
 209     VPNConfigProperties? VPN;
 210     WiFiConfigProperties? WiFi;
 211     WiMaxConfigProperties? WiMAX;
 212   };
 213
 214   dictionary NetworkStateProperties {
 215     CellularStateProperties? Cellular;
 216     boolean? Connectable;
 217     ConnectionStateType? ConnectionState;
 218     EthernetStateProperties? Ethernet;
 219     DOMString? ErrorState;
 220     DOMString GUID;
 221     DOMString? Name;
 222     long? Priority;
 223     DOMString? Source;
 224     NetworkType Type;
 225     VPNStateProperties? VPN;
 226     WiFiStateProperties? WiFi;
 227     WiMAXStateProperties? WiMAX;
 228   };
 229
 230   dictionary VerificationProperties {
 231     // A string containing a PEM-encoded (including the 'BEGIN CERTIFICATE'
 232     // header and 'END CERTIFICATE' footer) X.509 certificate for use in
 233     // verifying the signed data.
 234     DOMString certificate;
 235
 236     // An array of PEM-encoded X.509 intermediate certificate authority
 237     // certificates. Each PEM-encoded certificate is expected to have the
 238     // 'BEGIN CERTIFICATE' header and 'END CERTIFICATE' footer.
 239     DOMString[]? intermediateCertificates;
 240
 241     // A string containing a base64-encoded RSAPublicKey ASN.1 structure,
 242     // representing the public key to be used by
 243     // $(ref:verifyAndEncryptCredentials) and $(ref:verifyAndEncryptData)
 244     // methods.
 245     DOMString publicKey;
 246
 247     // A string containing a base64-encoded random binary data for use in
 248     // verifying the signed data.
 249     DOMString nonce;
 250
 251     // A string containing the identifying data string signed by the device.
 252     DOMString signedData;
 253
 254     // A string containing the serial number of the device.
 255     DOMString deviceSerial;
 256
 257     // A string containing the SSID of the device. Should be empty for new
 258     // configurations.
 259     DOMString deviceSsid;
 260
 261     // A string containing the BSSID of the device. Should be empty for new
 262     // configurations.
 263     DOMString deviceBssid;
 264   };
 265
 266   dictionary NetworkFilter {
 267     // The type of networks to return.
 268     NetworkType networkType;
 269
 270     // If true, only include visible (physically connected or in-range)
 271     // networks. Defaults to 'false'.
 272     boolean? visible;
 273
 274     // If true, only include configured (saved) networks. Defaults to 'false'.
 275     boolean? configured;
 276
 277     // Maximum number of networks to return. Defaults to 1000 if unspecified.
 278     // Use 0 for no limit.
 279     long? limit;
 280   };
 281
 282   callback VoidCallback = void();
 283   callback BooleanCallback = void(boolean result);
 284   callback StringCallback = void(DOMString result);
 285   // TODO(stevenjb): Use NetworkProperties for |result| once defined.
 286   callback GetPropertiesCallback = void(object result);
 287   // TODO(stevenjb): Use ManagedNetworkProperties for |result| once defined.
 288   callback GetManagedPropertiesCallback = void(object result);
 289   callback GetStatePropertiesCallback = void(NetworkStateProperties result);
 290   callback GetNetworksCallback = void(NetworkStateProperties[] result);
 291   callback GetDeviceStatesCallback = void(DeviceStateProperties[] result);
 292   callback GetEnabledNetworkTypesCallback = void(NetworkType[] result);
 293   callback CaptivePortalStatusCallback = void(CaptivePortalStatus result);
 294
 295   // These functions all report failures via chrome.runtime.lastError.
 296   interface Functions {
 297     // Gets all the properties of the network with id networkGuid. Includes all
 298     // properties of the network (read-only and read/write values).
 299     // |networkGuid|: The GUID of the network to get properties for.
 300     // |callback|: Called with the network properties when received.
 301     static void getProperties(DOMString networkGuid,
 302                               GetPropertiesCallback callback);
 303
 304     // Gets the merged properties of the network with id networkGuid from the
 305     // sources: User settings, shared settings, user policy, device policy and
 306     // the currently active settings.
 307     // |networkGuid|: The GUID of the network to get properties for.
 308     // |callback|: Called with the managed network properties when received.
 309     static void getManagedProperties(DOMString networkGuid,
 310                                      GetManagedPropertiesCallback callback);
 311
 312     // Gets the cached read-only properties of the network with id networkGuid.
 313     // This is meant to be a higher performance function than
 314     // $(ref:getProperties), which requires a round trip to query the networking
 315     // subsystem. The following properties are returned for all networks: GUID,
 316     // Type, Name, WiFi.Security. Additional properties are provided for visible
 317     // networks: ConnectionState, ErrorState, WiFi.SignalStrength,
 318     // Cellular.NetworkTechnology, Cellular.ActivationState,
 319     // Cellular.RoamingState.
 320     // |networkGuid|: The GUID of the network to get properties for.
 321     // |callback|: Called immediately with the network state properties.
 322     static void getState(DOMString networkGuid,
 323                          GetStatePropertiesCallback callback);
 324
 325     // Sets the properties of the network with id networkGuid.
 326     // |networkGuid|: The GUID of the network to set properties for.
 327     // |properties|: The properties to set.
 328     // |callback|: Called when the operation has completed.
 329     static void setProperties(DOMString networkGuid,
 330                               NetworkConfigProperties properties,
 331                               optional VoidCallback callback);
 332
 333     // Creates a new network configuration from properties. If a matching
 334     // configured network already exists, this will fail. Otherwise returns the
 335     // guid of the new network.
 336     // |shared|: If true, share this network configuration with other users.
 337     // |properties|: The properties to configure the new network with.
 338     // |callback|: Called with the GUID for the new network configuration once
 339     //     the network has been created.
 340     static void createNetwork(boolean shared,
 341                               NetworkConfigProperties properties,
 342                               optional StringCallback callback);
 343
 344     // Forgets a network configuration by clearing any configured properties for
 345     // the network with GUID 'networkGuid'. This may also include any other
 346     // networks with matching identifiers (e.g. WiFi SSID and Security). If no
 347     // such configuration exists, an error will be set and the operation will
 348     // fail.
 349     // |networkGuid|: The GUID of the network to forget.
 350     // |callback|: Called when the operation has completed.
 351     static void forgetNetwork(DOMString networkGuid,
 352                               optional VoidCallback callback);
 353
 354     // Returns a list of network objects with the same properties provided by
 355     // $(ref:networkingPrivate.getState). A filter is provided to specify the
 356     // type of networks returned and to limit the number of networks. Networks
 357     // are ordered by the system based on their priority, with connected or
 358     // connecting networks listed first.
 359     // |filter|: Describes which networks to return.
 360     // |callback|: Called with a dictionary of networks and their state
 361     //     properties when received.
 362     static void getNetworks(NetworkFilter filter,
 363                             GetNetworksCallback callback);
 364
 365     // Deprecated. Please use $(ref:networkingPrivate.getNetworks) with
 366     // filter.visible = true instead.
 367     [deprecated="Use getNetworks."] static void getVisibleNetworks(
 368         NetworkType networkType,
 369         GetNetworksCallback callback);
 370
 371     // Deprecated. Please use $(ref:networkingPrivate.getDeviceStates) instead.
 372     [deprecated="Use getDeviceStates."] static void getEnabledNetworkTypes(
 373         GetEnabledNetworkTypesCallback callback);
 374
 375     // Returns a list of $(ref:networkingPrivate.DeviceStateProperties) objects.
 376     // |callback|: Called with a list of devices and their state.
 377     static void getDeviceStates(GetDeviceStatesCallback callback);
 378
 379     // Enables any devices matching the specified network type. Note, the type
 380     // might represent multiple network types (e.g. 'Wireless').
 381     // |networkType|: The type of network to enable.
 382     static void enableNetworkType(NetworkType networkType);
 383
 384     // Disables any devices matching the specified network type. See note for
 385     // $(ref:networkingPrivate.enableNetworkType).
 386     // |networkType|: The type of network to disable.
 387     static void disableNetworkType(NetworkType networkType);
 388
 389     // Requests that the networking subsystem scan for new networks and
 390     // update the list returned by $(ref:getVisibleNetworks). This is only a
 391     // request: the network subsystem can choose to ignore it.  If the list
 392     // is updated, then the $(ref:onNetworkListChanged) event will be fired.
 393     static void requestNetworkScan();
 394
 395     // Starts a connection to the network with networkGuid.
 396     // |networkGuid|: The GUID of the network to connect to.
 397     // |callback|: Called when the connect request has been sent. Note: the
 398     //     connection may not have completed. Observe $(ref:onNetworksChanged)
 399     //     to be notified when a network state changes.
 400     static void startConnect(DOMString networkGuid,
 401                              optional VoidCallback callback);
 402
 403     // Starts a disconnect from the network with networkGuid.
 404     // |networkGuid|: The GUID of the network to disconnect from.
 405     // |callback|: Called when the disconnect request has been sent. See note
 406     //     for $(ref:startConnect).
 407     static void startDisconnect(DOMString networkGuid,
 408                                 optional VoidCallback callback);
 409
 410     // Starts activation of the Cellular network with networkGuid. If called
 411     // for a network that is already activated, or for a network with a carrier
 412     // that can not be directly activated, this will show the account details
 413     // page for the carrier if possible.
 414     // |networkGuid|: The GUID of the Cellular network to activate.
 415     // |carrier|: Optional name of carrier to activate.
 416     // |callback|: Called when the activation request has been sent. See note
 417     //     for $(ref:startConnect).
 418     static void startActivate(DOMString networkGuid,
 419                               optional DOMString carrier,
 420                               optional VoidCallback callback);
 421
 422     // Verifies that the device is a trusted device.
 423     // |properties|: Properties of the destination to use in verifying that it
 424     //     is a trusted device.
 425     // |callback|: A callback function that indicates whether or not the device
 426     //     is a trusted device.
 427     static void verifyDestination(VerificationProperties properties,
 428                                   BooleanCallback callback);
 429
 430     // Verifies that the device is a trusted device and retrieves encrypted
 431     // network credentials.
 432     // |properties|: Properties of the destination to use in verifying that it
 433     //     is a trusted device.
 434     // |networkGuid|: The GUID of the Cellular network to activate.
 435     // |callback|: A callback function that receives base64-encoded encrypted
 436     //     credential data to send to a trusted device.
 437     static void verifyAndEncryptCredentials(VerificationProperties properties,
 438                                             DOMString networkGuid,
 439                                             StringCallback callback);
 440
 441     // Verifies that the device is a trusted device and encrypts supplied
 442     // data with device public key.
 443     // |properties|: Properties of the destination to use in verifying that it
 444     //     is a trusted device.
 445     // |data|: A string containing the base64-encoded data to encrypt.
 446     // |callback|: A callback function that receives base64-encoded encrypted
 447     //     data to send to a trusted device.
 448     static void verifyAndEncryptData(VerificationProperties properties,
 449                                      DOMString data,
 450                                      StringCallback callback);
 451
 452     // Enables TDLS for WiFi traffic with a specified peer if available.
 453     // |ip_or_mac_address|: The IP or MAC address of the peer with which to
 454     //     enable a TDLS connection.
 455     // |enabled| If true, enable TDLS, otherwise disable TDLS.
 456     // |callback|: A callback function that receives a string with an error or
 457     //     the current TDLS status. 'Failed' indicates that the request failed
 458     //     (e.g. MAC address lookup failed). 'Timeout' indicates that the lookup
 459     //     timed out. Otherwise a valid status is returned (see
 460     //     $(ref:getWifiTDLSStatus)).
 461     static void setWifiTDLSEnabledState(DOMString ip_or_mac_address,
 462                                         boolean enabled,
 463                                         optional StringCallback callback);
 464
 465     // Returns the current TDLS status for the specified peer.
 466     // |ip_or_mac_address|: The IP or MAC address of the peer.
 467     // |callback|: A callback function that receives a string with the current
 468     //     TDLS status which can be 'Connected', 'Disabled', 'Disconnected',
 469     //     'Nonexistent', or 'Unknown'.
 470     static void getWifiTDLSStatus(DOMString ip_or_mac_address,
 471                                   StringCallback callback);
 472
 473     // Returns captive portal status for the network matching 'networkGuid'.
 474     // |networkGuid|: The GUID of the network to get captive portal status for.
 475     // |callback|: A callback function that returns the results of the query for
 476     //     network captive portal status.
 477     static void getCaptivePortalStatus(DOMString networkGuid,
 478                                        CaptivePortalStatusCallback callback);
 479
 480     // Unlocks a Cellular SIM card.
 481     // * If the SIM is PIN locked, |pin| will be used to unlock the SIM and
 482     //   the |puk| argument will be ignored if provided.
 483     // * If the SIM is PUK locked, |puk| and |pin| must be provided. If the
 484     //   operation succeds (|puk| is valid), the PIN will be set to |pin|.
 485     //   (If |pin| is empty or invalid the operation will fail).
 486     // |networkGuid|: The GUID of the cellular network to unlock.
 487     // |pin|: The current SIM PIN, or the new PIN if PUK is provided.
 488     // |puk|: The operator provided PUK for unblocking a blocked SIM.
 489     // |callback|: Called when the operation has completed.
 490     static void unlockCellularSim(DOMString networkGuid,
 491                                   DOMString pin,
 492                                   optional DOMString puk,
 493                                   optional VoidCallback callback);
 494
 495     // Sets whether or not SIM locking is enabled (i.e a PIN will be required
 496     // when the device is powered) and changes the PIN if a new PIN is
 497     // specified. If the new PIN is provided but not valid (e.g. too short)
 498     // the operation will fail. This will not lock the SIM; that is handled
 499     // automatically by the device. NOTE: If the SIM is locked, it must first be
 500     // unlocked with unlockCellularSim() before this can be called (otherwise it
 501     // will fail and chrome.runtime.lastError will be set to Error.SimLocked).
 502     // |networkGuid|: The GUID of the cellular network to set the SIM state of.
 503     // |simState|: The SIM state to set.
 504     // |callback|: Called when the operation has completed.
 505     static void setCellularSimState(DOMString networkGuid,
 506                                     CellularSimState simState,
 507                                     optional VoidCallback callback);
 508   };
 509
 510   interface Events {
 511     // Fired when the properties change on any of the networks.  Sends a list of
 512     // GUIDs for networks whose properties have changed.
 513     static void onNetworksChanged(DOMString[] changes);
 514
 515     // Fired when the list of networks has changed.  Sends a complete list of
 516     // GUIDs for all the current networks.
 517     static void onNetworkListChanged(DOMString[] changes);
 518
 519     // Fired when the list of devices has changed or any device state properties
 520     // have changed.
 521     static void onDeviceStateListChanged();
 522
 523     // Fired when a portal detection for a network completes. Sends the guid of
 524     // the network and the corresponding captive portal status.
 525     static void onPortalDetectionCompleted(DOMString networkGuid,
 526                                            CaptivePortalStatus status);
 527   };
 528 };