« back to all changes in this revision
Viewing changes to developer.txt
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Kyle McMartin
- Date: 2005-02-15 00:51:28 UTC
- Revision ID: james.westby@ubuntu.com-20050215005128-xr4m8owiunur2008
Tags: upstream-0.3.8
Import upstream version 0.3.8
- files added:
- doc
added
removed
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.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1