diff options
Diffstat (limited to 'contrib/wpa_supplicant/doc/docbook/wpa_supplicant.8')
| -rw-r--r-- | contrib/wpa_supplicant/doc/docbook/wpa_supplicant.8 | 544 |
1 files changed, 544 insertions, 0 deletions
diff --git a/contrib/wpa_supplicant/doc/docbook/wpa_supplicant.8 b/contrib/wpa_supplicant/doc/docbook/wpa_supplicant.8 new file mode 100644 index 0000000..fcd738b --- /dev/null +++ b/contrib/wpa_supplicant/doc/docbook/wpa_supplicant.8 @@ -0,0 +1,544 @@ +.\" 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" "08 February 2006" "" "" + +.SH NAME +wpa_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" +.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 have be +loaded. Note, however, that the '-w' option of the wpa_supplicant +daemon instructs the daemon to continue running and to wait for +the interface to become available. Without the '-w' option, 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 or +external Xsupplicant 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 +The 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\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 +\fBbsd\fR +BSD 802.11 support (Atheros, etc.). +.TP +\fBndis\fR +Windows NDIS driver. +.SH "COMMAND LINE OPTIONS" +.TP +\fB-B\fR +Run daemon in the background. +.TP +\fB-i ifname\fR +Interface to listen on. +.TP +\fB-c filename\fR +Path to configuration file. +.TP +\fB-D driver\fR +Driver to use. See the available options below. +.TP +\fB-d\fR +Increase debugging verbosity (-dd even more). +.TP +\fB-K\fR +Include keys (passwords, etc.) in debug output. +.TP +\fB-t\fR +Include timestamp in debug messages. +.TP +\fB-e\fR +Use external IEEE 802.1X Supplicant (e.g., +\fBxsupplicant\fR) (this disables the internal +Supplicant). +.TP +\fB-h\fR +Help. Show a usage message. +.TP +\fB-L\fR +Show license (GPL and BSD). +.TP +\fB-q\fR +Decrease debugging verbosity (-qq even less). +.TP +\fB-v\fR +Show version. +.TP +\fB-w\fR +wait for interface to be added, if needed. normally, +\fBwpa_supplicant\fR will exit if the interface +is not there yet. +.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 -Bw -c/etc/wpa_supplicant.conf -iwlan0 +.fi +.RE +.PP +This makes the process fork into background and wait for the wlan0 +interface if it is not available at startup time. +.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 +\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 ('iwconfig wlan0 mode managed'). 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\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 'start' 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 -Bw -c/etc/wpa_supplicant.conf -i$DEVICE +fi + +.fi +.RE +.PP +Add 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 + +.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. \fBwpa_supplicant\fR will wait until the +interface is set up--either when a static IP address is configured +or when DHCP client is started--and will then negotiate keys with +the AP. +.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-2005, +Jouni Malinen <jkmaline@cc.hut.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. |
