584 lines
15 KiB
Groff
584 lines
15 KiB
Groff
.\" 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" "07 September 2010" "" ""
|
|
|
|
.SH NAME
|
|
wpa_supplicant \- Wi-Fi Protected Access client and IEEE 802.1X supplicant
|
|
.SH SYNOPSIS
|
|
|
|
\fBwpa_supplicant\fR [ \fB-BddfhKLqqtuvW\fR ] [ \fB-i\fIifname\fB\fR ] [ \fB-c\fIconfig file\fB\fR ] [ \fB-D\fIdriver\fB\fR ] [ \fB-P\fIPID_file\fB\fR ] [ \fB-f\fIoutput file\fB\fR ]
|
|
|
|
.SH "OVERVIEW"
|
|
.PP
|
|
Wireless networks do not require physical access to the network equipment
|
|
in the same way as wired networks. This makes it easier for unauthorized
|
|
users 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 wireless
|
|
LAN adapter may have been configured to automatically join any available
|
|
network.
|
|
.PP
|
|
Link-layer encryption can be used to provide a layer of security for
|
|
wireless networks. The original wireless LAN standard, IEEE 802.11,
|
|
included a simple encryption mechanism, WEP. However, that proved to
|
|
be flawed in many areas and network protected with WEP cannot be consider
|
|
secure. IEEE 802.1X authentication and frequently changed dynamic WEP keys
|
|
can be used to improve the network security, but even that has inherited
|
|
security issues due to the use of WEP for encryption. Wi-Fi Protected
|
|
Access and IEEE 802.11i amendment to the wireless LAN standard introduce
|
|
a much improvement mechanism for securing wireless networks. IEEE 802.11i
|
|
enabled networks that are using CCMP (encryption mechanism based on strong
|
|
cryptographic algorithm AES) can finally be called secure used for
|
|
applications which require efficient protection against unauthorized
|
|
access.
|
|
.PP
|
|
\fBwpa_supplicant\fR is an implementation of
|
|
the WPA Supplicant component, i.e., the part that runs in the
|
|
client stations. It implements WPA key negotiation with a WPA
|
|
Authenticator and EAP authentication with Authentication
|
|
Server. In addition, it controls the roaming and IEEE 802.11
|
|
authentication/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 the
|
|
backend component controlling the wireless
|
|
connection. \fBwpa_supplicant\fR supports separate
|
|
frontend programs and an example text-based frontend,
|
|
\fBwpa_cli\fR, is included with
|
|
wpa_supplicant.
|
|
.PP
|
|
Before wpa_supplicant can do its work, the network interface
|
|
must be available. That means that the physical device must be
|
|
present and enabled, and the driver for the device must be
|
|
loaded. The daemon will exit immediately if the device is not already
|
|
available.
|
|
.PP
|
|
After \fBwpa_supplicant\fR has configured the
|
|
network device, higher level configuration such as DHCP may
|
|
proceed. There are a variety of ways to integrate wpa_supplicant
|
|
into a machine's networking scripts, a few of which are described
|
|
in sections below.
|
|
.PP
|
|
The following steps are used when associating with an AP
|
|
using WPA:
|
|
.TP 0.2i
|
|
\(bu
|
|
\fBwpa_supplicant\fR requests the kernel
|
|
driver to scan neighboring BSSes
|
|
.TP 0.2i
|
|
\(bu
|
|
\fBwpa_supplicant\fR selects a BSS based on
|
|
its configuration
|
|
.TP 0.2i
|
|
\(bu
|
|
\fBwpa_supplicant\fR requests the kernel
|
|
driver to associate with the chosen BSS
|
|
.TP 0.2i
|
|
\(bu
|
|
If WPA-EAP: integrated IEEE 802.1X Supplicant
|
|
completes EAP authentication with the
|
|
authentication server (proxied by the Authenticator in the
|
|
AP)
|
|
.TP 0.2i
|
|
\(bu
|
|
If WPA-EAP: master key is received from the IEEE 802.1X
|
|
Supplicant
|
|
.TP 0.2i
|
|
\(bu
|
|
If WPA-PSK: \fBwpa_supplicant\fR uses PSK
|
|
as the master session key
|
|
.TP 0.2i
|
|
\(bu
|
|
\fBwpa_supplicant\fR completes WPA 4-Way
|
|
Handshake and Group Key Handshake with the Authenticator
|
|
(AP)
|
|
.TP 0.2i
|
|
\(bu
|
|
\fBwpa_supplicant\fR configures encryption
|
|
keys for unicast and broadcast
|
|
.TP 0.2i
|
|
\(bu
|
|
normal data packets can be transmitted and received
|
|
.SH "SUPPORTED FEATURES"
|
|
.PP
|
|
Supported WPA/IEEE 802.11i features:
|
|
.TP 0.2i
|
|
\(bu
|
|
WPA-PSK ("WPA-Personal")
|
|
.TP 0.2i
|
|
\(bu
|
|
WPA with EAP (e.g., with RADIUS authentication server)
|
|
("WPA-Enterprise") Following authentication methods are
|
|
supported with an integrate IEEE 802.1X Supplicant:
|
|
.RS
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TLS
|
|
.RE
|
|
.RS
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/EAP-MD5-Challenge
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/EAP-GTC
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/EAP-OTP
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/EAP-MSCHAPv2
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/EAP-TLS
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/MSCHAPv2
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/MSCHAP
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/PAP
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-TTLS/CHAP
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-SIM
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-AKA
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-PSK
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-PAX
|
|
.TP 0.2i
|
|
\(bu
|
|
LEAP (note: requires special support from
|
|
the driver for IEEE 802.11 authentication)
|
|
.TP 0.2i
|
|
\(bu
|
|
(following methods are supported, but since
|
|
they do not generate keying material, they cannot be used
|
|
with WPA or IEEE 802.1X WEP keying)
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-MD5-Challenge
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-MSCHAPv2
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-GTC
|
|
.TP 0.2i
|
|
\(bu
|
|
EAP-OTP
|
|
.RE
|
|
.TP 0.2i
|
|
\(bu
|
|
key management for CCMP, TKIP, WEP104, WEP40
|
|
.TP 0.2i
|
|
\(bu
|
|
RSN/WPA2 (IEEE 802.11i)
|
|
.RS
|
|
.TP 0.2i
|
|
\(bu
|
|
pre-authentication
|
|
.TP 0.2i
|
|
\(bu
|
|
PMKSA caching
|
|
.RE
|
|
.SH "AVAILABLE DRIVERS"
|
|
.PP
|
|
A summary of available driver backends is below. Support for each
|
|
of the driver backends is chosen at wpa_supplicant compile time. For a
|
|
list of supported driver backends that may be used with the -D option on
|
|
your system, refer to the help output of wpa_supplicant
|
|
(\fBwpa_supplicant -h\fR).
|
|
.TP
|
|
\fBhostap\fR
|
|
(default) Host AP driver (Intersil Prism2/2.5/3).
|
|
(this can also be used with Linuxant DriverLoader).
|
|
.TP
|
|
\fBhermes\fR
|
|
Agere Systems Inc. driver (Hermes-I/Hermes-II).
|
|
.TP
|
|
\fBmadwifi\fR
|
|
MADWIFI 802.11 support (Atheros, etc.).
|
|
.TP
|
|
\fBatmel\fR
|
|
ATMEL AT76C5XXx (USB, PCMCIA).
|
|
.TP
|
|
\fBwext\fR
|
|
Linux wireless extensions (generic).
|
|
.TP
|
|
\fBndiswrapper\fR
|
|
Linux ndiswrapper.
|
|
.TP
|
|
\fBbroadcom\fR
|
|
Broadcom wl.o driver.
|
|
.TP
|
|
\fBipw\fR
|
|
Intel ipw2100/2200 driver.
|
|
.TP
|
|
\fBwired\fR
|
|
wpa_supplicant wired Ethernet driver
|
|
.TP
|
|
\fBroboswitch\fR
|
|
wpa_supplicant Broadcom switch driver
|
|
.TP
|
|
\fBbsd\fR
|
|
BSD 802.11 support (Atheros, etc.).
|
|
.TP
|
|
\fBndis\fR
|
|
Windows NDIS driver.
|
|
.SH "COMMAND LINE OPTIONS"
|
|
.PP
|
|
Most command line options have global scope. Some are given per
|
|
interface, and are only valid if at least one \fB-i\fR option
|
|
is specified, otherwise they're ignored. Option groups for different
|
|
interfaces must be separated by \fB-N\fR option.
|
|
.TP
|
|
\fB-b br_ifname\fR
|
|
Optional bridge interface name. (Per interface)
|
|
.TP
|
|
\fB-B\fR
|
|
Run daemon in the background.
|
|
.TP
|
|
\fB-c filename\fR
|
|
Path to configuration file. (Per interface)
|
|
.TP
|
|
\fB-C ctrl_interface\fR
|
|
Path to ctrl_interface socket (Per interface. Only used if
|
|
\fB-c\fR is not).
|
|
.TP
|
|
\fB-i ifname\fR
|
|
Interface to listen on. Multiple instances of this option can
|
|
be present, one per interface, separated by \fB-N\fR
|
|
option (see below).
|
|
.TP
|
|
\fB-d\fR
|
|
Increase debugging verbosity (\fB-dd\fR even
|
|
more).
|
|
.TP
|
|
\fB-D driver\fR
|
|
Driver to use (can be multiple drivers: nl80211,wext).
|
|
(Per interface, see the available options below.)
|
|
.TP
|
|
\fB-f output file\fR
|
|
Log output to specified file instead of stdout.
|
|
.TP
|
|
\fB-g global ctrl_interface\fR
|
|
Path to global ctrl_interface socket. If specified, interface
|
|
definitions may be omitted.
|
|
.TP
|
|
\fB-K\fR
|
|
Include keys (passwords, etc.) in debug output.
|
|
.TP
|
|
\fB-t\fR
|
|
Include timestamp in debug messages.
|
|
.TP
|
|
\fB-h\fR
|
|
Help. Show a usage message.
|
|
.TP
|
|
\fB-L\fR
|
|
Show license (GPL and BSD).
|
|
.TP
|
|
\fB-p\fR
|
|
Driver parameters. (Per interface)
|
|
.TP
|
|
\fB-P PID_file\fR
|
|
Path to PID file.
|
|
.TP
|
|
\fB-q\fR
|
|
Decrease debugging verbosity (\fB-qq\fR even
|
|
less).
|
|
.TP
|
|
\fB-u\fR
|
|
Enabled DBus control interface. If enabled, interface
|
|
definitions may be omitted.
|
|
.TP
|
|
\fB-v\fR
|
|
Show version.
|
|
.TP
|
|
\fB-W\fR
|
|
Wait for a control interface monitor before starting.
|
|
.TP
|
|
\fB-N\fR
|
|
Start describing new interface.
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
In most common cases, \fBwpa_supplicant\fR is
|
|
started with:
|
|
.sp
|
|
.RS
|
|
|
|
.nf
|
|
wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0
|
|
.fi
|
|
.RE
|
|
.PP
|
|
This makes the process fork into background.
|
|
.PP
|
|
The easiest way to debug problems, and to get debug log for
|
|
bug reports, is to start \fBwpa_supplicant\fR on
|
|
foreground with debugging enabled:
|
|
.sp
|
|
.RS
|
|
|
|
.nf
|
|
wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
|
|
.fi
|
|
.RE
|
|
.PP
|
|
If the specific driver wrapper is not known beforehand, it is
|
|
possible to specify multiple comma separated driver wrappers on the command
|
|
line. \fBwpa_supplicant\fR will use the first driver
|
|
wrapper that is able to initialize the interface.
|
|
.sp
|
|
.RS
|
|
|
|
.nf
|
|
wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
|
|
.fi
|
|
.RE
|
|
.PP
|
|
\fBwpa_supplicant\fR can control multiple
|
|
interfaces (radios) either by running one process for each
|
|
interface separately or by running just one process and list of
|
|
options at command line. Each interface is separated with -N
|
|
argument. As an example, following command would start
|
|
wpa_supplicant for two interfaces:
|
|
.sp
|
|
.RS
|
|
|
|
.nf
|
|
wpa_supplicant \\
|
|
-c wpa1.conf -i wlan0 -D hostap -N \\
|
|
-c wpa2.conf -i ath0 -D madwifi
|
|
.fi
|
|
.RE
|
|
.SH "OS REQUIREMENTS"
|
|
.PP
|
|
Current hardware/software requirements:
|
|
.TP 0.2i
|
|
\(bu
|
|
Linux kernel 2.4.x or 2.6.x with Linux Wireless
|
|
Extensions v15 or newer
|
|
.TP 0.2i
|
|
\(bu
|
|
FreeBSD 6-CURRENT
|
|
.TP 0.2i
|
|
\(bu
|
|
Microsoft Windows with WinPcap (at least WinXP, may work
|
|
with 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 in
|
|
Managed mode (\fBiwconfig wlan0 mode managed\fR).
|
|
Please note that station firmware version needs to be 1.7.0 or
|
|
newer to work 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 note
|
|
that the driver interface file (driver_hermes.c) and hardware
|
|
specific include files are not included in the wpa_supplicant
|
|
distribution. You will need to copy these from the source
|
|
package of the Agere driver.
|
|
.TP
|
|
\fBmadwifi driver for cards based on Atheros chip set (ar521x)\fR
|
|
(http://sourceforge.net/projects/madwifi/) Please
|
|
note that you will need to modify the wpa_supplicant .config
|
|
file to use the correct path for the madwifi driver root
|
|
directory (CFLAGS += -I../madwifi/wpa line in example
|
|
defconfig).
|
|
.TP
|
|
\fBATMEL AT76C5XXx driver for USB and PCMCIA cards\fR
|
|
(http://atmelwlandriver.sourceforge.net/).
|
|
.TP
|
|
\fBLinux ndiswrapper\fR
|
|
(http://ndiswrapper.sourceforge.net/) with Windows
|
|
NDIS driver.
|
|
.TP
|
|
\fBBroadcom wl.o driver\fR
|
|
This is a generic Linux driver for Broadcom IEEE
|
|
802.11a/g cards. However, it is proprietary driver that is
|
|
not publicly available except for couple of exceptions, mainly
|
|
Broadcom-based APs/wireless routers that use Linux. The driver
|
|
binary can be downloaded, e.g., from Linksys support site
|
|
(http://www.linksys.com/support/gpl.asp) for Linksys
|
|
WRT54G. The GPL tarball includes cross-compiler and the needed
|
|
header file, wlioctl.h, for compiling wpa_supplicant. This
|
|
driver support in wpa_supplicant is expected to work also with
|
|
other devices based on Broadcom driver (assuming the driver
|
|
includes 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\fR
|
|
In theory, any driver that supports Linux wireless
|
|
extensions can be used with IEEE 802.1X (i.e., not WPA) when
|
|
using ap_scan=0 option in configuration file.
|
|
.TP
|
|
\fBWired Ethernet drivers\fR
|
|
Use ap_scan=0.
|
|
.TP
|
|
\fBBSD net80211 layer (e.g., Atheros driver)\fR
|
|
At the moment, this is for FreeBSD 6-CURRENT branch.
|
|
.TP
|
|
\fBWindows NDIS\fR
|
|
The current Windows port requires WinPcap
|
|
(http://winpcap.polito.it/). See README-Windows.txt for more
|
|
information.
|
|
.PP
|
|
wpa_supplicant was designed to be portable for different
|
|
drivers and operating systems. Hopefully, support for more wlan
|
|
cards and OSes will be added in the future. See developer.txt for
|
|
more information about the design of wpa_supplicant and porting to
|
|
other drivers. One main goal is to add full WPA/WPA2 support to
|
|
Linux wireless extensions to allow new drivers to be supported
|
|
without having to implement new driver-specific interface code in
|
|
wpa_supplicant.
|
|
.SH "ARCHITECTURE"
|
|
.PP
|
|
The
|
|
\fBwpa_supplicant\fR system consists of the following
|
|
components:
|
|
.TP
|
|
\fB\fIwpa_supplicant.conf\fB \fR
|
|
the configuration file describing all networks that the
|
|
user wants the computer to connect to.
|
|
.TP
|
|
\fBwpa_supplicant\fR
|
|
the program that directly interacts with the
|
|
network interface.
|
|
.TP
|
|
\fBwpa_cli\fR
|
|
the
|
|
client program that provides a high-level interface to the
|
|
functionality of the daemon.
|
|
.TP
|
|
\fBwpa_passphrase\fR
|
|
a utility needed to construct
|
|
\fIwpa_supplicant.conf\fR files that include
|
|
encrypted passwords.
|
|
.SH "QUICK START"
|
|
.PP
|
|
First, make a configuration file, e.g.
|
|
\fI/etc/wpa_supplicant.conf\fR, that describes the networks
|
|
you are interested in. See \fBwpa_supplicant.conf\fR(5)
|
|
for details.
|
|
.PP
|
|
Once the configuration is ready, you can test whether the
|
|
configuration works by running \fBwpa_supplicant\fR
|
|
with following command to start it on foreground with debugging
|
|
enabled:
|
|
.sp
|
|
.RS
|
|
|
|
.nf
|
|
wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
|
|
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Assuming everything goes fine, you can start using following
|
|
command to start \fBwpa_supplicant\fR on background
|
|
without debugging:
|
|
.sp
|
|
.RS
|
|
|
|
.nf
|
|
wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
|
|
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Please note that if you included more than one driver
|
|
interface in the build time configuration (.config), you may need
|
|
to specify which interface to use by including -D<driver
|
|
name> option on the command line.
|
|
.SH "INTERFACE TO PCMCIA-CS/CARDMRG"
|
|
.PP
|
|
For example, following small changes to pcmcia-cs scripts
|
|
can be used to enable WPA support:
|
|
.PP
|
|
Add MODE="Managed" and WPA="y" to the network scheme in
|
|
\fI/etc/pcmcia/wireless.opts\fR\&.
|
|
.PP
|
|
Add the following block to the end of \fBstart\fR
|
|
action handler in \fI/etc/pcmcia/wireless\fR:
|
|
.sp
|
|
.RS
|
|
|
|
.nf
|
|
if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
|
|
/usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf -i$DEVICE
|
|
fi
|
|
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Add the following block to the end of \fBstop\fR
|
|
action handler (may need to be separated from other actions) in
|
|
\fI/etc/pcmcia/wireless\fR:
|
|
.sp
|
|
.RS
|
|
|
|
.nf
|
|
if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
|
|
killall wpa_supplicant
|
|
fi
|
|
|
|
.fi
|
|
.RE
|
|
.PP
|
|
This will make \fBcardmgr\fR start
|
|
\fBwpa_supplicant\fR when the card is plugged
|
|
in.
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
\fBwpa_background\fR(8)
|
|
\fBwpa_supplicant.conf\fR(5)
|
|
\fBwpa_cli\fR(8)
|
|
\fBwpa_passphrase\fR(8)
|
|
.SH "LEGAL"
|
|
.PP
|
|
wpa_supplicant is copyright (c) 2003-2007,
|
|
Jouni Malinen <j@w1.fi> and
|
|
contributors.
|
|
All Rights Reserved.
|
|
.PP
|
|
This program is dual-licensed under both the GPL version 2
|
|
and BSD license. Either license may be used at your option.
|