.\" This manpage has been automatically generated by docbook2man .\" from a DocBook document.  This tool can be found at:.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> .\" Please send any bug reports, improvements, comments, patches, .\" etc. to Steve Cheng <steve@ggi-project.org>..TH "WPA_SUPPLICANT" "8" "06 May 2006" "" "".SH NAMEwpa_supplicant \- Wi-Fi Protected Access client and IEEE 802.1X supplicant.SH SYNOPSIS\fBwpa_supplicant\fR [ \fB-BddehLqqvw\fR ] [ \fB-i\fIifname\fB\fR ] [ \fB-c\fIconfig file\fB\fR ] [ \fB-D\fIdriver\fB\fR ].SH "OVERVIEW".PPWireless networks do not require physical access to the network equipmentin the same way as wired networks. This makes it easier for unauthorizedusers to passively monitor a network and capture all transmitted frames.In addition, unauthorized use of the network is much easier. In many cases,this can happen even without user's explicit knowledge since the wirelessLAN adapter may have been configured to automatically join any availablenetwork..PPLink-layer encryption can be used to provide a layer of security forwireless networks. The original wireless LAN standard, IEEE 802.11,included a simple encryption mechanism, WEP. However, that proved tobe flawed in many areas and network protected with WEP cannot be considersecure. IEEE 802.1X authentication and frequently changed dynamic WEP keyscan be used to improve the network security, but even that has inheritedsecurity issues due to the use of WEP for encryption. Wi-Fi ProtectedAccess and IEEE 802.11i amendment to the wireless LAN standard introducea much improvement mechanism for securing wireless networks. IEEE 802.11ienabled networks that are using CCMP (encryption mechanism based on strongcryptographic algorithm AES) can finally be called secure used forapplications which require efficient protection against unauthorizedaccess..PP\fBwpa_supplicant\fR is an implementation ofthe WPA Supplicant component, i.e., the part that runs in theclient stations. It implements WPA key negotiation with a WPAAuthenticator and EAP authentication with AuthenticationServer. In addition, it controls the roaming and IEEE 802.11authentication/association of the wireless LAN driver..PP\fBwpa_supplicant\fR is designed to be a"daemon" program that runs in the background and acts as thebackend component controlling the wirelessconnection. \fBwpa_supplicant\fR supports separatefrontend programs and an example text-based frontend,\fBwpa_cli\fR, is included withwpa_supplicant..PPBefore wpa_supplicant can do its work, the network interfacemust be available.  That means that the physical device must bepresent and enabled, and the driver for the device must have beloaded.  Note, however, that the '-w' option of the wpa_supplicantdaemon instructs the daemon to continue running and to wait forthe interface to become available.  Without the '-w' option, thedaemon will exit immediately if the device is not alreadyavailable..PPAfter \fBwpa_supplicant\fR has configured thenetwork device, higher level configuration such as DHCP mayproceed.  There are a variety of ways to integrate wpa_supplicantinto a machine's networking scripts, a few of which are describedin sections below..PPThe following steps are used when associating with an APusing WPA:.TP 0.2i\(bu\fBwpa_supplicant\fR requests the kerneldriver to scan neighboring BSSes.TP 0.2i\(bu\fBwpa_supplicant\fR selects a BSS based onits configuration.TP 0.2i\(bu\fBwpa_supplicant\fR requests the kerneldriver to associate with the chosen BSS.TP 0.2i\(buIf WPA-EAP: integrated IEEE 802.1X Supplicant orexternal Xsupplicant completes EAP authentication with theauthentication server (proxied by the Authenticator in theAP).TP 0.2i\(buIf WPA-EAP: master key is received from the IEEE 802.1XSupplicant.TP 0.2i\(buIf WPA-PSK: \fBwpa_supplicant\fR uses PSKas the master session key.TP 0.2i\(bu\fBwpa_supplicant\fR completes WPA 4-WayHandshake and Group Key Handshake with the Authenticator(AP).TP 0.2i\(bu\fBwpa_supplicant\fR configures encryptionkeys for unicast and broadcast.TP 0.2i\(bunormal data packets can be transmitted and received.SH "SUPPORTED FEATURES".PPSupported WPA/IEEE 802.11i features:.TP 0.2i\(buWPA-PSK ("WPA-Personal").TP 0.2i\(buWPA with EAP (e.g., with RADIUS authentication server)("WPA-Enterprise") Following authentication methods aresupported with an integrate IEEE 802.1X Supplicant:.RS.TP 0.2i\(buEAP-TLS.RE.RS.TP 0.2i\(buEAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1).TP 0.2i\(buEAP-PEAP/TLS (both PEAPv0 and PEAPv1).TP 0.2i\(buEAP-PEAP/GTC (both PEAPv0 and PEAPv1).TP 0.2i\(buEAP-PEAP/OTP (both PEAPv0 and PEAPv1).TP 0.2i\(buEAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1).TP 0.2i\(buEAP-TTLS/EAP-MD5-Challenge.TP 0.2i\(buEAP-TTLS/EAP-GTC.TP 0.2i\(buEAP-TTLS/EAP-OTP.TP 0.2i\(buEAP-TTLS/EAP-MSCHAPv2.TP 0.2i\(buEAP-TTLS/EAP-TLS.TP 0.2i\(buEAP-TTLS/MSCHAPv2.TP 0.2i\(buEAP-TTLS/MSCHAP.TP 0.2i\(buEAP-TTLS/PAP.TP 0.2i\(buEAP-TTLS/CHAP.TP 0.2i\(buEAP-SIM.TP 0.2i\(buEAP-AKA.TP 0.2i\(buEAP-PSK.TP 0.2i\(buEAP-PAX.TP 0.2i\(buLEAP (note: requires special support fromthe driver for IEEE 802.11 authentication).TP 0.2i\(bu(following methods are supported, but sincethey do not generate keying material, they cannot be usedwith WPA or IEEE 802.1X WEP keying).TP 0.2i\(buEAP-MD5-Challenge .TP 0.2i\(buEAP-MSCHAPv2.TP 0.2i\(buEAP-GTC.TP 0.2i\(buEAP-OTP.RE.TP 0.2i\(bukey management for CCMP, TKIP, WEP104, WEP40.TP 0.2i\(buRSN/WPA2 (IEEE 802.11i).RS.TP 0.2i\(bupre-authentication.TP 0.2i\(buPMKSA caching.RE.SH "AVAILABLE DRIVERS".PPThe available drivers to specify with the -D option are:.TP\fBhostap\fR(default) Host AP driver (Intersil Prism2/2.5/3).(this can also be used with Linuxant DriverLoader)..TP\fBhermes\fRAgere Systems Inc. driver (Hermes-I/Hermes-II)..TP\fBmadwifi\fRMADWIFI 802.11 support (Atheros, etc.)..TP\fBatmel\fRATMEL AT76C5XXx (USB, PCMCIA)..TP\fBwext\fRLinux wireless extensions (generic)..TP\fBndiswrapper\fRLinux ndiswrapper..TP\fBbroadcom\fRBroadcom wl.o driver..TP\fBipw\fRIntel ipw2100/2200 driver..TP\fBwired\fRwpa_supplicant wired Ethernet driver.TP\fBbsd\fRBSD 802.11 support (Atheros, etc.)..TP\fBndis\fRWindows NDIS driver..SH "COMMAND LINE OPTIONS".TP\fB-B\fRRun daemon in the background..TP\fB-i ifname\fRInterface to listen on..TP\fB-c filename\fRPath to configuration file..TP\fB-D driver\fRDriver to use.  See the available options below..TP\fB-d\fRIncrease debugging verbosity (-dd even more)..TP\fB-K\fRInclude keys (passwords, etc.) in debug output..TP\fB-t\fRInclude timestamp in debug messages..TP\fB-e\fRUse external IEEE 802.1X Supplicant (e.g.,\fBxsupplicant\fR) (this disables the internalSupplicant)..TP\fB-h\fRHelp.  Show a usage message..TP\fB-L\fRShow license (GPL and BSD)..TP\fB-q\fRDecrease debugging verbosity (-qq even less)..TP\fB-v\fRShow version..TP\fB-w\fRwait for interface to be added, if needed.  normally,\fBwpa_supplicant\fR will exit if the interfaceis not there yet..TP\fB-N\fRStart describing new interface..SH "EXAMPLES".PPIn most common cases, \fBwpa_supplicant\fR isstarted with:.sp.RS.nfwpa_supplicant -Bw -c/etc/wpa_supplicant.conf -iwlan0.fi.RE.PPThis makes the process fork into background and wait for the wlan0interface if it is not available at startup time..PPThe easiest way to debug problems, and to get debug log forbug reports, is to start \fBwpa_supplicant\fR onforeground with debugging enabled:.sp.RS.nfwpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d.fi.RE.PP\fBwpa_supplicant\fR can control multipleinterfaces (radios) either by running one process for eachinterface separately or by running just one process and list ofoptions at command line. Each interface is separated with -Nargument. As an example, following command would startwpa_supplicant for two interfaces:.sp.RS.nfwpa_supplicant \\	-c wpa1.conf -i wlan0 -D hostap -N \\	-c wpa2.conf -i ath0 -D madwifi.fi.RE.SH "OS REQUIREMENTS".PPCurrent hardware/software requirements:.TP 0.2i\(buLinux kernel 2.4.x or 2.6.x with Linux WirelessExtensions v15 or newer.TP 0.2i\(buFreeBSD 6-CURRENT.TP 0.2i\(buMicrosoft Windows with WinPcap (at least WinXP, may workwith other versions).SH "SUPPORTED DRIVERS".TP\fBHost AP driver for Prism2/2.5/3 (development snapshot/v0.2.x)\fR(http://hostap.epitest.fi/) Driver needs to be set inManaged mode ('iwconfig wlan0 mode managed').  Please notethat station firmware version needs to be 1.7.0 or newer towork in WPA mode..TP\fBLinuxant DriverLoader\fR(http://www.linuxant.com/driverloader/)with Windows NDIS driver for your wlan card supporting WPA..TP\fBAgere Systems Inc. Linux Driver\fR(http://www.agere.com/support/drivers/) Please notethat the driver interface file (driver_hermes.c) and hardwarespecific include files are not included in the wpa_supplicantdistribution. You will need to copy these from the sourcepackage of the Agere driver..TP\fBmadwifi driver for cards based on Atheros chip set (ar521x)\fR(http://sourceforge.net/projects/madwifi/) Pleasenote that you will need to modify the wpa_supplicant .configfile to use the correct path for the madwifi driver rootdirectory (CFLAGS += -I../madwifi/wpa line in exampledefconfig)..TP\fBATMEL AT76C5XXx driver for USB and PCMCIA cards\fR(http://atmelwlandriver.sourceforge.net/)..TP\fBLinux ndiswrapper\fR(http://ndiswrapper.sourceforge.net/) with WindowsNDIS driver..TP\fBBroadcom wl.o driver\fRThis is a generic Linux driver for Broadcom IEEE802.11a/g cards.  However, it is proprietary driver that isnot publicly available except for couple of exceptions, mainlyBroadcom-based APs/wireless routers that use Linux. The driverbinary can be downloaded, e.g., from Linksys support site(http://www.linksys.com/support/gpl.asp) for LinksysWRT54G. The GPL tarball includes cross-compiler and the neededheader file, wlioctl.h, for compiling wpa_supplicant.  Thisdriver support in wpa_supplicant is expected to work also withother devices based on Broadcom driver (assuming the driverincludes client mode support)..TP\fB Intel ipw2100 driver\fR(http://sourceforge.net/projects/ipw2100/).TP\fBIntel ipw2200 driver\fR(http://sourceforge.net/projects/ipw2200/).TP\fBLinux wireless extensions\fRIn theory, any driver that supports Linux wirelessextensions can be used with IEEE 802.1X (i.e., not WPA) whenusing ap_scan=0 option in configuration file..TP\fBWired Ethernet drivers\fRUse ap_scan=0..TP\fBBSD net80211 layer (e.g., Atheros driver)\fRAt the moment, this is for FreeBSD 6-CURRENT branch..TP\fBWindows NDIS\fRThe current Windows port requires WinPcap(http://winpcap.polito.it/).  See README-Windows.txt for moreinformation..PPwpa_supplicant was designed to be portable for differentdrivers and operating systems. Hopefully, support for more wlancards and OSes will be added in the future. See developer.txt formore information about the design of wpa_supplicant and porting toother drivers. One main goal is to add full WPA/WPA2 support toLinux wireless extensions to allow new drivers to be supportedwithout having to implement new driver-specific interface code inwpa_supplicant..SH "ARCHITECTURE".PPThe\fBwpa_supplicant\fR system consists of the followingcomponents:.TP\fB\fIwpa_supplicant.conf\fB \fRthe configuration file describing all networks that theuser wants the computer to connect to.  .TP\fBwpa_supplicant\fRthe program that directly interacts with thenetwork interface.  .TP\fBwpa_cli\fRtheclient program that provides a high-level interface to thefunctionality of the daemon.  .TP\fBwpa_passphrase\fRa utility needed to construct\fIwpa_supplicant.conf\fR files that includeencrypted passwords..SH "QUICK START".PPFirst, make a configuration file, e.g.\fI/etc/wpa_supplicant.conf\fR, that describes the networksyou are interested in.  See \fBwpa_supplicant\fR(5)for details..PPOnce the configuration is ready, you can test whether theconfiguration works by running \fBwpa_supplicant\fRwith following command to start it on foreground with debuggingenabled:.sp.RS.nfwpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d    .fi.RE.PPAssuming everything goes fine, you can start using followingcommand to start \fBwpa_supplicant\fR on backgroundwithout debugging:.sp.RS.nfwpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B    .fi.RE.PPPlease note that if you included more than one driverinterface in the build time configuration (.config), you may needto specify which interface to use by including -D<drivername> option on the command line..SH "INTERFACE TO PCMCIA-CS/CARDMRG".PPFor example, following small changes to pcmcia-cs scriptscan be used to enable WPA support:.PPAdd MODE="Managed" and WPA="y" to the network scheme in\fI/etc/pcmcia/wireless.opts\fR\&..PPAdd the following block to the end of 'start' action handlerin \fI/etc/pcmcia/wireless\fR:.sp.RS.nfif [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then    /usr/local/bin/wpa_supplicant -Bw -c/etc/wpa_supplicant.conf -i$DEVICEfi    .fi.RE.PPAdd the following block to the end of 'stop' action handler(may need to be separated from other actions) in\fI/etc/pcmcia/wireless\fR:.sp.RS.nfif [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then    killall wpa_supplicantfi    .fi.RE.PPThis will make \fBcardmgr\fR start\fBwpa_supplicant\fR when the card is pluggedin. \fBwpa_supplicant\fR will wait until theinterface is set up--either when a static IP address is configuredor when DHCP client is started--and will then negotiate keys withthe AP..SH "SEE ALSO".PP\fBwpa_background\fR(8)\fBwpa_supplicant.conf\fR(5)\fBwpa_cli\fR(8)\fBwpa_passphrase\fR(8).SH "LEGAL".PPwpa_supplicant is copyright (c) 2003-2005,Jouni Malinen <jkmaline@cc.hut.fi> andcontributors.All Rights Reserved..PPThis program is dual-licensed under both the GPL version 2and BSD license. Either license may be used at your option.