wpa_supplicant D-Bus API

This section documents the wpa_supplicant D-Bus API. Every D-Bus interface implemented by wpa_supplicant is described here including their methods, signals, and properties with arguments, returned values, and possible errors.

Interfaces:

• fi.w1.wpa_supplicant1
• fi.w1.wpa_supplicant1.Interface
• fi.w1.wpa_supplicant1.Interface.WPS
• fi.w1.wpa_supplicant1.BSS
• fi.w1.wpa_supplicant1.Network

fi.w1.wpa_supplicant1

Interface implemented by the main wpa_supplicant D-Bus object registered in the bus with fi.w1.wpa_supplicant1 name.

Methods

• CreateInterface ( a{sv} : args ) --> o : interface

  Registers a wireless interface in wpa_supplicant.

  Arguments

  a{sv} : args

  A dictionary with arguments used to add the interface to wpa_supplicant. The dictionary may contain the following entries:

  Key	Value type	Description	Required
  Ifname	s	Name of the network interface to control, e.g., wlan0	Yes
  Bridge_ifname	s	Name of the bridge interface to control, e.g., br0	No
  Driver	s	Driver name which the interface uses, e.g., nl80211	No

  Returns

  o : interface

  A D-Bus path to object representing created interface

  Possible errors

  fi.w1.wpa_supplicant1.InterfaceExists

  wpa_supplicant already controls this interface.

  fi.w1.wpa_supplicant1.UnknownError

  Creating interface failed for an unknown reason.

  fi.w1.wpa_supplicant1.InvalidArgs

  Invalid entries were found in the passed argument.

• RemoveInterface ( o : interface ) --> nothing

  Deregisters a wireless interface from wpa_supplicant.

  Arguments

  o : interface

  A D-Bus path to an object representing an interface to remove returned by CreateInterface

  Possible errors

  fi.w1.wpa_supplicant1.InterfaceUnknown

  Object pointed by the path doesn't exist or doesn't represent an interface.

  fi.w1.wpa_supplicant1.UnknownError

  Removing interface failed for an unknown reason.

• GetInterface ( s : ifname ) --> o : interface

  Returns a D-Bus path to an object related to an interface which wpa_supplicant already controls.

  Arguments

  s : ifname

  Name of the network interface, e.g., wlan0

  Returns

  o : interface

  A D-Bus path to an object representing an interface

  Possible errors

  fi.w1.wpa_supplicant1.InterfaceUnknown

  An interface with the passed name in not controlled by wpa_supplicant.

  fi.w1.wpa_supplicant1.UnknownError

  Getting an interface object path failed for an unknown reason.

Properties

• DebugLevel - s - (read/write)

  Global wpa_supplicant debugging level. Possible values are "msgdump" (verbose debugging), "debug" (debugging), "info" (informative), "warning" (warnings), and "error" (errors).

• DebugTimestamp - b - (read/write)

  Global wpa_supplicant debugging parameter. Determines if timestamps are shown in debug logs.

• DebugShowKeys - b - (read/write)

  Global wpa_supplicant debugging parameter. Determines if secrets are shown in debug logs.

• Interfaces - ao - (read)

  An array with paths to D-Bus objects representing controlled interfaces each.

• EapMethods - as - (read)

  An array with supported EAP methods names.

Signals

• InterfaceAdded ( o : interface, a{sv} : properties )

  A new interface was added to wpa_supplicant.

  Arguments

  o : interface

  A D-Bus path to an object representing the added interface

  a{sv} : properties

  A dictionary containing properties of added interface.

• InterfaceRemoved ( o : interface )

  An interface was removed from wpa_supplicant.

  Arguments

  o : interface

  A D-Bus path to an object representing the removed interface

• PropertiesChanged ( a{sv} : properties )

  Some properties have changed.

  Arguments

  a{sv} : properties

  A dictionary with pairs of properties names which have changed and theirs new values. Possible dictionary keys are: "DebugParams"

fi.w1.wpa_supplicant1.Interface

Interface implemented by objects related to network interface added to wpa_supplicant, i.e., returned by fi.w1.wpa_supplicant1.CreateInterface.

Methods

