driver_wrapper.doxygen 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. /**
  2. \page driver_wrapper Driver wrapper implementation (driver.h, drivers.c)
  3. All hardware and driver dependent functionality is in separate C files
  4. that implement defined wrapper functions. Other parts
  5. of the wpa_supplicant are designed to be hardware, driver, and operating
  6. system independent.
  7. Driver wrappers need to implement whatever calls are used in the
  8. target operating system/driver for controlling wireless LAN
  9. devices. As an example, in case of Linux, these are mostly some glue
  10. code and ioctl() calls and netlink message parsing for Linux Wireless
  11. Extensions (WE). Since features required for WPA were added only recently to
  12. Linux Wireless Extensions (in version 18), some driver specific code is used
  13. in number of driver interface implementations. These driver dependent parts
  14. can be replaced with generic code in \ref driver_wext.c once the target driver
  15. includes full support for WE-18. After that, all Linux drivers, at
  16. least in theory, could use the same driver wrapper code.
  17. A driver wrapper needs to implement some or all of the functions
  18. defined in \ref driver.h. These functions are registered by filling struct
  19. \ref wpa_driver_ops with function pointers. Hardware independent parts of
  20. wpa_supplicant will call these functions to control the driver/wlan
  21. card. In addition, support for driver events is required. The event
  22. callback function, \ref wpa_supplicant_event(), and its parameters are
  23. documented in \ref driver.h. In addition, a pointer to the 'struct
  24. \ref wpa_driver_ops' needs to be registered in \ref drivers.c file.
  25. When porting to other operating systems, the driver wrapper should be
  26. modified to use the native interface of the target OS. It is possible
  27. that some extra requirements for the interface between the driver
  28. wrapper and generic wpa_supplicant code are discovered during porting
  29. to a new operating system. These will be addressed on case by case
  30. basis by modifying the interface and updating the other driver
  31. wrappers for this. The goal is to avoid changing this interface
  32. without very good reasons in order to limit the number of changes
  33. needed to other wrappers and hardware independent parts of
  34. wpa_supplicant. When changes are required, recommended way is to
  35. make them in backwards compatible way that allows existing driver
  36. interface implementations to be compiled without any modification.
  37. Generic Linux Wireless Extensions functions are implemented in
  38. \ref driver_wext.c. All Linux driver wrappers can use these when the kernel
  39. driver supports the generic ioctl()s and wireless events. Driver
  40. specific functions are implemented in separate C files, e.g.,
  41. \ref driver_hostap.c. These files need to define struct \ref wpa_driver_ops
  42. entry that will be used in \ref wpa_supplicant.c when calling driver
  43. functions. struct \ref wpa_driver_ops entries are registered in \ref drivers.c.
  44. In general, it is likely to be useful to first take a look at couple
  45. of driver interface examples before starting on implementing a new
  46. one. \ref driver_hostap.c and \ref driver_wext.c include a complete
  47. implementation for Linux drivers that use wpa_supplicant-based control
  48. of WPA IE and roaming. \ref driver_ndis.c (with help from \ref driver_ndis_.c)
  49. is an example of a complete interface for Windows NDIS interface for
  50. drivers that generate WPA IE themselves and decide when to roam. These
  51. example implementations include full support for all security modes.
  52. \section driver_req Driver requirements for WPA
  53. WPA introduces new requirements for the device driver. At least some
  54. of these need to be implemented in order to provide enough support for
  55. wpa_supplicant.
  56. \subsection driver_tkip_ccmp TKIP/CCMP
  57. WPA requires that the pairwise cipher suite (encryption algorithm for
  58. unicast data packets) is TKIP or CCMP. These are new encryption
  59. protocols and thus, the driver will need to be modified to support
  60. them. Depending on the used wlan hardware, some parts of these may be
  61. implemented by the hardware/firmware.
  62. Specification for both TKIP and CCMP is available from IEEE (IEEE
  63. 802.11i amendment). Fully functional, hardware independent
  64. implementation of both encryption protocols is also available in Host
  65. AP driver (driver/modules/hostap_{tkip,ccmp}.c). In addition, Linux 2.6
  66. kernel tree has generic implementations for WEP, TKIP, and CCMP that can
  67. be used in Linux drivers.
  68. The driver will also need to provide configuration mechanism to allow
  69. user space programs to configure TKIP and CCMP. Linux Wireless Extensions
  70. v18 added support for configuring these algorithms and
  71. individual/non-default keys. If the target kernel does not include WE-18,
  72. private ioctls can be used to provide similar functionality.
  73. \subsection driver_roaming Roaming control and scanning support
  74. wpa_supplicant can optionally control AP selection based on the
  75. information received from Beacon and/or Probe Response frames
  76. (ap_scan=1 mode in configuration). This means that the driver should
  77. support external control for scan process. In case of Linux, use of
  78. new Wireless Extensions scan support (i.e., 'iwlist wlan0 scan') is
  79. recommended. The current driver wrapper (\ref driver_wext.c) uses this for
  80. scan results.
  81. Scan results must also include the WPA information element. Support for
  82. this was added in WE-18. With older versions, a custom event can be used
  83. to provide the full WPA IE (including element id and length) as a hex
  84. string that is included in the scan results.
  85. wpa_supplicant needs to also be able to request the driver to
  86. associate with a specific BSS. Current Host AP driver and matching
  87. \ref driver_hostap.c wrapper uses following sequence for this
  88. request. Similar/identical mechanism should be usable also with other
  89. drivers.
  90. - set WPA IE for AssocReq with private ioctl
  91. - set SSID with SIOCSIWESSID
  92. - set channel/frequency with SIOCSIWFREQ
  93. - set BSSID with SIOCSIWAP
  94. (this last ioctl will trigger the driver to request association)
  95. \subsection driver_wpa_ie WPA IE generation
  96. wpa_supplicant selects which cipher suites and key management suites
  97. are used. Based on this information, it generates a WPA IE. This is
  98. provided to the driver interface in the associate call. This does not
  99. match with Windows NDIS drivers which generate the WPA IE
  100. themselves.
  101. wpa_supplicant allows Windows NDIS-like behavior by providing the
  102. selected cipher and key management suites in the associate call. If
  103. the driver generates its own WPA IE and that differs from the one
  104. generated by wpa_supplicant, the driver has to inform wpa_supplicant
  105. about the used WPA IE (i.e., the one it used in (Re)Associate
  106. Request). This notification is done using EVENT_ASSOCINFO event (see
  107. \ref driver.h). wpa_supplicant is normally configured to use
  108. ap_scan=2 mode with drivers that control WPA IE generation and roaming.
  109. \subsection driver_events Driver events
  110. wpa_supplicant needs to receive event callbacks when certain events
  111. occur (association, disassociation, Michael MIC failure, scan results
  112. available, PMKSA caching candidate). These events and the callback
  113. details are defined in \ref driver.h (\ref wpa_supplicant_event() function
  114. and enum \ref wpa_event_type).
  115. On Linux, association and disassociation can use existing Wireless
  116. Extensions event that is reporting new AP with SIOCGIWAP
  117. event. Similarly, completion of a scan can be reported with SIOCGIWSCAN
  118. event.
  119. Michael MIC failure event was added in WE-18. Older versions of Wireless
  120. Extensions will need to use a custom event. Host AP driver used a custom
  121. event with following contents: MLME-MICHAELMICFAILURE.indication(keyid=#
  122. broadcast/unicast addr=addr2). This is the recommended format until
  123. the driver can be moved to use WE-18 mechanism.
  124. \subsection driver_wext_summary Summary of Linux Wireless Extensions use
  125. AP selection depends on ap_scan configuration:
  126. ap_scan=1:
  127. - wpa_supplicant requests scan with SIOCSIWSCAN
  128. - driver reports scan complete with wireless event SIOCGIWSCAN
  129. - wpa_supplicant reads scan results with SIOCGIWSCAN (multiple call if
  130. a larget buffer is needed)
  131. - wpa_supplicant decides which AP to use based on scan results
  132. - wpa_supplicant configures driver to associate with the selected BSS
  133. (SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWFREQ,
  134. SIOCSIWESSID, SIOCSIWAP)
  135. ap_scan=2:
  136. - wpa_supplicant configures driver to associate with an SSID
  137. (SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWESSID)
  138. After this, both modes use similar steps:
  139. - optionally (or required for drivers that generate WPA/RSN IE for
  140. (Re)AssocReq), driver reports association parameters (AssocReq IEs)
  141. with wireless event IWEVASSOCREQIE (and optionally IWEVASSOCRESPIE)
  142. - driver reports association with wireless event SIOCGIWAP
  143. - wpa_supplicant takes care of EAPOL frame handling (validating
  144. information from associnfo and if needed, from scan results if WPA/RSN
  145. IE from the Beacon frame is not reported through associnfo)
  146. */