1WPA_SUPPLICANT(8)                                            WPA_SUPPLICANT(8)
2
3
4

NAME

6       wpa_supplicant  - Wi-Fi Protected Access client and IEEE 802.1X suppli‐
7       cant
8

SYNOPSIS

10       wpa_supplicant [ -BddfhKLqqsTtuvW ]  [ -iifname ]  [ -cconfig file ]  [
11       -Ddriver ]  [ -PPID_file ]  [ -foutput file ]
12

OVERVIEW

14       Wireless  networks do not require physical access to the network equip‐
15       ment in the same way as wired networks. This makes it easier for  unau‐
16       thorized users to passively monitor a network and capture all transmit‐
17       ted frames.  In addition, unauthorized use of the network is much  eas‐
18       ier. In many cases, this can happen even without user's explicit knowl‐
19       edge since the wireless LAN adapter may have been configured  to  auto‐
20       matically join any available network.
21
22       Link-layer  encryption  can  be used to provide a layer of security for
23       wireless networks. The original wireless  LAN  standard,  IEEE  802.11,
24       included a simple encryption mechanism, WEP. However, that proved to be
25       flawed in many areas and network protected with WEP cannot be  consider
26       secure.  IEEE  802.1X authentication and frequently changed dynamic WEP
27       keys can be used to improve the network security,  but  even  that  has
28       inherited  security  issues due to the use of WEP for encryption. Wi-Fi
29       Protected Access and IEEE 802.11i amendment to the wireless  LAN  stan‐
30       dard  introduce a much improvement mechanism for securing wireless net‐
31       works. IEEE 802.11i enabled networks that are  using  CCMP  (encryption
32       mechanism  based  on strong cryptographic algorithm AES) can finally be
33       called secure used for applications which require efficient  protection
34       against unauthorized access.
35
36       wpa_supplicant  is  an  implementation of the WPA Supplicant component,
37       i.e., the part that runs in the client stations. It implements WPA  key
38       negotiation  with  a  WPA  Authenticator  and  EAP  authentication with
39       Authentication Server. In addition, it controls the  roaming  and  IEEE
40       802.11 authentication/association of the wireless LAN driver.
41
42       wpa_supplicant  is  designed  to be a "daemon" program that runs in the
43       background and acts as the backend component controlling  the  wireless
44       connection.  wpa_supplicant  supports separate frontend programs and an
45       example text-based frontend, wpa_cli, is included with wpa_supplicant.
46
47       Before wpa_supplicant can do its work, the network  interface  must  be
48       available.  That  means  that  the  physical device must be present and
49       enabled, and the driver for the device must be loaded. The daemon  will
50       exit immediately if the device is not already available.
51
52       After  wpa_supplicant  has  configured the network device, higher level
53       configuration such as DHCP may proceed. There are a variety of ways  to
54       integrate  wpa_supplicant into a machine's networking scripts, a few of
55       which are described in sections below.
56
57       The following steps are used when associating with an AP using WPA:
58
59       · wpa_supplicant requests the kernel driver to scan neighboring BSSes
60
61       · wpa_supplicant selects a BSS based on its configuration
62
63       · wpa_supplicant requests the kernel driver to associate with the  cho‐
64         sen BSS
65
66       · If WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP authenti‐
67         cation with the authentication server (proxied by  the  Authenticator
68         in the AP)
69
70       · If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
71
72       · If WPA-PSK: wpa_supplicant uses PSK as the master session key
73
74       · wpa_supplicant  completes WPA 4-Way Handshake and Group Key Handshake
75         with the Authenticator (AP)
76
77       · wpa_supplicant configures encryption keys for unicast and broadcast
78
79       · normal data packets can be transmitted and received
80

SUPPORTED FEATURES

