NameDateSize

..09-Feb-201823

driver.h06-Nov-20121.3 KiB

driver_wifi.c06-Nov-201211 KiB

eloop.c06-Nov-20127 KiB

eloop.h06-Nov-20121.6 KiB

l2_packet.c06-Nov-20123.8 KiB

l2_packet.h06-Nov-20121.3 KiB

Makefile14-Jan-20191.5 KiB

README06-Nov-201227.4 KiB

THIRDPARTYLICENSE06-Nov-20121.8 KiB

THIRDPARTYLICENSE.descrip06-Nov-201230

wpa.c06-Nov-201250.3 KiB

wpa.xml06-Nov-20122.5 KiB

wpa_enc.c06-Nov-20125.4 KiB

wpa_enc.h06-Nov-20121.3 KiB

wpa_impl.h06-Nov-20127.1 KiB

wpa_supplicant.c06-Nov-201223.1 KiB

README

1#pragma ident	"%Z%%M%	%I%	%E% SMI"
2
3WPA Supplicant
4==============
5
6Copyright (c) 2003-2004, Jouni Malinen <jkmaline@cc.hut.fi>
7All Rights Reserved.
8
9Sun elects to license this software under the BSD license.
10
11
12License
13-------
14
15BSD license:
16
17Redistribution and use in source and binary forms, with or without
18modification, are permitted provided that the following conditions are
19met:
20
211. Redistributions of source code must retain the above copyright
22   notice, this list of conditions and the following disclaimer.
23
242. Redistributions in binary form must reproduce the above copyright
25   notice, this list of conditions and the following disclaimer in the
26   documentation and/or other materials provided with the distribution.
27
283. Neither the name(s) of the above-listed copyright holder(s) nor the
29   names of its contributors may be used to endorse or promote products
30   derived from this software without specific prior written permission.
31
32THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
33"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
34LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
35A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
36OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
37SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
38LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
39DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
40THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
41(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
42OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
43
44
45
46Features
47--------
48
49Supported WPA/IEEE 802.11i features:
50- WPA-PSK ("WPA-Personal")
51- WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")
52  Following authentication methods are supported with an integrate IEEE 802.1X
53  Supplicant:
54  * EAP-TLS
55  * EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
56  * EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
57  * EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
58  * EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
59  * EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
60  * EAP-TTLS/EAP-MD5-Challenge
61  * EAP-TTLS/EAP-GTC
62  * EAP-TTLS/EAP-OTP
63  * EAP-TTLS/EAP-MSCHAPv2
64  * EAP-TTLS/EAP-TLS
65  * EAP-TTLS/MSCHAPv2
66  * EAP-TTLS/MSCHAP
67  * EAP-TTLS/PAP
68  * EAP-TTLS/CHAP
69  * EAP-SIM
70  * LEAP (note: only with WEP keys, i.e., not for WPA; in addition, LEAP
71	requires special support from the driver for IEEE 802.11
72	authentication)
73  (following methods are supported, but since they do not generate keying
74   material, they cannot be used with WPA or IEEE 802.1X WEP keying)
75  * EAP-MD5-Challenge 
76  * EAP-MSCHAPv2
77  * EAP-GTC
78  * EAP-OTP
79  Alternatively, an external program, e.g., Xsupplicant, can be used for EAP
80  authentication.
81- key management for CCMP, TKIP, WEP104, WEP40
82- RSN/WPA2 (IEEE 802.11i)
83  * pre-authentication
84  * PMKSA caching
85
86
87
88Requirements
89------------
90
91Current hardware/software requirements:
92- Linux kernel 2.4.x or 2.6.x
93- Linux Wireless Extensions v15 or newer
94- drivers:
95	Host AP driver for Prism2/2.5/3 (development snapshot/v0.2.x)
96	in Managed mode ('iwconfig wlan0 mode managed'). Please note that
97	station firmware version needs to be 1.7.0 or newer to work in
98	WPA mode.
99
100	Linuxant DriverLoader (http://www.linuxant.com/driverloader/)
101	with Windows NDIS driver for your wlan card supporting WPA.
102
103	Agere Systems Inc. Linux Driver
104	(http://www.agere.com/support/drivers/)
105	Please note that the driver interface file (driver_hermes.c) and
106	hardware specific include files are not included in the
107	wpa_supplicant distribution. You will need to copy these from the
108	source package of the Agere driver.
109
110	madwifi driver for cards based on Atheros chip set (ar521x)
111	(http://sourceforge.net/projects/madwifi/)
112	Please note that you will need to modify the wpa_supplicant Makefile
113	to use correct path for madwifi driver root directory
114	(CFLAGS += -I../madwifi/wpa line in Makefile).
115
116	ATMEL AT76C5XXx driver for USB and PCMCIA cards
117	(http://atmelwlandriver.sourceforge.net/).
118
119	Linux ndiswrapper (http://ndiswrapper.sourceforge.net/) with
120	Windows NDIS driver.
121
122	In theory, any driver that supports Linux wireless extensions can be
123	used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in
124	configuration file.
125
126wpa_supplicant was designed to be portable for different drivers and
127operating systems. Hopefully, support for more wlan cards will be
128added in the future. See developer.txt for more information about the
129design of wpa_supplicant and porting to other drivers. One main goal
130is to add full WPA/WPA2 support to Linux wireless extensions to allow
131new drivers to be supported without having to implement new
132driver-specific interface code in wpa_supplicant.
133
134Optional libraries for layer2 packet processing:
135- libpcap (tested with 0.7.2, most relatively recent versions assumed to work,
136	this is likely to be available with most distributions,
137	http://tcpdump.org/)
138- libdnet (tested with v1.4, most versions assumed to work,
139	http://libdnet.sourceforge.net/)
140
141These libraries are _not_ used in the default build. Instead, internal
142Linux specific implementation is used. libpcap/libdnet are more
143portable and they can be used by modifying Makefile (define
144USE_DNET_PCAP and link with these libraries).
145
146
147Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS:
148- openssl (tested with 0.9.7c and 0.9.7d, assumed to work with most
149  relatively recent versions; this is likely to be available with most
150  distributions, http://www.openssl.org/)
151
152This library is only needed when EAP-TLS, EAP-PEAP, or EAP-TTLS
153support is enabled. WPA-PSK mode does not require this or EAPOL/EAP
154implementation. A configuration file, .config, for compilation is
155needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5,
156EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so
157they should only be enabled if testing the EAPOL/EAP state
158machines. However, there can be used as inner authentication
159algorithms with EAP-PEAP and EAP-TTLS.
160
161See Building and installing section below for more detailed
162information about the wpa_supplicant build time configuration.
163
164
165
166WPA
167---
168
169The original security mechanism of IEEE 802.11 standard was not
170designed to be strong and has proved to be insufficient for most
171networks that require some kind of security. Task group I (Security)
172of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked
173to address the flaws of the base standard and has in practice
174completed its work in May 2004. The IEEE 802.11i amendment to the IEEE
175802.11 standard was approved in June 2004 and this amendment is likely
176to be published in July 2004.
177
178Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the
179IEEE 802.11i work (draft 3.0) to define a subset of the security
180enhancements that can be implemented with existing wlan hardware. This
181is called Wi-Fi Protected Access<TM> (WPA). This has now become a
182mandatory component of interoperability testing and certification done
183by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web
184site (http://www.wi-fi.org/OpenSection/protected_access.asp).
185
186IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
187for protecting wireless networks. WEP uses RC4 with 40-bit keys,
18824-bit initialization vector (IV), and CRC32 to protect against packet
189forgery. All these choice have proved to be insufficient: key space is
190too small against current attacks, RC4 key scheduling is insufficient
191(beginning of the pseudorandom stream should be skipped), IV space is
192too small and IV reuse makes attacks easier, there is no replay
193protection, and non-keyed authentication does not protect against bit
194flipping packet data.
195
196WPA is an intermediate solution for the security issues. It uses
197temporal key integrity protocol (TKIP) to replace WEP. TKIP is a
198compromise on strong security and possibility to use existing
199hardware. It still uses RC4 for the encryption like WEP, but with
200per-packet RC4 keys. In addition, it implements replay protection,
201keyed packet authentication mechanism (Michael MIC).
202
203Keys can be managed using two different mechanisms. WPA can either use
204an external authentication server (e.g., RADIUS) and EAP just like
205IEEE 802.1X is using or pre-shared keys without need for additional
206servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
207respectively. Both mechanisms will generate a master session key for
208the Authenticator (AP) and Supplicant (client station).
209
210WPA implements a new key handshake (4-Way Handshake and Group Key
211Handshake) for generating and exchanging data encryption keys between
212the Authenticator and Supplicant. This handshake is also used to
213verify that both Authenticator and Supplicant know the master session
214key. These handshakes are identical regardless of the selected key
215management mechanism (only the method for generating master session
216key changes).
217
218
219
220IEEE 802.11i / WPA2
221-------------------
222
223The design for parts of IEEE 802.11i that were not included in WPA has
224finished (May 2004) and this amendment to IEEE 802.11 was approved in
225June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
226version of WPA called WPA2. This includes, e.g., support for more
227robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
228to replace TKIP and optimizations for handoff (reduced number of
229messages in initial key handshake, pre-authentication, key caching).
230
231Some wireless LAN vendors are already providing support for CCMP in
232their WPA products. There is no "official" interoperability
233certification for CCMP and/or mixed modes using both TKIP and CCMP, so
234some interoperability issues can be expected even though many
235combinations seem to be working with equipment from different vendors.
236Certification for WPA2 is likely to start during the second half of
2372004.
238
239
240
241wpa_supplicant
242--------------
243
244wpa_supplicant is an implementation of the WPA Supplicant component,
245i.e., the part that runs in the client stations. It implements WPA key
246negotiation with a WPA Authenticator and EAP authentication with
247Authentication Server. In addition, it controls the roaming and IEEE
248802.11 authentication/association of the wlan driver.
249
250wpa_supplicant is designed to be a "daemon" program that runs in the
251background and acts as the backend component controlling the wireless
252connection. wpa_supplicant supports separate frontend programs and an
253example text-based frontend, wpa_cli, is included with wpa_supplicant.
254
255Following steps are used when associating with an AP using WPA:
256
257- wpa_supplicant requests the kernel driver to scan neighboring BSSes
258- wpa_supplicant selects a BSS based on its configuration
259- wpa_supplicant requests the kernel driver to associate with the chosen
260  BSS
261- If WPA-EAP: integrated IEEE 802.1X Supplicant or external Xsupplicant
262  completes EAP authentication with the authentication server (proxied
263  by the Authenticator in the AP)
264- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
265- If WPA-PSK: wpa_supplicant uses PSK as the master session key
266- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake
267  with the Authenticator (AP)
268- wpa_supplicant configures encryption keys for unicast and broadcast
269- normal data packets can be transmitted and received
270
271
272
273Building and installing
274-----------------------
275
276In order to be able to build wpa_supplicant, you will first need to
277select which parts of it will be included. This is done by creating a
278build time configuration file, .config, in the wpa_supplicant root
279directory. Configuration options are text lines using following
280format: CONFIG_<option>=y. Lines starting with # are considered
281comments and are ignored.
282
283The build time configuration can be used to select only the needed
284features and limit the binary size and requirements for external
285libraries. The main configuration parts are the selection of which
286driver interfaces (e.g., hostap, madwifi, ..) and which authentication
287methods (e.g., EAP-TLS, EAP-PEAP, ..) are included.
288
289Following build time configuration options are used to control IEEE
290802.1X/EAPOL and EAP state machines and all EAP methods. Including
291TLS, PEAP, or TTLS will require linking wpa_supplicant with openssl
292library for TLS implementation.
293
294CONFIG_IEEE8021X_EAPOL=y
295CONFIG_EAP_MD5=y
296CONFIG_MSCHAPV2=y
297CONFIG_EAP_TLS=y
298CONFIG_EAP_PEAP=y
299CONFIG_EAP_TTLS=y
300CONFIG_EAP_GTC=y
301CONFIG_EAP_OTP=y
302CONFIG_EAP_SIM=y
303CONFIG_EAP_LEAP=y
304
305Following option can be used to include GSM SIM/USIM interface for GSM
306authentication algorithm (for EAP-SIM). This requires pcsc-lite
307(http://www.linuxnet.com/) for smart card access.
308
309CONFIG_PCSC=y
310
311Following options can be added to .config to select which driver
312interfaces are included. Prism54.org driver is not yet complete and
313Hermes driver interface needs to be downloaded from Agere (see above).
314Most Linux driver need to include CONFIG_WIRELESS_EXTENSION.
315
316CONFIG_WIRELESS_EXTENSION=y
317CONFIG_DRIVER_HOSTAP=y
318CONFIG_DRIVER_PRISM54=y
319CONFIG_DRIVER_HERMES=y
320CONFIG_DRIVER_MADWIFI=y
321CONFIG_DRIVER_ATMEL=y
322CONFIG_DRIVER_WEXT=y
323CONFIG_DRIVER_NDISWRAPPER=y
324
325Following example includes all features and driver interfaces that are
326included in the wpa_supplicant package:
327
328CONFIG_DRIVER_HOSTAP=y
329CONFIG_DRIVER_PRISM54=y
330CONFIG_DRIVER_HERMES=y
331CONFIG_DRIVER_MADWIFI=y
332CONFIG_DRIVER_ATMEL=y
333CONFIG_DRIVER_WEXT=y
334CONFIG_DRIVER_NDISWRAPPER=y
335CONFIG_WIRELESS_EXTENSION=y
336CONFIG_IEEE8021X_EAPOL=y
337CONFIG_EAP_MD5=y
338CONFIG_MSCHAPV2=y
339CONFIG_EAP_TLS=y
340CONFIG_EAP_PEAP=y
341CONFIG_EAP_TTLS=y
342CONFIG_EAP_GTC=y
343CONFIG_EAP_OTP=y
344CONFIG_EAP_SIM=y
345CONFIG_EAP_LEAP=y
346CONFIG_PCSC=y
347
348EAP-PEAP and EAP-TTLS will automatically include configured EAP
349methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection.
350
351
352After you have created a configuration file, you can build
353wpa_supplicant and wpa_cli with 'make' command. You may then install
354the binaries to a suitable system directory, e.g., /usr/local/bin.
355
356Example commands:
357
358# build wpa_supplicant and wpa_cli
359make
360# install binaries (this may need root privileges)
361cp wpa_cli wpa_supplicant /usr/local/bin
362
363
364You will need to make a configuration file, e.g.,
365/etc/wpa_supplicant.conf, with network configuration for the networks
366you are going to use. Configuration file section below includes
367explanation fo the configuration file format and includes various
368examples. Once the configuration is ready, you can test whether the
369configuration work by first running wpa_supplicant with following
370command to start it on foreground with debugging enabled:
371
372wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
373
374Assuming everything goes fine, you can start using following command
375to start wpa_supplicant on background without debugging:
376
377wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
378
379Please note that if you included more than one driver interface in the
380build time configuration (.config), you may need to specify which
381interface to use by including -D<driver name> option on the command
382line. See following section for more details on command line options
383for wpa_supplicant.
384
385
386
387Command line options
388--------------------
389
390usage:
391  wpa_supplicant [-BddehLqqvw] -i<ifname> -c<config file> [-D<driver>]
392
393options:
394  -B = run daemon in the background
395  -d = increase debugging verbosity (-dd even more)
396  -e = use external IEEE 802.1X Supplicant (e.g., xsupplicant)
397       (this disables the internal Supplicant)
398  -h = show this help text
399  -L = show license (GPL and BSD)
400  -q = decrease debugging verbosity (-qq even less)
401  -v = show version
402  -w = wait for interface to be added, if needed
403
404drivers:
405  hostap = Host AP driver (Intersil Prism2/2.5/3) [default]
406	(this can also be used with Linuxant DriverLoader)
407  prism54 = Prism54.org driver (Intersil Prism GT/Duette/Indigo)
408	not yet fully implemented
409  hermes = Agere Systems Inc. driver (Hermes-I/Hermes-II)
410  madwifi = MADWIFI 802.11 support (Atheros, etc.)
411  atmel = ATMEL AT76C5XXx (USB, PCMCIA)
412  wext = Linux wireless extensions (generic)
413  ndiswrapper = Linux ndiswrapper
414
415In most common cases, wpa_supplicant is started with
416
417wpa_supplicant -Bw -c/etc/wpa_supplicant.conf -iwlan0
418
419This makes the process fork into background and wait for the wlan0
420interface if it is not available at startup time.
421
422
423
424Configuration file
425------------------
426
427wpa_supplicant is configured using a text file that lists all accepted
428networks and security policies, including pre-shared keys. See
429example configuration file, wpa_supplicant.conf, for detailed
430information about the configuration format and supported fields.
431
432Changes to configuration file can be reloaded be sending SIGHUP signal
433to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarily,
434reloading can be triggered with 'wpa_cli reconfigure' command.
435
436Configuration file can include one or more network blocks, e.g., one
437for each used SSID. wpa_supplicant will automatically select the best
438betwork based on the order of network blocks in the configuration
439file, network security level (WPA/WPA2 is prefered), and signal
440strength.
441
442Example configuration files for some common configurations:
443
4441) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work
445   network
446
447# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
448ctrl_interface=/var/run/wpa_supplicant
449ctrl_interface_group=wheel
450#
451# home network; allow all valid ciphers
452network={
453	ssid="home"
454	scan_ssid=1
455	key_mgmt=WPA-PSK
456	psk="very secret passphrase"
457}
458#
459# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
460network={
461	ssid="work"
462	scan_ssid=1
463	key_mgmt=WPA-EAP
464	pairwise=CCMP TKIP
465	group=CCMP TKIP
466	eap=TLS
467	identity="user@example.com"
468	ca_cert="/etc/cert/ca.pem"
469	client_cert="/etc/cert/user.pem"
470	private_key="/etc/cert/user.prv"
471	private_key_passwd="password"
472}
473
474
4752) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
476   (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series)
477
478ctrl_interface=/var/run/wpa_supplicant
479ctrl_interface_group=wheel
480network={
481	ssid="example"
482	scan_ssid=1
483	key_mgmt=WPA-EAP
484	eap=PEAP
485	identity="user@example.com"
486	password="foobar"
487	ca_cert="/etc/cert/ca.pem"
488	phase1="peaplabel=0"
489	phase2="auth=MSCHAPV2"
490}
491
492
4933) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
494   unencrypted use. Real identity is sent only within an encrypted TLS tunnel.
495
496ctrl_interface=/var/run/wpa_supplicant
497ctrl_interface_group=wheel
498network={
499	ssid="example"
500	scan_ssid=1
501	key_mgmt=WPA-EAP
502	eap=TTLS
503	identity="user@example.com"
504	anonymous_identity="anonymous@example.com"
505	password="foobar"
506	ca_cert="/etc/cert/ca.pem"
507	phase2="auth=MD5"
508}
509
510
5114) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and
512   broadcast); use EAP-TLS for authentication
513
514ctrl_interface=/var/run/wpa_supplicant
515ctrl_interface_group=wheel
516network={
517	ssid="1x-test"
518	scan_ssid=1
519	key_mgmt=IEEE8021X
520	eap=TLS
521	identity="user@example.com"
522	ca_cert="/etc/cert/ca.pem"
523	client_cert="/etc/cert/user.pem"
524	private_key="/etc/cert/user.prv"
525	private_key_passwd="password"
526	eapol_flags=3
527}
528
529
5305) Catch all example that allows more or less all configuration modes. The
531   configuration options are used based on what security policy is used in the
532   selected SSID. This is mostly for testing and is not recommended for normal
533   use.
534
535ctrl_interface=/var/run/wpa_supplicant
536ctrl_interface_group=wheel
537network={
538	ssid="example"
539	scan_ssid=1
540	key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
541	pairwise=CCMP TKIP
542	group=CCMP TKIP WEP104 WEP40
543	psk="very secret passphrase"
544	eap=TTLS PEAP TLS
545	identity="user@example.com"
546	password="foobar"
547	ca_cert="/etc/cert/ca.pem"
548	client_cert="/etc/cert/user.pem"
549	private_key="/etc/cert/user.prv"
550	private_key_passwd="password"
551	phase1="peaplabel=0"
552	ca_cert2="/etc/cert/ca2.pem"
553	client_cert2="/etc/cer/user.pem"
554	private_key2="/etc/cer/user.prv"
555	private_key2_passwd="password"
556}
557
558
559
560Certificates
561------------
562
563Some EAP authentication methods require use of certificates. EAP-TLS
564uses both server side and client certificates whereas EAP-PEAP and
565EAP-TTLS only require the server side certificate. When client
566certificate is used, a matching private key file has to also be
567included in configuration. If the private key uses a passphrase, this
568has to be configured in wpa_supplicant.conf ("private_key_passwd").
569
570wpa_supplicant supports X.509 certificates in PEM and DER
571formats. User certificate and private key can be included in the same
572file.
573
574If the user certificate and private key is received in PKCS#12/PFX
575format, they need to be converted to suitable PEM/DER format for
576wpa_supplicant. This can be done, e.g., with following commands:
577
578# convert client certificate and private key to PEM format
579openssl pkcs12 -in example.pfx -out user.pem -clcerts
580# convert CA certificate (if included in PFX file) to PEM format
581openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
582
583
584
585wpa_cli
586-------
587
588wpa_cli is a text-based frontend program for interacting with
589wpa_supplicant. It is used to query current status, change
590configuration, trigger events, and request interactive user input.
591
592wpa_cli can show the current authentication status, selected security
593mode, dot11 and dot1x MIBs, etc. In addition, it can configuring some
594variables like EAPOL state machine parameters and trigger events like
595reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user
596interface to request authentication information, like username and
597password, if these are not included in the configuration. This can be
598used to implement, e.g., one-time-passwords or generic token card
599authentication where the authentication is based on a
600challenge-response that uses an external device for generating the
601response.
602
603The control interface of wpa_supplicant can be configured to allow
604non-root user access (ctrl_interface_group in the configuration
605file). This makes it possible to run wpa_cli with a normal user
606account.
607
608wpa_cli supports two modes: interactive and command line. Both modes
609share the same command set and the main difference is in interactive
610mode providing access to unsolicited messages (event messages,
611username/password requests).
612
613Interactive mode is started when wpa_cli is executed without including
614the command as a command line parameter. Commands are then entered on
615the wpa_cli prompt. In command line mode, the same commands are
616entered as command line arguments for wpa_cli.
617
618
619Interactive authentication parameters request
620
621When wpa_supplicant need authentication parameters, like username and
622password, which are not present in the configuration file, it sends a
623request message to all attached frontend programs, e.g., wpa_cli in
624interactive mode. wpa_cli shows these requests with
625"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or
626OTP (one-time-password). <id> is a unique identifier for the current
627network. <text> is description of the request. In case of OTP request,
628it includes the challenge from the authentication server.
629
630The reply to these requests can be given with 'identity', 'password',
631and 'otp' commands. <id> needs to be copied from the the matching
632request. 'password' and 'otp' commands can be used regardless of
633whether the request was for PASSWORD or OTP. The main difference
634between these two commands is that values given with 'password' are
635remembered as long as wpa_supplicant is running whereas values given
636with 'otp' are used only once and then forgotten, i.e., wpa_supplicant
637will ask frontend for a new value for every use. This can be used to
638implement one-time-password lists and generic token card -based
639authentication.
640
641Example request for password and a matching reply:
642
643CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
644> password 1 mysecretpassword
645
646Example request for generic token card challenge-response:
647
648CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
649> otp 2 9876
650
651
652wpa_cli commands
653
654  status = get current WPA/EAPOL/EAP status
655  mib = get MIB variables (dot1x, dot11)
656  help = show this usage help
657  interface [ifname] = show interfaces/select interface
658  level <debug level> = change debug level
659  license = show full wpa_cli license
660  logoff = IEEE 802.1X EAPOL state machine logoff
661  logon = IEEE 802.1X EAPOL state machine logon
662  set = set variables (shows list of variables when run without arguments)
663  pmksa = show PMKSA cache
664  reassociate = force reassociation
665  reconfigure = force wpa_supplicant to re-read its configuration file
666  preauthenticate <BSSID> = force preauthentication
667  identity <network id> <identity> = configure identity for an SSID
668  password <network id> <password> = configure password for an SSID
669  otp <network id> <password> = configure one-time-password for an SSID
670  quit = exit wpa_cli
671
672
673
674Integrating with pcmcia-cs/cardmgr scripts
675------------------------------------------
676
677wpa_supplicant needs to be running when using a wireless network with
678WPA. It can be started either from system startup scripts or from
679pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be
680completed before data frames can be exchanged, so wpa_supplicant
681should be started before DHCP client.
682
683Command line option '-w' can be used if wpa_supplicant is started
684before the wireless LAN interface is present (e.g., before inserting
685the PC Card) or is not yet up.
686
687For example, following small changes to pcmcia-cs scripts can be used
688to enable WPA support:
689
690Add MODE="Managed" and WPA="y" to the network scheme in
691/etc/pcmcia/wireless.opts.
692
693Add the following block to the end of 'start' action handler in
694/etc/pcmcia/wireless:
695
696    if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
697	/usr/local/bin/wpa_supplicant -Bw -c/etc/wpa_supplicant.conf \
698		-i$DEVICE
699    fi
700
701Add the following block to the end of 'stop' action handler (may need
702to be separated from other actions) in /etc/pcmcia/wireless:
703
704    if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
705	killall wpa_supplicant
706    fi
707
708This will make cardmgr start wpa_supplicant when the card is plugged
709in. wpa_supplicant will wait until the interface is set up--either
710when a static IP address is configured or when DHCP client is
711started--and will then negotiate keys with the AP.
712
713
714
715Optional integration with Xsupplicant
716-------------------------------------
717
718wpa_supplicant has an integrated IEEE 802.1X Supplicant that supports
719most commonly used EAP methods. In addition, wpa_supplicant has an
720experimental interface for integrating it with Xsupplicant
721(http://www.open1x.org/) for the WPA with EAP authentication.
722
723Xsupplicant needs to be modified to send master session key to
724wpa_supplicant after successful EAP authentication. The included patch
725(xsupplicant.patch) shows the changes needed. This was merged into
726xsupplicant CVS on February 6, 2004, so any snapshot after that should
727have the needed functionality already included.
728
729When using WPA-EAP, both wpa_supplicant and Xsupplicant must be
730configured with the network security policy. See Xsupplicant documents
731for information about its configuration. Please also note, that a new
732command line option -W (enable WPA; added by xsupplicant.patch) must
733be used when starting xsupplicant.
734
735Example configuration for xsupplicant:
736
737network_list = all
738default_netname = jkm
739
740jkm
741{
742	type = wireless
743	allow_types = eap_peap
744	identity = <BEGIN_ID>jkm<END_ID>
745	eap-peap {
746		random_file = /dev/urandom
747		root_cert = /home/jkm/CA.pem
748		chunk_size = 1398
749		allow_types = eap_mschapv2
750		eap-mschapv2 {
751			username = <BEGIN_UNAME>jkm<END_UNAME>
752			password = <BEGIN_PASS>jkm<END_PASS>
753		}
754	}
755}
756
757
758Example configuration for wpa_supplicant:
759
760network={
761	ssid="jkm"
762	key_mgmt=WPA-EAP
763}
764
765
766Both wpa_supplicant and xsupplicant need to be started. Please remember
767to add '-W' option for xsupplicant in order to provide keying material
768for wpa_supplicant and '-e' option for wpa_supplicant to disable internal
769IEEE 802.1X implementation.
770
771wpa_supplicant -iwlan0 -cwpa_supplicant.conf -e
772xsupplicant -iwlan0 -cxsupplicant.conf -W
773