4
Copyright (c) 2003-2012, Jouni Malinen <j@w1.fi> and contributors
4
Copyright (c) 2003-2014, Jouni Malinen <j@w1.fi> and contributors
7
This program is dual-licensed under both the GPL version 2 and BSD
8
license. Either license may be used at your option.
7
This program is licensed under the BSD license (the one with
8
advertisement clause removed).
10
If you are submitting changes to the project, please see CONTRIBUTIONS
11
file for more instructions.
17
This program is free software; you can redistribute it and/or modify
18
it under the terms of the GNU General Public License version 2 as
19
published by the Free Software Foundation.
21
This program is distributed in the hope that it will be useful,
22
but WITHOUT ANY WARRANTY; without even the implied warranty of
23
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24
GNU General Public License for more details.
26
You should have received a copy of the GNU General Public License
27
along with this program; if not, write to the Free Software
28
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
30
(this copy of the license is in COPYING file)
33
Alternatively, this software may be distributed, used, and modified
34
under the terms of BSD license:
18
This software may be distributed, used, and modified under the terms of
36
21
Redistribution and use in source and binary forms, with or without
37
22
modification, are permitted provided that the following conditions are
131
116
- Microsoft Windows with WinPcap (at least WinXP, may work with other versions)
118
Linux drivers that support cfg80211/nl80211. Even though there are
119
number of driver specific interface included in wpa_supplicant, please
120
note that Linux drivers are moving to use generic wireless configuration
121
interface driver_nl80211 (-Dnl80211 on wpa_supplicant command line)
122
should be the default option to start with before falling back to driver
133
125
Linux drivers that support WPA/WPA2 configuration with the generic
134
Linux wireless extensions (WE-18 or newer). Even though there are
135
number of driver specific interface included in wpa_supplicant, please
136
note that Linux drivers are moving to use generic wireless extensions
137
and driver_wext (-Dwext on wpa_supplicant command line) should be the
138
default option to start with before falling back to driver specific
141
Host AP driver for Prism2/2.5/3 (development snapshot/v0.2.x)
142
(http://hostap.epitest.fi/)
143
Driver need to be set in Managed mode ('iwconfig wlan0 mode managed').
144
Please note that station firmware version needs to be 1.7.0 or newer
147
Linuxant DriverLoader (http://www.linuxant.com/driverloader/)
148
with Windows NDIS driver for your wlan card supporting WPA.
150
madwifi driver for cards based on Atheros chip set (ar521x)
151
(http://sourceforge.net/projects/madwifi/)
152
Please note that you will need to modify the wpa_supplicant .config
153
file to use the correct path for the madwifi driver root directory
154
(CFLAGS += -I../madwifi/wpa line in example defconfig).
156
Linux ndiswrapper (http://ndiswrapper.sourceforge.net/) with
159
Broadcom wl.o driver (old version only)
160
This is a generic Linux driver for Broadcom IEEE 802.11a/g cards.
161
However, it is proprietary driver that is not publicly available
162
except for couple of exceptions, mainly Broadcom-based APs/wireless
163
routers that use Linux. The driver binary can be downloaded, e.g.,
164
from Linksys support site (http://www.linksys.com/support/gpl.asp)
165
for Linksys WRT54G. The GPL tarball includes cross-compiler and
166
the needed header file, wlioctl.h, for compiling wpa_supplicant.
167
This driver support in wpa_supplicant is expected to work also with
168
other devices based on Broadcom driver (assuming the driver includes
169
client mode support). Please note that the newer Broadcom driver
170
("hybrid Linux driver") supports Linux wireless extensions and does
171
not need (or even work) with the specific driver wrapper. Use -Dwext
126
Linux wireless extensions (WE-18 or newer). Obsoleted by nl80211.
174
128
In theory, any driver that supports Linux wireless extensions can be
175
129
used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in
347
301
The build time configuration can be used to select only the needed
348
302
features and limit the binary size and requirements for external
349
303
libraries. The main configuration parts are the selection of which
350
driver interfaces (e.g., hostap, madwifi, ..) and which authentication
304
driver interfaces (e.g., nl80211, wext, ..) and which authentication
351
305
methods (e.g., EAP-TLS, EAP-PEAP, ..) are included.
353
307
Following build time configuration options are used to control IEEE
489
440
-N = start describing new interface
492
hostap = Host AP driver (Intersil Prism2/2.5/3) [default]
493
(this can also be used with Linuxant DriverLoader)
494
madwifi = MADWIFI 802.11 support (Atheros, etc.) (deprecated; use wext)
443
nl80211 = Linux nl80211/cfg80211
495
444
wext = Linux wireless extensions (generic)
496
ralink = Ralink Client driver
497
broadcom = Broadcom wl.o driver
498
445
wired = wpa_supplicant wired Ethernet driver
499
446
roboswitch = wpa_supplicant Broadcom switch driver
500
447
bsd = BSD 802.11 support (Atheros, etc.)
927
874
# Start wpa_supplicant in the background
928
875
wpa_supplicant -g/var/run/wpa_supplicant-global -B
930
# Add a new interface (wlan0, no configuration file, driver=wext, and
877
# Add a new interface (wlan0, no configuration file, driver=nl80211, and
931
878
# enable control interface)
932
879
wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \
933
"" wext /var/run/wpa_supplicant
880
"" nl80211 /var/run/wpa_supplicant
935
882
# Configure a network using the newly added network interface:
936
883
wpa_cli -iwlan0 add_network
1002
949
wpa_priv can control multiple interface with one process, but it is
1003
950
also possible to run multiple wpa_priv processes at the same time, if
954
Linux capabilities instead of privileged process
955
------------------------------------------------
957
wpa_supplicant performs operations that need special permissions, e.g.,
958
to control the network connection. Traditionally this has been achieved
959
by running wpa_supplicant as a privileged process with effective user id
960
0 (root). Linux capabilities can be used to provide restricted set of
961
capabilities to match the functions needed by wpa_supplicant. The
962
minimum set of capabilities needed for the operations is CAP_NET_ADMIN
965
setcap(8) can be used to set file capabilities. For example:
967
sudo setcap cap_net_raw,cap_net_admin+ep wpa_supplicant
969
Please note that this would give anyone being able to run that
970
wpa_supplicant binary access to the additional capabilities. This can
971
further be limited by file owner/group and mode bits. For example:
973
sudo chown wpas wpa_supplicant
974
sudo chmod 0100 wpa_supplicant
976
This combination of setcap, chown, and chmod commands would allow wpas
977
user to execute wpa_supplicant with additional network admin/raw
980
Common way style of creating a control interface socket in
981
/var/run/wpa_supplicant could not be done by this user, but this
982
directory could be created before starting the wpa_supplicant and set to
983
suitable mode to allow wpa_supplicant to create sockets
984
there. Alternatively, other directory or abstract socket namespace could
985
be used for the control interface.
988
External requests for radio control
989
-----------------------------------
991
External programs can request wpa_supplicant to not start offchannel
992
operations during other tasks that may need exclusive control of the
993
radio. The RADIO_WORK control interface command can be used for this.
995
"RADIO_WORK add <name> [freq=<MHz>] [timeout=<seconds>]" command can be
996
used to reserve a slot for radio access. If freq is specified, other
997
radio work items on the same channel may be completed in
998
parallel. Otherwise, all other radio work items are blocked during
999
execution. Timeout is set to 10 seconds by default to avoid blocking
1000
wpa_supplicant operations for excessive time. If a longer (or shorter)
1001
safety timeout is needed, that can be specified with the optional
1002
timeout parameter. This command returns an identifier for the radio work
1005
Once the radio work item has been started, "EXT-RADIO-WORK-START <id>"
1006
event message is indicated that the external processing can start. Once
1007
the operation has been completed, "RADIO_WORK done <id>" is used to
1008
indicate that to wpa_supplicant. This allows other radio works to be
1009
performed. If this command is forgotten (e.g., due to the external
1010
program terminating), wpa_supplicant will time out the radio owrk item
1011
and send "EXT-RADIO-WORK-TIMEOUT <id>" event ot indicate that this has
1012
happened. "RADIO_WORK done <id>" can also be used to cancel items that
1013
have not yet been started.
1015
For example, in wpa_cli interactive mode:
1017
> radio_work add test
1019
<3>EXT-RADIO-WORK-START 1
1021
ext:test@wlan0:0:1:2.487797
1030
ext:test freq=2412 timeout=30@wlan0:2412:1:28.583483
1031
<3>EXT-RADIO-WORK-TIMEOUT 2
1034
> radio_work add test2 freq=2412 timeout=60
1036
<3>EXT-RADIO-WORK-START 5
1037
> radio_work add test3
1039
> radio_work add test4
1042
ext:test2 freq=2412 timeout=60@wlan0:2412:1:9.751844
1043
ext:test3@wlan0:0:0:5.071812
1044
ext:test4@wlan0:0:0:3.143870
1048
ext:test2 freq=2412 timeout=60@wlan0:2412:1:16.287869
1049
ext:test4@wlan0:0:0:9.679895
1052
<3>EXT-RADIO-WORK-START 7
1053
<3>EXT-RADIO-WORK-TIMEOUT 7