82       Supported WPA/IEEE 802.11i features:
83
84       · WPA-PSK ("WPA-Personal")
85
86       · WPA with EAP (e.g., with RADIUS authentication  server)  ("WPA-Enter‐
87         prise")  Following authentication methods are supported with an inte‐
88         grate IEEE 802.1X Supplicant:
89
90         · EAP-TLS
91
92              · EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
93
94              · EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
95
96              · EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
97
98              · EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
99
100              · EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
101
102              · EAP-TTLS/EAP-MD5-Challenge
103
104              · EAP-TTLS/EAP-GTC
105
106              · EAP-TTLS/EAP-OTP
107
108              · EAP-TTLS/EAP-MSCHAPv2
109
110              · EAP-TTLS/EAP-TLS
111
112              · EAP-TTLS/MSCHAPv2
113
114              · EAP-TTLS/MSCHAP
115
116              · EAP-TTLS/PAP
117
118              · EAP-TTLS/CHAP
119
120              · EAP-SIM
121
122              · EAP-AKA
123
124              · EAP-PSK
125
126              · EAP-PAX
127
128              · LEAP (note: requires special support from the driver for  IEEE
129                802.11 authentication)
130
131              · (following methods are supported, but since they do not gener‐
132                ate keying material, they cannot be  used  with  WPA  or  IEEE
133                802.1X WEP keying)
134
135              · EAP-MD5-Challenge
136
137              · EAP-MSCHAPv2
138
139              · EAP-GTC
140
141              · EAP-OTP
142
143       · key management for CCMP, TKIP, WEP104, WEP40
144
145       · RSN/WPA2 (IEEE 802.11i)
146
147         · pre-authentication
148
149         · PMKSA caching
150

AVAILABLE DRIVERS

152       A  summary  of  available driver backends is below. Support for each of
153       the driver backends is chosen at wpa_supplicant  compile  time.  For  a
154       list  of  supported driver backends that may be used with the -D option
155       on your system, refer to the help output of wpa_supplicant (wpa_suppli‐
156       cant -h).
157
158       wext   Linux wireless extensions (generic).
159
160       wired  wpa_supplicant wired Ethernet driver
161
162       roboswitch
163              wpa_supplicant Broadcom switch driver
164
165       bsd    BSD 802.11 support (Atheros, etc.).
166
167       ndis   Windows NDIS driver.
168

COMMAND LINE OPTIONS

170       Most  command line options have global scope. Some are given per inter‐
171       face, and are only valid if at least one -i option is specified, other‐
172       wise  they're  ignored.  Option groups for different interfaces must be
173       separated by -N option.
174
175       -b br_ifname
176              Optional bridge interface name. (Per interface)
177
178       -B     Run daemon in the background.
179
180       -c filename
181              Path to configuration file. (Per interface)
182
183       -C ctrl_interface
184              Path to ctrl_interface socket (Per interface. Only used if -c is
185              not).
186
187       -i ifname
188              Interface to listen on. Multiple instances of this option can be
189              present, one per interface, separated by -N option (see below).
190
191       -d     Increase debugging verbosity (-dd even more).
192
193       -D driver
194              Driver to use (can be  multiple  drivers:  nl80211,wext).   (Per
195              interface, see the available options below.)
196
197       -e entropy file
198              File  for wpa_supplicant to use to maintain its internal entropy
199              store in over restarts.
200
201       -f output file
202              Log output to specified file instead of stdout.  (This  is  only
203              available if wpa_supplicant was built with the CONFIG_DEBUG_FILE
204              option.)
205
206       -g global ctrl_interface
207              Path to global ctrl_interface socket.  If  specified,  interface
208              definitions may be omitted.
209
210       -K     Include keys (passwords, etc.) in debug output.
211
212       -h     Help. Show a usage message.
213
214       -L     Show license (BSD).
215
216       -o override driver
217              Override the driver parameter for new interfaces.
218
219       -O override ctrl_interface
220              Override the ctrl_interface parameter for new interfaces.
221
222       -p     Driver parameters. (Per interface)
223
224       -P PID_file
225              Path to PID file.
226
227       -q     Decrease debugging verbosity (-qq even less).
228
229       -s     Log  output to syslog instead of stdout. (This is only available
230              if  wpa_supplicant  was  built  with   the   CONFIG_DEBUG_SYSLOG
231              option.)
232
233       -T     Log  output  to  Linux tracing in addition to any other destina‐
234              tions. (This is only available if wpa_supplicant was built  with
235              the CONFIG_DEBUG_LINUX_TRACING option.)
236
237       -t     Include timestamp in debug messages.
238
239       -u     Enable DBus control interface. If enabled, interface definitions
240              may be omitted. (This is only available  if  wpa_supplicant  was
241              built with the CONFIG_DBUS option.)
242
243       -v     Show version.
244
245       -W     Wait for a control interface monitor before starting.
246
247       -N     Start describing new interface.
248

EXAMPLES

250       In most common cases, wpa_supplicant is started with:
251
252
253              wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0
254
255
256
257       This makes the process fork into background.
258
259       The  easiest  way  to  debug  problems,  and  to  get debug log for bug
260       reports, is  to  start  wpa_supplicant  on  foreground  with  debugging
261       enabled:
262
263
264              wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
265
266
267
268       If  the specific driver wrapper is not known beforehand, it is possible
269       to specify multiple comma separated  driver  wrappers  on  the  command
270       line.  wpa_supplicant will use the first driver wrapper that is able to
271       initialize the interface.
272
273
274              wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
275
276
277
278       wpa_supplicant can control multiple interfaces (radios) either by  run‐
279       ning  one  process for each interface separately or by running just one
280       process and list of options at command line. Each  interface  is  sepa‐
281       rated  with  -N  argument. As an example, following command would start
282       wpa_supplicant for two interfaces:
283
284
285              wpa_supplicant \
286                   -c wpa1.conf -i wlan0 -D nl80211 -N \
287                   -c wpa2.conf -i ath0 -D wext
288
289
290

OS REQUIREMENTS

292       Current hardware/software requirements:
293
294       · Linux kernel 2.4.x or 2.6.x with Linux  Wireless  Extensions  v15  or
295         newer
296
297       · FreeBSD 6-CURRENT
298
299       · Microsoft  Windows  with WinPcap (at least WinXP, may work with other
300         versions)
301

SUPPORTED DRIVERS

303       Linux wireless extensions
304              In theory, any driver that supports  Linux  wireless  extensions
305              can  be  used  with  IEEE  802.1X  (i.e.,  not  WPA)  when using
306              ap_scan=0 option in configuration file.
307
308       Wired Ethernet drivers
309              Use ap_scan=0.
310
311       BSD net80211 layer (e.g., Atheros driver)
312              At the moment, this is for FreeBSD 6-CURRENT branch.
313
314       Windows NDIS
315              The  current  Windows   port   requires   WinPcap   (http://win
316              pcap.polito.it/). See README-Windows.txt for more information.
317
318       wpa_supplicant  was  designed  to be portable for different drivers and
319       operating systems. Hopefully, support for more wlan cards and OSes will
320       be  added  in  the future. See developer.txt for more information about
321       the design of wpa_supplicant and porting to  other  drivers.  One  main
322       goal  is  to  add full WPA/WPA2 support to Linux wireless extensions to
323       allow new drivers to be  supported  without  having  to  implement  new
324       driver-specific interface code in wpa_supplicant.
325

ARCHITECTURE

327       The wpa_supplicant system consists of the following components:
328
329       wpa_supplicant.conf
330              the  configuration  file  describing  all networks that the user
331              wants the computer to connect to.
332
333       wpa_supplicant
334              the program that directly interacts with the network interface.
335
336       wpa_cli
337              the client program that provides a high-level interface  to  the
338              functionality of the daemon.
339
340       wpa_passphrase
341              a  utility  needed  to  construct wpa_supplicant.conf files that
342              include encrypted passwords.
343

QUICK START

345       First, make a configuration file, e.g.  /etc/wpa_supplicant.conf,  that
346       describes   the   networks  you  are  interested  in.  See  wpa_suppli‐
347       cant.conf(5) for details.
348
349       Once the configuration is ready, you can test whether the configuration
350       works  by  running wpa_supplicant with following command to start it on
351       foreground with debugging enabled:
352
353
354              wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
355
356
357
358
359       Assuming everything goes fine, you can start using following command to
360       start wpa_supplicant on background without debugging:
361
362
363              wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
364
365
366
367
368       Please  note that if you included more than one driver interface in the
369       build time configuration (.config),  you  may  need  to  specify  which
370       interface  to  use  by  including -D<driver name> option on the command
371       line.
372

INTERFACE TO PCMCIA-CS/CARDMRG

374       For example, following small changes to pcmcia-cs scripts can  be  used
375       to enable WPA support:
376
377       Add  MODE="Managed"  and  WPA="y"  to  the  network scheme in /etc/pcm‐
378       cia/wireless.opts.
379
380       Add the following block to the end of start action handler in /etc/pcm‐
381       cia/wireless:
382
383
384              if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
385                  /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf -i$DEVICE
386              fi
387
388
389
390
391       Add  the following block to the end of stop action handler (may need to
392       be separated from other actions) in /etc/pcmcia/wireless:
393
394
395              if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
396                  killall wpa_supplicant
397              fi
398
399
400
401
402       This will make cardmgr start wpa_supplicant when the  card  is  plugged
403       in.
404

SEE ALSO

406       wpa_background(8) wpa_supplicant.conf(5) wpa_cli(8) wpa_passphrase(8)
407
409       wpa_supplicant  is copyright (c) 2003-2016, Jouni Malinen <j@w1.fi> and
410       contributors.  All Rights Reserved.
411
412       This program is licensed under the BSD license (the one with advertise‐
413       ment clause removed).
414
415
416
417                                30 October 2018              WPA_SUPPLICANT(8)
Impressum