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