• Scan ( a{sv} : args ) --> nothing

  Triggers a scan.

  Arguments

  a{sv} : args

  A dictionary with arguments describing scan type:

  Key	Value type	Description	Required
  Type	s	Type of the scan. Possible values: "active", "passive"	Yes
  SSIDs	aay	Array of SSIDs to scan for (applies only if scan type is active)	No
  IEs	aay	Information elements to used in active scan (applies only if scan type is active)	No
  Channels	a(uu)	Array of frequencies to scan in form of (center, width) in MHz.	No

  Possible errors

  fi.w1.wpa_supplicant1.InvalidArgs

  Invalid entries were found in the passed argument.

• Disconnect ( ) --> nothing

  Disassociates the interface from current network.

  Possible errors

  fi.w1.wpa_supplicant1.NotConnected

  Interface is not connected to any network.

• AddNetwork ( a{sv} : args ) --> o : network

  Adds a new network to the interface.

  Arguments

  a{sv} : args

  A dictionary with network configuration. Dictionary entries are equivalent to entries in the "network" block in wpa_supplicant configuration file. Entry values should be appropriate type to the entry, e.g., an entry with key "frequency" should have value type int.

  Returns

  o : network

  A D-Bus path to an object representing a configured network

  Possible errors

  fi.w1.wpa_supplicant1.InvalidArgs

  Invalid entries were found in the passed argument.

  fi.w1.wpa_supplicant1.UnknownError

  Adding network failed for an unknown reason.

• RemoveNetwork ( o : network ) --> nothing

  Removes a configured network from the interface.

  Arguments

  o : network

  A D-Bus path to an object representing a configured network returned by fi.w1.wpa_supplicant1.Interface.AddNetwork

  Possible errors

  fi.w1.wpa_supplicant1.NetworkUnknown

  A passed path doesn't point to any network object.

  fi.w1.wpa_supplicant1.InvalidArgs

  A passed path doesn't point to any network object.

  fi.w1.wpa_supplicant1.UnknownError

  Removing network failed for an unknown reason.

• SelectNetwork ( o : network ) --> nothing

  Attempt association with a configured network.

  Arguments

  o : network

  A D-Bus path to an object representing a configured network returned by fi.w1.wpa_supplicant1.Interface.AddNetwork

  Possible errors

  fi.w1.wpa_supplicant1.NetworkUnknown

  A passed path doesn't point to any network object.

  fi.w1.wpa_supplicant1.InvalidArgs

  A passed path doesn't point to any network object.

• AddBlob ( s : name, ay : data ) --> nothing

  Adds a blob to the interface.

  Arguments

  s : name

  A name of a blob

  ay : data

  A blob data

  Possible errors

  fi.w1.wpa_supplicant1.BlobExists

  A blob with the specified name already exists.

• RemoveBlob ( s : name ) --> nothing

  Removes the blob from the interface.

  Arguments

  s : name

  A name of the blob to remove

  Possible errors

  fi.w1.wpa_supplicant1.BlobUnknown

  A blob with the specified name doesn't exist.

• GetBlob ( s : name ) --> ay : data

  Returns the blob data of a previously added blob.

  Arguments

  s : name

  A name of the blob

  Returns

  ay : data

  A blob data

  Possible errors

  fi.w1.wpa_supplicant1.BlobUnknown

  A blob with the specified name doesn't exist.

Properties

• Capabilities - a{sv} - (read)

  Capabilities of the interface. Dictionary contains following entries:

  Key	Value type	Description
  Pairwise	as	Possible array elements: "ccmp", "tkip", "none"
  Group	as	Possible array elements: "ccmp", "tkip", "wep104", "wep40"
  KeyMgmt	as	Possible array elements: "wpa-psk", "wpa-ft-psk", "wpa-psk-sha256", "wpa-eap", "wpa-ft-eap", "wpa-eap-sha256", "ieee8021x", "wpa-none", "wps", "none"
  Protocol	as	Possible array elements: "rsn", "wpa"
  AuthAlg	as	Possible array elements: "open", "shared", "leap"
  Scan	as	Possible array elements: "active", "passive", "ssid"
  Modes	as	Possible array elements: "infrastructure", "ad-hoc", "ap"

• State - s - (read)

  A state of the interface. Possible values are: return "disconnected", "inactive", "scanning", "authenticating", "associating", "associated", "4way_handshake", "group_handshake", "completed","unknown".

