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     // Set to the SIM lock type if the device type is Cellular and the device
 109     // is locked.
 110     DOMString? SimLockType;
 111
 112     // Set to the SIM present state if the device type is Cellular.
 113     boolean? SimPresent;
 114
 115     // The current state of the device.
 116     DeviceStateType State;
 117
 118     // The network type associated with the device (Cellular, Ethernet, WiFi, or
 119     // WiMAX).
 120     NetworkType Type;
 121   };
 122
 123   dictionary EthernetStateProperties {
 124     DOMString Authentication;
 125   };
 126
 127   dictionary IPConfigProperties {
 128     DOMString? Gateway;
 129     DOMString? IPAddress;
 130     DOMString[]? NameServers;
 131     long? RoutingPrefix;
 132     DOMString? Type;
 133     DOMString? WebProxyAutoDiscoveryUrl;
 134   };
 135
 136   dictionary IPSecProperties {
 137     DOMString AuthenticationType;
 138   };
 139
 140   dictionary ProxyLocation {
 141     DOMString Host;
 142     long Port;
 143   };
 144
 145   dictionary ManualProxySettings {
 146     ProxyLocation? HTTPProxy;
 147     ProxyLocation? SecureHTTPProxy;
 148     ProxyLocation? FTPProxy;
 149     ProxyLocation? SOCKS;
 150   };
 151
 152   dictionary ProxySettings {
 153     ProxySettingsType Type;
 154     ManualProxySettings? Manual;
 155     DOMString[]? ExcludeDomains;
 156     DOMString? PAC;
 157   };
 158
 159   dictionary OpenVPNProperties {
 160     DOMString? OTP;
 161     DOMString? Password;
 162     DOMString? UserAuthenticationType;
 163     DOMString? Username;
 164   };
 165
 166   dictionary ThirdPartyVPNProperties {
 167     DOMString ExtensionID;
 168   };
 169
 170   dictionary VPNConfigProperties {
 171     boolean? AutoConnect;
 172     DOMString? Host;
 173     OpenVPNProperties? OpenVPN;
 174     ThirdPartyVPNProperties? ThirdPartyVPN;
 175     DOMString? Type;
 176   };
 177
 178   dictionary VPNStateProperties {
 179     DOMString Type;
 180     IPSecProperties? IPsec;
 181     ThirdPartyVPNProperties? ThirdPartyVPN;
 182   };
 183
 184   dictionary WiFiConfigProperties {
 185     boolean? AutoConnect;
 186     DOMString? HexSSID;
 187     boolean? HiddenSSID;
 188     DOMString? Passphrase;
 189     DOMString? SSID;
 190     DOMString? Security;
 191   };
 192
 193   dictionary WiFiStateProperties {
 194     DOMString Security;
 195     long? SignalStrength;
 196   };
 197
 198   dictionary WiMaxConfigProperties {
 199     boolean? AutoConnect;
 200   };
 201
 202   dictionary WiMAXStateProperties {
 203     long? SignalStrength;
 204   };
 205
 206   dictionary NetworkConfigProperties {
 207     CellularConfigProperties? Cellular;
 208     DOMString? GUID;
 209     IPConfigType? IPAddressConfigType;
 210     DOMString? Name;
 211     IPConfigType? NameServersConfigType;
 212     long? Priority;
 213     ProxySettings? ProxySettings;
 214     IPConfigProperties? StaticIPConfig;
 215     NetworkType? Type;
 216     VPNConfigProperties? VPN;
 217     WiFiConfigProperties? WiFi;
 218     WiMaxConfigProperties? WiMAX;
 219   };
 220
 221   dictionary NetworkStateProperties {
 222     CellularStateProperties? Cellular;
 223     boolean? Connectable;
 224     ConnectionStateType? ConnectionState;
 225     EthernetStateProperties? Ethernet;
 226     DOMString? ErrorState;
 227     DOMString GUID;
 228     DOMString? Name;
 229     long? Priority;
 230     DOMString? Source;
 231     NetworkType Type;
 232     VPNStateProperties? VPN;
 233     WiFiStateProperties? WiFi;
 234     WiMAXStateProperties? WiMAX;
 235   };
 236
 237   dictionary VerificationProperties {
 238     // A string containing a PEM-encoded (including the 'BEGIN CERTIFICATE'
 239     // header and 'END CERTIFICATE' footer) X.509 certificate for use in
 240     // verifying the signed data.
 241     DOMString certificate;
 242
 243     // An array of PEM-encoded X.509 intermediate certificate authority
 244     // certificates. Each PEM-encoded certificate is expected to have the
 245     // 'BEGIN CERTIFICATE' header and 'END CERTIFICATE' footer.
 246     DOMString[]? intermediateCertificates;
 247
 248     // A string containing a base64-encoded RSAPublicKey ASN.1 structure,
 249     // representing the public key to be used by
 250     // $(ref:verifyAndEncryptCredentials) and $(ref:verifyAndEncryptData)
 251     // methods.
 252     DOMString publicKey;
 253
 254     // A string containing a base64-encoded random binary data for use in
 255     // verifying the signed data.
 256     DOMString nonce;
 257
 258     // A string containing the identifying data string signed by the device.
 259     DOMString signedData;
 260
 261     // A string containing the serial number of the device.
 262     DOMString deviceSerial;
 263
 264     // A string containing the SSID of the device. Should be empty for new
 265     // configurations.
 266     DOMString deviceSsid;
 267
 268     // A string containing the BSSID of the device. Should be empty for new
 269     // configurations.
 270     DOMString deviceBssid;
 271   };
 272
 273   dictionary NetworkFilter {
 274     // The type of networks to return.
 275     NetworkType networkType;
 276
 277     // If true, only include visible (physically connected or in-range)
 278     // networks. Defaults to 'false'.
 279     boolean? visible;
 280
 281     // If true, only include configured (saved) networks. Defaults to 'false'.
 282     boolean? configured;
 283
 284     // Maximum number of networks to return. Defaults to 1000 if unspecified.
 285     // Use 0 for no limit.
 286     long? limit;
 287   };
 288
 289   callback VoidCallback = void();
 290   callback BooleanCallback = void(boolean result);
 291   callback StringCallback = void(DOMString result);
 292   // TODO(stevenjb): Use NetworkProperties for |result| once defined.
 293   callback GetPropertiesCallback = void(object result);
 294   // TODO(stevenjb): Use ManagedNetworkProperties for |result| once defined.
 295   callback GetManagedPropertiesCallback = void(object result);
 296   callback GetStatePropertiesCallback = void(NetworkStateProperties result);
 297   callback GetNetworksCallback = void(NetworkStateProperties[] result);
 298   callback GetDeviceStatesCallback = void(DeviceStateProperties[] result);
 299   callback GetEnabledNetworkTypesCallback = void(NetworkType[] result);
 300   callback CaptivePortalStatusCallback = void(CaptivePortalStatus result);
 301
 302   // These functions all report failures via chrome.runtime.lastError.
 303   interface Functions {
 304     // Gets all the properties of the network with id networkGuid. Includes all
 305     // properties of the network (read-only and read/write values).
 306     // |networkGuid|: The GUID of the network to get properties for.
 307     // |callback|: Called with the network properties when received.
 308     static void getProperties(DOMString networkGuid,
 309                               GetPropertiesCallback callback);
 310
 311     // Gets the merged properties of the network with id networkGuid from the
 312     // sources: User settings, shared settings, user policy, device policy and
 313     // the currently active settings.
 314     // |networkGuid|: The GUID of the network to get properties for.
 315     // |callback|: Called with the managed network properties when received.
 316     static void getManagedProperties(DOMString networkGuid,
 317                                      GetManagedPropertiesCallback callback);
 318
 319     // Gets the cached read-only properties of the network with id networkGuid.
 320     // This is meant to be a higher performance function than
 321     // $(ref:getProperties), which requires a round trip to query the networking
 322     // subsystem. The following properties are returned for all networks: GUID,
 323     // Type, Name, WiFi.Security. Additional properties are provided for visible
 324     // networks: ConnectionState, ErrorState, WiFi.SignalStrength,
 325     // Cellular.NetworkTechnology, Cellular.ActivationState,
 326     // Cellular.RoamingState.
 327     // |networkGuid|: The GUID of the network to get properties for.
 328     // |callback|: Called immediately with the network state properties.
 329     static void getState(DOMString networkGuid,
 330                          GetStatePropertiesCallback callback);
 331
 332     // Sets the properties of the network with id networkGuid.
 333     // |networkGuid|: The GUID of the network to set properties for.
 334     // |properties|: The properties to set.
 335     // |callback|: Called when the operation has completed.
 336     static void setProperties(DOMString networkGuid,
 337                               NetworkConfigProperties properties,
 338                               optional VoidCallback callback);
 339
 340     // Creates a new network configuration from properties. If a matching
 341     // configured network already exists, this will fail. Otherwise returns the
 342     // guid of the new network.
 343     // |shared|: If true, share this network configuration with other users.
 344     // |properties|: The properties to configure the new network with.
 345     // |callback|: Called with the GUID for the new network configuration once
 346     //     the network has been created.
 347     static void createNetwork(boolean shared,
 348                               NetworkConfigProperties properties,
 349                               optional StringCallback callback);
 350
 351     // Forgets a network configuration by clearing any configured properties for
 352     // the network with GUID 'networkGuid'. This may also include any other
 353     // networks with matching identifiers (e.g. WiFi SSID and Security). If no
 354     // such configuration exists, an error will be set and the operation will
 355     // fail.
 356     // |networkGuid|: The GUID of the network to forget.
 357     // |callback|: Called when the operation has completed.
 358     static void forgetNetwork(DOMString networkGuid,
 359                               optional VoidCallback callback);
 360
 361     // Returns a list of network objects with the same properties provided by
 362     // $(ref:networkingPrivate.getState). A filter is provided to specify the
 363     // type of networks returned and to limit the number of networks. Networks
 364     // are ordered by the system based on their priority, with connected or
 365     // connecting networks listed first.
 366     // |filter|: Describes which networks to return.
 367     // |callback|: Called with a dictionary of networks and their state
 368     //     properties when received.
 369     static void getNetworks(NetworkFilter filter,
 370                             GetNetworksCallback callback);
 371
 372     // Deprecated. Please use $(ref:networkingPrivate.getNetworks) with
 373     // filter.visible = true instead.
 374     [deprecated="Use getNetworks."] static void getVisibleNetworks(
 375         NetworkType networkType,
 376         GetNetworksCallback callback);
 377
 378     // Deprecated. Please use $(ref:networkingPrivate.getDeviceStates) instead.
 379     [deprecated="Use getDeviceStates."] static void getEnabledNetworkTypes(
 380         GetEnabledNetworkTypesCallback callback);
 381
 382     // Returns a list of $(ref:networkingPrivate.DeviceStateProperties) objects.
 383     // |callback|: Called with a list of devices and their state.
 384     static void getDeviceStates(GetDeviceStatesCallback callback);
 385
 386     // Enables any devices matching the specified network type. Note, the type
 387     // might represent multiple network types (e.g. 'Wireless').
 388     // |networkType|: The type of network to enable.
 389     static void enableNetworkType(NetworkType networkType);
 390
 391     // Disables any devices matching the specified network type. See note for
 392     // $(ref:networkingPrivate.enableNetworkType).
 393     // |networkType|: The type of network to disable.
 394     static void disableNetworkType(NetworkType networkType);
 395
 396     // Requests that the networking subsystem scan for new networks and
 397     // update the list returned by $(ref:getVisibleNetworks). This is only a
 398     // request: the network subsystem can choose to ignore it.  If the list
 399     // is updated, then the $(ref:onNetworkListChanged) event will be fired.
 400     static void requestNetworkScan();
 401
 402     // Starts a connection to the network with networkGuid.
 403     // |networkGuid|: The GUID of the network to connect to.
 404     // |callback|: Called when the connect request has been sent. Note: the
 405     //     connection may not have completed. Observe $(ref:onNetworksChanged)
 406     //     to be notified when a network state changes.
 407     static void startConnect(DOMString networkGuid,
 408                              optional VoidCallback callback);
 409
 410     // Starts a disconnect from the network with networkGuid.
 411     // |networkGuid|: The GUID of the network to disconnect from.
 412     // |callback|: Called when the disconnect request has been sent. See note
 413     //     for $(ref:startConnect).
 414     static void startDisconnect(DOMString networkGuid,
 415                                 optional VoidCallback callback);
 416
 417     // Starts activation of the Cellular network with networkGuid. If called
 418     // for a network that is already activated, or for a network with a carrier
 419     // that can not be directly activated, this will show the account details
 420     // page for the carrier if possible.
 421     // |networkGuid|: The GUID of the Cellular network to activate.
 422     // |carrier|: Optional name of carrier to activate.
 423     // |callback|: Called when the activation request has been sent. See note
 424     //     for $(ref:startConnect).
 425     static void startActivate(DOMString networkGuid,
 426                               optional DOMString carrier,
 427                               optional VoidCallback callback);
 428
 429     // Verifies that the device is a trusted device.
 430     // |properties|: Properties of the destination to use in verifying that it
 431     //     is a trusted device.
 432     // |callback|: A callback function that indicates whether or not the device
 433     //     is a trusted device.
 434     static void verifyDestination(VerificationProperties properties,
 435                                   BooleanCallback callback);
 436
 437     // Verifies that the device is a trusted device and retrieves encrypted
 438     // network credentials.
 439     // |properties|: Properties of the destination to use in verifying that it
 440     //     is a trusted device.
 441     // |networkGuid|: The GUID of the Cellular network to activate.
 442     // |callback|: A callback function that receives base64-encoded encrypted
 443     //     credential data to send to a trusted device.
 444     static void verifyAndEncryptCredentials(VerificationProperties properties,
 445                                             DOMString networkGuid,
 446                                             StringCallback callback);
 447
 448     // Verifies that the device is a trusted device and encrypts supplied
 449     // data with device public key.
 450     // |properties|: Properties of the destination to use in verifying that it
 451     //     is a trusted device.
 452     // |data|: A string containing the base64-encoded data to encrypt.
 453     // |callback|: A callback function that receives base64-encoded encrypted
 454     //     data to send to a trusted device.
 455     static void verifyAndEncryptData(VerificationProperties properties,
 456                                      DOMString data,
 457                                      StringCallback callback);
 458
 459     // Enables TDLS for WiFi traffic with a specified peer if available.
 460     // |ip_or_mac_address|: The IP or MAC address of the peer with which to
 461     //     enable a TDLS connection.
 462     // |enabled| If true, enable TDLS, otherwise disable TDLS.
 463     // |callback|: A callback function that receives a string with an error or
 464     //     the current TDLS status. 'Failed' indicates that the request failed
 465     //     (e.g. MAC address lookup failed). 'Timeout' indicates that the lookup
 466     //     timed out. Otherwise a valid status is returned (see
 467     //     $(ref:getWifiTDLSStatus)).
 468     static void setWifiTDLSEnabledState(DOMString ip_or_mac_address,
 469                                         boolean enabled,
 470                                         optional StringCallback callback);
 471
 472     // Returns the current TDLS status for the specified peer.
 473     // |ip_or_mac_address|: The IP or MAC address of the peer.
 474     // |callback|: A callback function that receives a string with the current
 475     //     TDLS status which can be 'Connected', 'Disabled', 'Disconnected',
 476     //     'Nonexistent', or 'Unknown'.
 477     static void getWifiTDLSStatus(DOMString ip_or_mac_address,
 478                                   StringCallback callback);
 479
 480     // Returns captive portal status for the network matching 'networkGuid'.
 481     // |networkGuid|: The GUID of the network to get captive portal status for.
 482     // |callback|: A callback function that returns the results of the query for
 483     //     network captive portal status.
 484     static void getCaptivePortalStatus(DOMString networkGuid,
 485                                        CaptivePortalStatusCallback callback);
 486
 487     // Unlocks a Cellular SIM card.
 488     // * If the SIM is PIN locked, |pin| will be used to unlock the SIM and
 489     //   the |puk| argument will be ignored if provided.
 490     // * If the SIM is PUK locked, |puk| and |pin| must be provided. If the
 491     //   operation succeds (|puk| is valid), the PIN will be set to |pin|.
 492     //   (If |pin| is empty or invalid the operation will fail).
 493     // |networkGuid|: The GUID of the cellular network to unlock.
 494     // |pin|: The current SIM PIN, or the new PIN if PUK is provided.
 495     // |puk|: The operator provided PUK for unblocking a blocked SIM.
 496     // |callback|: Called when the operation has completed.
 497     static void unlockCellularSim(DOMString networkGuid,
 498                                   DOMString pin,
 499                                   optional DOMString puk,
 500                                   optional VoidCallback callback);
 501
 502     // Sets whether or not SIM locking is enabled (i.e a PIN will be required
 503     // when the device is powered) and changes the PIN if a new PIN is
 504     // specified. If the new PIN is provided but not valid (e.g. too short)
 505     // the operation will fail. This will not lock the SIM; that is handled
 506     // automatically by the device. NOTE: If the SIM is locked, it must first be
 507     // unlocked with unlockCellularSim() before this can be called (otherwise it
 508     // will fail and chrome.runtime.lastError will be set to Error.SimLocked).
 509     // |networkGuid|: The GUID of the cellular network to set the SIM state of.
 510     // |simState|: The SIM state to set.
 511     // |callback|: Called when the operation has completed.
 512     static void setCellularSimState(DOMString networkGuid,
 513                                     CellularSimState simState,
 514                                     optional VoidCallback callback);
 515   };
 516
 517   interface Events {
 518     // Fired when the properties change on any of the networks.  Sends a list of
 519     // GUIDs for networks whose properties have changed.
 520     static void onNetworksChanged(DOMString[] changes);
 521
 522     // Fired when the list of networks has changed.  Sends a complete list of
 523     // GUIDs for all the current networks.
 524     static void onNetworkListChanged(DOMString[] changes);
 525
 526     // Fired when the list of devices has changed or any device state properties
 527     // have changed.
 528     static void onDeviceStateListChanged();
 529
 530     // Fired when a portal detection for a network completes. Sends the guid of
 531     // the network and the corresponding captive portal status.
 532     static void onPortalDetectionCompleted(DOMString networkGuid,
 533                                            CaptivePortalStatus status);
 534   };
 535 };