developer.txt

   1 Developer notes for wpa_supplicant
   2 ==================================
   3
   4 The design goal for wpa_supplicant was to use hardware, driver, and OS
   5 independent, portable C code for all WPA functionality. All
   6 hardware/driver specific functionality is in separate files that
   7 implement a well-defined driver API.
   8
   9 The goal of this file and the comments in the header files is to give
  10 enough information for other developers to be able to port the example
  11 code. If any information is missing, feel free to contact Jouni Malinen
  12 <jkmaline@cc.hut.fi> for more information. Contributions as patch files
  13 are also very welcome at the same address.
  14
  15 Structure of the source code
  16 ----------------------------
  17
  18 Program initialization, main control loop and event handling is
  19 implemented in wpa_supplicant.c. WPA state machines and 4-Way/Group
  20 Key Handshake processing in in wpa.c. IEEE 802.1X/EAPOL processing and
  21 state machines are in eapol_sm.c. EAP state machine is in eap.c. EAP
  22 methods for the internal EAP peer are in eap_*.c.  Parser for the
  23 configuration file is implemented in config.c.
  24
  25 Driver interface API is defined in driver.h and all hardware/driver
  26 dependent functionality is implemented in driver_*.c (see below).
  27
  28
  29 Generic helper functions
  30 ------------------------
  31
  32 wpa_supplicant uses generic helper functions some of which are shared
  33 with with hostapd. The following C files are currently used:
  34
  35 eloop.[ch]
  36         event loop (select() loop with registerable timeouts, socket read
  37         callbacks, and signal callbacks)
  38
  39 common.[ch]
  40         common helper functions
  41
  42 defs.h
  43         definitions shared by multiple files
  44
  45 l2_packet.[ch]
  46         Layer 2 (link) access wrapper (includes native Linux implementation
  47         and wrappers for libdnet/libpcap)
  48
  49 pcsc_funcs.[ch]
  50         Wrapper for PC/SC lite SIM and smart card readers
  51
  52
  53 Cryptographic functions
  54 -----------------------
  55
  56 md5.c
  57         MD5 (replaced with openssl/crypto if TLS support is included)
  58         HMAC-MD5 (keyed checksum for message authenticity validation)
  59
  60 rc4.c
  61         RC4 (broadcast/default key encryption)
  62
  63 sha1.c
  64         SHA-1 (replaced with openssl/crypto if TLS support is included)
  65         HMAC-SHA-1 (keyed checksum for message authenticity validation)
  66         PRF-SHA-1 (pseudorandom (key/nonce generation) function)
  67         PBKDF2-SHA-1 (ASCII passphrase to shared secret)
  68         T-PRF (for EAP-FAST)
  69         TLS-PRF (RFC 2246)
  70
  71 aes_wrap.[ch], aes.c
  72         AES
  73         AES Key Wrap Algorithm with 128-bit KEK, RFC3394 (broadcast/default
  74         key encryption)
  75         One-Key CBC MAC (OMAC1) hash with AES-128
  76         AES-128 CTR mode encryption
  77         AES-128 EAX mode encryption/decryption
  78         AES-128 CBC
  79
  80 crypto.[ch]
  81         Wrapper functions for libcrypto (MD4 and DES)
  82
  83 ms_funcs.[ch]
  84         Helper functions for MSCHAPV2 and LEAP
  85
  86 tls.h
  87         Definition of TLS library wrapper
  88
  89 tls_none.c
  90         Dummy implementation of TLS library wrapper for cases where TLS
  91         functionality is not included.
  92
  93 tls_openssl.c
  94         TLS library wrapper for openssl
  95
  96
  97 Configuration
  98 -------------
  99
 100 config_ssid.h
 101         Definition of per network configuration items
 102
 103 config.h
 104         Definition of the wpa_supplicant configuration
 105
 106 config.c
 107         Configuration file parser
 108
 109
 110 Control interface
 111 -----------------
 112
 113 wpa_supplicant has a control interface that can be used to get status
 114 information and manage operations from external programs. An example,
 115 command line interface, wpa_cli, for this interface is included in the
 116 wpa_supplicant distribution.
 117
 118 ctrl_iface.[ch]
 119         wpa_supplicant-side of the control interface
 120
 121 wpa_ctrl.[ch]
 122         Library functions for external programs to provide access to the
 123         wpa_supplicant control interface
 124
 125 wpa_cli.c
 126         Example program for using wpa_supplicant control interface
 127
 128
 129 EAP peer
 130 --------
 131
 132 eap.[ch]
 133         EAP state machine
 134
 135 eap_defs.h
 136         Common EAP definitions
 137
 138 eap_i.h
 139         Internal definitions for EAP state machine and EAP methods
 140
 141 eap_sim_common.[ch]
 142         Common code for EAP-SIM and EAP-AKA
 143
 144 eap_tls_common.[ch]
 145         Common code for EAP-PEAP, EAP-TTLS, and EAP-FAST
 146
 147 eap_tlv.[ch]
 148         EAP-TLV code for EAP-PEAP and EAP-FAST
 149
 150 eap_{aka,fast,gtc,leap,md5,mschapv2,otp,peap,psk,sim,tls,ttls}.c
 151         EAP method implementations
 152
 153
 154 EAPOL supplicant
 155 ----------------
 156
 157 eapol_sm.[ch]
 158         EAPOL supplicant state machine and IEEE 802.1X processing
 159
 160
 161 Windows port
 162 ------------
 163
 164 ndis_events.cpp
 165         External program for receiving NdisMIndicateStatus() events and
 166         delivering them to wpa_supplicant in more easier to use form
 167
 168 win_if_list.c
 169         External program for listing current network interface
 170
 171
 172 Test programs
 173 -------------
 174
 175 radius_client.[ch]
 176         RADIUS authentication client implementation for eapol_test
 177
 178 eapol_test.c
 179         Standalone EAP testing tool with integrated RADIUS authentication
 180         client
 181
 182 preauth_test.c
 183         Standalone RSN pre-authentication tool
 184
 185
 186 wpa_supplicant.c
 187 ----------------
 188
 189 main()
 190 - parse command line
 191 - call config file parser
 192 - initialize Supplicant data structures
 193 - call functions to initialize WPA support in the driver
 194 - initialize event loop
 195 - cleanup when exiting
 196
 197 wpa_supplicant_dot1x_receive()
 198 - receive master session key update from Xsupplicant (optional)
 199
 200 wpa_supplicant_get_beacon_ie()
 201
 202 wpa_supplicant_deauthenticate()
 203
 204 wpa_supplicant_disassociate()
 205
 206 wpa_supplicant_scan()
 207
 208 wpa_supplicant_reconfig()
 209 - SIGHUP signal processing
 210
 211 wpa_supplicant_terminate()
 212 - SIGINT and SIGTERM processing
 213
 214 wpa_supplicant_reload_configuration()
 215
 216 wpa_supplicant_event()
 217 - receive driver events (through driver wrapper functions)
 218   * wpa_supplicant_scan_results(): process scan result event, BSS selection
 219   * wpa_supplicant_associnfo(): process association information event
 220
 221 wpa_supplicant_associate()
 222 - control association (select cipher and key management suites, initiate
 223   association)
 224
 225 wpa_supplicant_req_auth_timeout()
 226
 227 wpa_supplicant_cancel_auth_timeout()
 228
 229 wpa_supplicant_req_scan()
 230
 231 wpa_supplicant_cancel_scan()
 232
 233 wpa_supplicant_notify_eapol_done()
 234
 235 wpa_eapol_send()
 236 - send EAPOL frames
 237
 238 wpa_eapol_send_preauth()
 239 - send RSN preauthentication frames
 240
 241 wpa_msg()
 242 - event/debug function
 243
 244
 245 wpa_supplicant.h
 246 ----------------
 247
 248 - driver event definition
 249 - common function definition (e.g., wpa_msg)
 250
 251
 252 wpa_supplicant_i.h
 253 ------------------
 254 - internal definitions for wpa_supplicant; must not be included into
 255   common code, EAP methods, driver interface implementations
 256
 257
 258 wpa.[ch]
 259 --------
 260 - WPA supplicant state machine and 4-Way/Group Key Handshake processing
 261 - PMKSA cache and RSN pre-authentication
 262
 263 pmksa_cache_free()
 264
 265 pmksa_cache_get()
 266
 267 pmksa_cache_list()
 268
 269 pmksa_candidate_free()
 270
 271 wpa_parse_wpa_ie()
 272 - WPA/RSN IE parsing
 273
 274 wpa_gen_wpa_ei()
 275 - WPA/RSN IE generation
 276
 277 wpa_supplicant_get_ssid()
 278
 279 wpa_supplicant_key_request()
 280 - trigger function to start key requests
 281
 282 wpa_sm_rx_eapol()
 283 - WPA processing for received EAPOL-Key frames
 284   * wpa_supplicant_process_1_of_4() (message 1 of 4-Way Handshake)
 285   * wpa_supplicant_process_3_of_4() (message 3 of 4-Way Handshake)
 286   * wpa_supplicant_process_1_of_2() (message 1 of Group Key Handshake)
 287
 288 wpa_supplicant_rx_eapol()
 289 - l2_packet RX callback for EAPOL frames; sends the frames to WPA and EAPOL
 290   state machines for further processing
 291
 292 wpa_get_mib()
 293
 294 rsn_preauth_receive()
 295 - l2_packet RX callback for preauthentication frames
 296
 297 rsn_preauth_eapol_cb()
 298 - callback function to be called when EAPOL authentication has been completed
 299   (either successfully or unsuccessfully) for RSN pre-authentication
 300
 301 rsn_preauth_init()
 302 rsn_preauth_deinit()
 303
 304 pmksa_candidate_add()
 305 - add a BSSID to PMKSA candidate list
 306
 307 rsn_preauth_scan_results()
 308 - update RSN pre-authentication candidate list based on scan results
 309
 310
 311 Driver wrapper implementation (driver.h, drivers.c)
 312 ---------------------------------------------------
 313
 314 All hardware and driver dependent functionality is implemented in as a
 315 separate C file(s) implementing defined wrapper functions. Other parts
 316 of the wpa_supplicant are designed to be hardware, driver, and operating
 317 system independent.
 318
 319 Driver wrappers need to implement whatever calls are used in the
 320 target operating system/driver for controlling wireless LAN
 321 devices. As an example, in case of Linux, these are mostly some glue
 322 code and ioctl() calls and netlink message parsing for Linux Wireless
 323 Extensions. Since all features required for WPA are not yet included
 324 in Wireless Extensions, some driver specific code is used in the
 325 example implementation for Host AP driver. These driver dependent parts
 326 are to be replaced with generic code once the needed changes are
 327 included in the Wireless Extensions. After that, all Linux drivers, at
 328 least in theory, could use the same driver wrapper code.
 329
 330 A driver wrapper needs to implement some or all of the functions
 331 defined in driver.h (see that file for detailed documentation of the
 332 functions). Hardware independent parts of wpa_supplicant will call
 333 these functions to control the driver/wlan card. In addition, support
 334 for driver events is required. The event callback function,
 335 wpa_supplicant_event(), and its parameters are documented in
 336 wpa_supplicant.h. In addition, pointer to the 'struct wpa_driver_ops'
 337 needs to be registered in drivers.c file.
 338
 339 When porting to other operating systems, driver wrapper should be
 340 modified to use the native interface of the target OS. It is possible
 341 that some extra requirements for the interface between the driver
 342 wrapper and generic wpa_supplicant code are discovered during porting
 343 to a new operating system. These will be addresses on case by case
 344 basic by modifying the interface and updating the other driver
 345 wrappers for this. The goal is to avoid changing this interface
 346 without very good reasons in order to limit the number of changes
 347 needed to other wrappers and hardware independent parts of
 348 wpa_supplicant.
 349
 350 Generic Linux Wireless Extensions functions are implemented in
 351 driver_wext.c. All Linux driver wrappers can use these when the kernel
 352 driver supports the generic ioctl()s and wireless events. Driver
 353 specific functions are implemented in separate C files, e.g.,
 354 driver_hostap.c. These files need to define struct wpa_driver_ops
 355 entry that will be used in wpa_supplicant.c when calling driver
 356 functions. These entries need to be added to the lists in
 357 wpa_supplicant_set_driver() and usage() functions in wpa_supplicant.c.
 358
 359 In general, it is likely to be useful to first take a look at couple
 360 of the driver interfaces before starting on implementing a new
 361 one. driver_hostap.c and driver_wext.c include a complete
 362 implementation for Linux drivers that use wpa_supplicant-based control
 363 of WPA IE and roaming. driver_ndis.c (with help from driver_ndis_.c)
 364 is an example of a complete interface for Windows NDIS interface for
 365 drivers that generate WPA IE themselves and decide when to roam. These
 366 example implementations include full support for all security modes.
 367
 368
 369 Driver requirements for WPA
 370 ---------------------------
 371
 372 WPA introduces new requirements for the device driver. At least some
 373 of these need to be implemented in order to provide enough support for
 374 wpa_supplicant.
 375
 376 TKIP/CCMP
 377
 378 WPA requires that the pairwise cipher suite (encryption algorithm for
 379 unicast data packets) is TKIP or CCMP. These are new encryption
 380 protocols and thus, the driver will need to be modified to support
 381 them. Depending on the used wlan hardware, some parts of these may be
 382 implemented by the hardware/firmware.
 383
 384 Specification for both TKIP and CCMP is available from IEEE (IEEE
 385 802.11i draft version 3.0). Fully functional, hardware independent
 386 implementation of both encryption protocols is also available in Host
 387 AP driver (driver/modules/hostap_{tkip,ccmp}.c).
 388
 389 The driver will also need to provide configuration mechanism to allow
 390 user space programs to configure TKIP and CCMP. Current Linux Wireless
 391 Extensions (v16) does not yet support these algorithms or
 392 individual/non-default keys. Host AP driver has an example of private
 393 ioctl()s for this. Eventually, this should be replaced with modified
 394 Linux Wireless Extensions.
 395
 396 Roaming control and scanning support
 397
 398 wpa_supplicant controls AP selections based on the information
 399 received from Beacon and/or Probe Response frames. This means that the
 400 driver should support external control for scan process. In case of
 401 Linux, use of new Wireless Extensions scan support (i.e., 'iwlist
 402 wlan0 scan') is recommended. The current driver wrapper (driver_wext.c)
 403 uses this for scan results.
 404
 405 Scan results must also include WPA information element. This is not
 406 yet defined in Linux Wireless Extensions and Host AP driver uses a
 407 custom event to provide the full WPA IE (including element id and
 408 length) as a hex string that is included in the scan results.
 409 Eventually, this should be defined as a Wireless Extensions ioctl
 410 that can be used both with scan results and with configuration of WPA IE
 411 for association request (and Beacon/Probe Response in case of an
 412 AP/IBSS).
 413
 414 wpa_supplicant needs to also be able to request the driver to
 415 associate with a specific BSS. Current Host AP driver and matching
 416 driver_hostap.c wrapper uses following sequence for this
 417 request. Similar/identical mechanism should be usable also with other
 418 drivers.
 419
 420 - set WPA IE for AssocReq with private ioctl
 421 - set SSID with SIOCSIWESSID
 422 - set channel/frequency with SIOCSIWFREQ
 423 - set BSSID with SIOCSIWAP
 424   (this last ioctl will trigger the driver to request association)
 425
 426 WPA IE generation
 427
 428 wpa_supplicant selects which cipher suites and key management suites
 429 are used. Based on this information, it generates a WPA IE. This is
 430 provided to the driver interface in the associate call. This does not
 431 match with Windows NDIS drivers which generate the WPA IE
 432 themselves.
 433
 434 wpa_supplicant allows Windows NDIS-like behavior by providing the
 435 selected cipher and key management suites in the associate call. If
 436 the driver generates its own WPA IE and that differs from the one
 437 generated by wpa_supplicant, the driver has to inform wpa_supplicant
 438 about the used WPA IE (i.e., the one it used in (Re)Associate
 439 Request). This notification is done using EVENT_ASSOCINFO event (see
 440 wpa_supplicant.h).
 441
 442 Driver events
 443
 444 wpa_supplicant needs to receive event callbacks when certain events
 445 occur (association, disassociation, Michael MIC failure, scan results
 446 available, PMKSA caching candidate). These events and the callback
 447 details are defined in wpa_supplicant.h.
 448
 449 On Linux, association and disassociation can use existing Wireless
 450 Extensions event that is reporting new AP with SIOCGIWAP
 451 event. Similarly, completion of scan can be reported with SIOCGIWSCAN
 452 event.
 453
 454 Michael MIC failure event is not yet included in Wireless Extensions,
 455 so this needs a custom event. Host AP driver uses custom event with
 456 following contents: MLME-MICHAELMICFAILURE.indication(keyid=#
 457 broadcast/unicast addr=addr2). This is the recommended format until
 458 the event is added to Linux Wireless Extensions.