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       nl80211
159              Uses  the  modern Linux nl80211/cfg80211 netlink-based interface
160              (most new drivers).
161
162       wext   Uses the legacy Linux wireless extensions ioctl-based  interface
163              (older hardware/drivers).
164
165       wired  wpa_supplicant wired Ethernet driver
166
167       roboswitch
168              wpa_supplicant Broadcom switch driver
169
170       bsd    BSD 802.11 support (Atheros, etc.).
171
172       ndis   Windows NDIS driver.
173

COMMAND LINE OPTIONS

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

EXAMPLES

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

OS REQUIREMENTS

297       Current hardware/software requirements:
298
299       · Linux kernel 2.6.30 or higher with nl80211/cfg80211 support
300
301       · Linux kernel 2.4.x or higher with Linux Wireless  Extensions  v15  or
302         newer
303
304       · FreeBSD 6-CURRENT
305
306       · Microsoft  Windows  with WinPcap (at least WinXP, may work with other
307         versions)
308

SUPPORTED DRIVERS

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

ARCHITECTURE

337       The wpa_supplicant system consists of the following components:
338
339       wpa_supplicant.conf
340              the  configuration  file  describing  all networks that the user
341              wants the computer to connect to.
342
343       wpa_supplicant
344              the program that directly interacts with the network interface.
345
346       wpa_cli
347              the client program that provides a high-level interface  to  the
348              functionality of the daemon.
349
350       wpa_passphrase
351              a  utility  needed  to  construct wpa_supplicant.conf files that
352              include encrypted passwords.
353

QUICK START

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

INTERFACE TO PCMCIA-CS/CARDMRG

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

SEE ALSO

416       wpa_background(8) wpa_supplicant.conf(5) wpa_cli(8) wpa_passphrase(8)
417
419       wpa_supplicant  is copyright (c) 2003-2019, Jouni Malinen <j@w1.fi> and
420       contributors.  All Rights Reserved.
421
422       This program is licensed under the BSD license (the one with advertise‐
423       ment clause removed).
424
425
426
427                                30 October 2019              WPA_SUPPLICANT(8)
Impressum