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, in‐
24       cluded  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 in‐
28       herited  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 Au‐
39       thentication 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 en‐
49       abled, 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
59wpa_supplicant requests the kernel driver to scan neighboring BSSes
60
61wpa_supplicant selects a BSS based on its configuration
62
63wpa_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
74wpa_supplicant  completes WPA 4-Way Handshake and Group Key Handshake
75         with the Authenticator (AP)
76
77wpa_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 in‐
200              terface, 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  op‐
236              tion.)
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 re‐
265       ports, is to start wpa_supplicant on foreground with debugging enabled:
266
267
268              wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
269
270
271
272       If the specific driver wrapper is not known beforehand, it is  possible
273       to  specify  multiple  comma  separated  driver wrappers on the command
274       line. wpa_supplicant will use the first driver wrapper that is able  to
275       initialize the interface.
276
277
278              wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
279
280
281
282       wpa_supplicant  can control multiple interfaces (radios) either by run‐
283       ning one process for each interface separately or by running  just  one
284       process  and  list  of options at command line. Each interface is sepa‐
285       rated with -N argument. As an example, following  command  would  start
286       wpa_supplicant for two interfaces:
287
288
289              wpa_supplicant \
290                   -c wpa1.conf -i wlan0 -D nl80211 -N \
291                   -c wpa2.conf -i ath0 -D wext
292
293
294

OS REQUIREMENTS

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

SUPPORTED DRIVERS

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

ARCHITECTURE

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

QUICK START

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

INTERFACE TO PCMCIA-CS/CARDMRG

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

SEE ALSO

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