• Scanning - b - (read)

  Determines if the interface is already scanning or not

• ApScan - u - (read/write)

  Identical to ap_scan entry in wpa_supplicant configuration file. Possible values are 0, 1 or 2.

• BSSExpireAge - u - (read/write)

  Identical to bss_expiration_age entry in wpa_supplicant configuration file.

• BSSExpireCount - u - (read/write)

  Identical to bss_expiration_scan_count entry in wpa_supplicant configuration file.

• Country - s - (read/write)

  Identical to country entry in wpa_supplicant configuration file.

• Ifname - s - (read)

  Name of network interface controlled by the interface, e.g., wlan0.

• BridgeIfname - s - (read)

  Name of bridge network interface controlled by the interface, e.g., br0.

• Driver - s - (read)

  Name of driver used by the interface, e.g., nl80211.

• CurrentBSS - o - (read)

  Path to D-Bus object representing BSS which wpa_supplicant is associated with, or "/" if is not associated at all.

• CurrentNetwork - o - (read)

  Path to D-Bus object representing configured network which wpa_supplicant uses at the moment, or "/" if doesn't use any.

• Blobs - as - (read)

  List of blobs names added to the Interface.

• BSSs - ao - (read)

  List of D-Bus objects paths representing BSSs known to the interface, i.e., scan results.

• Networks - ao - (read)

  List of D-Bus objects paths representing configured networks.

• FastReauth - b - (read/write)

  Identical to fast_reauth entry in wpa_supplicant configuration file.

• ScanInterval - i - (read/write)

  Time (in seconds) between scans for a suitable AP. Must be >= 0.

Signals

• ScanDone ( b : success )

  Scanning finished.

  Arguments

  s : success

  Determines if scanning was successful. If so, results are available.

• BSSAdded ( o : BSS, a{sv} : properties )

  Interface became aware of a new BSS.

  Arguments

  o : BSS

  A D-Bus path to an object representing the new BSS.

  a{sv} : properties

  A dictionary containing properties of added BSS.

• BSSRemoved ( o : BSS )

  BSS disappeared.

  Arguments

  o : BSS

  A D-Bus path to an object representing the BSS.

• BlobAdded ( s : blobName )

  A new blob has been added to the interface.

  Arguments

  s : blobName

  A name of the added blob.

• BlobRemoved ( s : blobName )

  A blob has been removed from the interface.

  Arguments

  s : blobName

  A name of the removed blob.

• NetworkAdded ( o : network, a{sv} : properties )

  A new network has been added to the interface.

  Arguments

  o : network

  A D-Bus path to an object representing the added network.

  a{sv} : properties

  A dictionary containing properties of added network.

• NetworkRemoved ( o : network )

  The network has been removed from the interface.

  Arguments

  o : network

  A D-Bus path to an object representing the removed network.

• NetworkSelected ( o : network )

  The network has been selected.

  Arguments

  o : network

  A D-Bus path to an object representing the selected network.

• PropertiesChanged ( a{sv} : properties )

  Some properties have changed.

  Arguments

  a{sv} : properties

  A dictionary with pairs of properties names which have changed and theirs new values. Possible dictionary keys are: "ApScan", "Scanning", "State", "CurrentBSS", "CurrentNetwork"

fi.w1.wpa_supplicant1.Interface.WPS

Interface implemented by objects related to network interface added to wpa_supplicant, i.e., returned by fi.w1.wpa_supplicant1.CreateInterface.

Methods

• Start ( a{sv} : args ) --> a{sv} : output

  Starts WPS configuration.

  Arguments

  a{sv} : args

  A dictionary with arguments used to start WPS configuration. The dictionary may contain the following entries:

  Key	Value type	Description	Required
  Role	s	The device's role. Possible values are "enrollee" and "registrar".	Yes
  Type	s	WPS authentication type. Applies only for enrollee role. Possible values are "pin" and "pbc".	Yes, for enrollee role; otherwise no
  Pin	s	WPS Pin.	Yes, for registrar role; otherwise optional
  Bssid	ay		No

  Returns

  a{sv} : output

  Key	Value type	Description	Required
  Pin	s	Newly generated PIN, if not specified for enrollee role and pin authentication type.	No

  Possible errors

  fi.w1.wpa_supplicant1.UnknownError

  Starting WPS configuration failed for an unknown reason.

  fi.w1.wpa_supplicant1.InvalidArgs

  Invalid entries were found in the passed argument.

Properties

• ProcessCredentials - b - (read/write)

  Determines if the interface will process the credentials (credentials_processed configuration file parameter).

Signals

• Event ( s : name, a{sv} : args )

  WPS event occurred.

  Arguments

  s : event

  Event type. Possible values are: "success, "fail" and "m2d"

  a{sv} : args

  Event arguments. Empty for success event, one entry ( "msg" : i ) for fail event and following entries for m2d event:

  config_methods	Value type
  manufacturer	q
  model_name	ay
  model_number	ay
  serial_number	ay
  dev_name	ay
  primary_dev_type	ay
  config_error	q
  dev_password_id	q

• Credentials ( a{sv} : credentials )

  WPS credentials. Dictionary contains:

  Key	Value type	Description
  BSSID	ay
  SSID	s
  AuthType	as	Possible array elements: "open", "shared", "wpa-psk", "wpa-eap", "wpa2-eap", "wpa2-psk"
  EncrType	as	Possible array elements: "none", "wep", "tkip", "aes"
  Key	ay	Key data
  KeyIndex	u	Key index

• PropertiesChanged ( a{sv} : properties )

  Some properties have changed.

  Arguments

  a{sv} : properties

  A dictionary with pairs of properties names which have changed and theirs new values. Possible dictionary keys are: "ProcessCredentials"

fi.w1.wpa_supplicant1.BSS

Interface implemented by objects representing a scanned BSSs, i.e., scan results.

Properties

• BSSID - ay - (read)

  BSSID of the BSS.

• SSID - ay - (read)

  SSID of the BSS.

• WPA - a{sv} - (read)

  WPA information of the BSS. Empty dictionary indicates no WPA support. Dictionary entries are:

  KeyMgmt	as	Key management suite. Possible array elements: "wpa-psk", "wpa-eap", "wpa-none"
  Pairwise	as	Pairwise cipher suites. Possible array elements: "ccmp", "tkip"
  Group	s	Group cipher suite. Possible values are: "ccmp", "tkip", "wep104", "wep40"

• RSN - a{sv} - (read)

  RSN information of the BSS. Empty dictionary indicates no RSN support. Dictionary entries are:

  KeyMgmt	as	Key management suite. Possible array elements: "wpa-psk", "wpa-eap", "wpa-ft-psk", "wpa-ft-eap", "wpa-psk-sha256", "wpa-eap-sha256",
  Pairwise	as	Pairwise cipher suites. Possible array elements: "ccmp", "tkip"
  Group	s	Group cipher suite. Possible values are: "ccmp", "tkip", "wep104", "wep40"
  MgmtGroup	s	Mangement frames cipher suite. Possible values are: "aes128cmac"

• IEs - ay - (read)

  All IEs of the BSS as a chain of TLVs

• Privacy - b - (read)

  Indicates if BSS supports privacy.

• Mode - s - (read)

  Describes mode of the BSS. Possible values are: "ad-hoc" and "infrastructure".

• Frequency - q - (read)

  Frequency of the BSS in MHz.

• Rates - au - (read)

  Descending ordered array of rates supported by the BSS in bits per second.

• Signal - n - (read)

  Signal strength of the BSS.

Signals

• PropertiesChanged ( a{sv} : properties )

  Some properties have changed.

  Arguments

  a{sv} : properties

  A dictionary with pairs of properties names which have changed and theirs new values.

fi.w1.wpa_supplicant1.Network

Interface implemented by objects representing configured networks, i.e., returned by fi.w1.wpa_supplicant1.Interface.AddNetwork.

Properties

• Enabled - b - (read/write)

  Determines if the configured network is enabled or not.

• Properties - a{sv} - (read)

  Properties of the configured network. Dictionary contains entries from "network" block of wpa_supplicant configuration file. All values are string type, e.g., frequency is "2437", not 2437.

Signals

• PropertiesChanged ( a{sv} : properties )

  Some properties have changed.

  Arguments

  a{sv} : properties

  A dictionary with pairs of properties names which have changed and theirs new values. Possible dictionary keys are: "Enabled"