859 lines
30 KiB
Plaintext
859 lines
30 KiB
Plaintext
WPA Supplicant
|
|
==============
|
|
|
|
Copyright (c) 2003-2005, Jouni Malinen <jkmaline@cc.hut.fi> and
|
|
contributors
|
|
All Rights Reserved.
|
|
|
|
This program is dual-licensed under both the GPL version 2 and BSD
|
|
license. Either license may be used at your option.
|
|
|
|
|
|
|
|
License
|
|
-------
|
|
|
|
GPL v2:
|
|
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License version 2 as
|
|
published by the Free Software Foundation.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program; if not, write to the Free Software
|
|
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
|
(this copy of the license is in COPYING file)
|
|
|
|
|
|
Alternatively, this software may be distributed under the terms of BSD
|
|
license:
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are
|
|
met:
|
|
|
|
1. Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
|
|
2. Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
|
|
3. Neither the name(s) of the above-listed copyright holder(s) nor the
|
|
names of its contributors may be used to endorse or promote products
|
|
derived from this software without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
|
|
|
|
Features
|
|
--------
|
|
|
|
Supported WPA/IEEE 802.11i features:
|
|
- WPA-PSK ("WPA-Personal")
|
|
- WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")
|
|
Following authentication methods are supported with an integrate IEEE 802.1X
|
|
Supplicant:
|
|
* EAP-TLS
|
|
* EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
|
|
* EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
|
|
* EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
|
|
* EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
|
|
* EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
|
|
* EAP-TTLS/EAP-MD5-Challenge
|
|
* EAP-TTLS/EAP-GTC
|
|
* EAP-TTLS/EAP-OTP
|
|
* EAP-TTLS/EAP-MSCHAPv2
|
|
* EAP-TTLS/EAP-TLS
|
|
* EAP-TTLS/MSCHAPv2
|
|
* EAP-TTLS/MSCHAP
|
|
* EAP-TTLS/PAP
|
|
* EAP-TTLS/CHAP
|
|
* EAP-SIM
|
|
* EAP-AKA
|
|
* EAP-PSK
|
|
* LEAP (note: requires special support from the driver for IEEE 802.11
|
|
authentication)
|
|
(following methods are supported, but since they do not generate keying
|
|
material, they cannot be used with WPA or IEEE 802.1X WEP keying)
|
|
* EAP-MD5-Challenge
|
|
* EAP-MSCHAPv2
|
|
* EAP-GTC
|
|
* EAP-OTP
|
|
Alternatively, an external program, e.g., Xsupplicant, can be used for EAP
|
|
authentication.
|
|
- key management for CCMP, TKIP, WEP104, WEP40
|
|
- RSN/WPA2 (IEEE 802.11i)
|
|
* pre-authentication
|
|
* PMKSA caching
|
|
|
|
|
|
|
|
Requirements
|
|
------------
|
|
|
|
Current hardware/software requirements:
|
|
- Linux kernel 2.4.x or 2.6.x with Linux Wireless Extensions v15 or newer
|
|
- FreeBSD 6-CURRENT
|
|
- Microsoft Windows with WinPcap (at least WinXP, may work with other versions)
|
|
- drivers:
|
|
Host AP driver for Prism2/2.5/3 (development snapshot/v0.2.x)
|
|
(http://hostap.epitest.fi/)
|
|
Driver need 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.
|
|
|
|
Linuxant DriverLoader (http://www.linuxant.com/driverloader/)
|
|
with Windows NDIS driver for your wlan card supporting WPA.
|
|
|
|
Agere Systems Inc. Linux Driver
|
|
(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.
|
|
|
|
madwifi driver for cards based on Atheros chip set (ar521x)
|
|
(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).
|
|
|
|
ATMEL AT76C5XXx driver for USB and PCMCIA cards
|
|
(http://atmelwlandriver.sourceforge.net/).
|
|
|
|
Linux ndiswrapper (http://ndiswrapper.sourceforge.net/) with
|
|
Windows NDIS driver.
|
|
|
|
Broadcom wl.o driver
|
|
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).
|
|
|
|
Intel ipw2100 driver
|
|
(http://sourceforge.net/projects/ipw2100/)
|
|
|
|
Intel ipw2200 driver
|
|
(http://sourceforge.net/projects/ipw2200/)
|
|
|
|
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.
|
|
|
|
BSD net80211 layer (e.g., Atheros driver)
|
|
At the moment, this is for FreeBSD 6-CURRENT branch.
|
|
|
|
Windows NDIS
|
|
The current Windows port requires WinPcap (http://winpcap.polito.it/).
|
|
See README-Windows.txt for more information.
|
|
|
|
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.
|
|
|
|
Optional libraries for layer2 packet processing:
|
|
- libpcap (tested with 0.7.2, most relatively recent versions assumed to work,
|
|
this is likely to be available with most distributions,
|
|
http://tcpdump.org/)
|
|
- libdnet (tested with v1.4, most versions assumed to work,
|
|
http://libdnet.sourceforge.net/)
|
|
|
|
These libraries are _not_ used in the default Linux build. Instead,
|
|
internal Linux specific implementation is used. libpcap/libdnet are
|
|
more portable and they can be used by adding CONFIG_DNET_PCAP=y into
|
|
.config. They may also be selected automatically for other operating
|
|
systems.
|
|
|
|
|
|
Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS:
|
|
- openssl (tested with 0.9.7c and 0.9.7d, assumed to work with most
|
|
relatively recent versions; this is likely to be available with most
|
|
distributions, http://www.openssl.org/)
|
|
|
|
This library is only needed when EAP-TLS, EAP-PEAP, or EAP-TTLS
|
|
support is enabled. WPA-PSK mode does not require this or EAPOL/EAP
|
|
implementation. A configuration file, .config, for compilation is
|
|
needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5,
|
|
EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so
|
|
they should only be enabled if testing the EAPOL/EAP state
|
|
machines. However, there can be used as inner authentication
|
|
algorithms with EAP-PEAP and EAP-TTLS.
|
|
|
|
See Building and installing section below for more detailed
|
|
information about the wpa_supplicant build time configuration.
|
|
|
|
|
|
|
|
WPA
|
|
---
|
|
|
|
The original security mechanism of IEEE 802.11 standard was not
|
|
designed to be strong and has proven to be insufficient for most
|
|
networks that require some kind of security. Task group I (Security)
|
|
of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked
|
|
to address the flaws of the base standard and has in practice
|
|
completed its work in May 2004. The IEEE 802.11i amendment to the IEEE
|
|
802.11 standard was approved in June 2004 and this amendment is likely
|
|
to be published in July 2004.
|
|
|
|
Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the
|
|
IEEE 802.11i work (draft 3.0) to define a subset of the security
|
|
enhancements that can be implemented with existing wlan hardware. This
|
|
is called Wi-Fi Protected Access<TM> (WPA). This has now become a
|
|
mandatory component of interoperability testing and certification done
|
|
by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web
|
|
site (http://www.wi-fi.org/OpenSection/protected_access.asp).
|
|
|
|
IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
|
|
for protecting wireless networks. WEP uses RC4 with 40-bit keys,
|
|
24-bit initialization vector (IV), and CRC32 to protect against packet
|
|
forgery. All these choices have proven to be insufficient: key space is
|
|
too small against current attacks, RC4 key scheduling is insufficient
|
|
(beginning of the pseudorandom stream should be skipped), IV space is
|
|
too small and IV reuse makes attacks easier, there is no replay
|
|
protection, and non-keyed authentication does not protect against bit
|
|
flipping packet data.
|
|
|
|
WPA is an intermediate solution for the security issues. It uses
|
|
Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a
|
|
compromise on strong security and possibility to use existing
|
|
hardware. It still uses RC4 for the encryption like WEP, but with
|
|
per-packet RC4 keys. In addition, it implements replay protection,
|
|
keyed packet authentication mechanism (Michael MIC).
|
|
|
|
Keys can be managed using two different mechanisms. WPA can either use
|
|
an external authentication server (e.g., RADIUS) and EAP just like
|
|
IEEE 802.1X is using or pre-shared keys without need for additional
|
|
servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
|
|
respectively. Both mechanisms will generate a master session key for
|
|
the Authenticator (AP) and Supplicant (client station).
|
|
|
|
WPA implements a new key handshake (4-Way Handshake and Group Key
|
|
Handshake) for generating and exchanging data encryption keys between
|
|
the Authenticator and Supplicant. This handshake is also used to
|
|
verify that both Authenticator and Supplicant know the master session
|
|
key. These handshakes are identical regardless of the selected key
|
|
management mechanism (only the method for generating master session
|
|
key changes).
|
|
|
|
|
|
|
|
IEEE 802.11i / WPA2
|
|
-------------------
|
|
|
|
The design for parts of IEEE 802.11i that were not included in WPA has
|
|
finished (May 2004) and this amendment to IEEE 802.11 was approved in
|
|
June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
|
|
version of WPA called WPA2. This includes, e.g., support for more
|
|
robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
|
|
to replace TKIP and optimizations for handoff (reduced number of
|
|
messages in initial key handshake, pre-authentication, and PMKSA caching).
|
|
|
|
Some wireless LAN vendors are already providing support for CCMP in
|
|
their WPA products. There is no "official" interoperability
|
|
certification for CCMP and/or mixed modes using both TKIP and CCMP, so
|
|
some interoperability issues can be expected even though many
|
|
combinations seem to be working with equipment from different vendors.
|
|
Certification for WPA2 is likely to start during the second half of
|
|
2004.
|
|
|
|
|
|
|
|
wpa_supplicant
|
|
--------------
|
|
|
|
wpa_supplicant 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 wlan driver.
|
|
|
|
wpa_supplicant is designed to be a "daemon" program that runs in the
|
|
background and acts as the backend component controlling the wireless
|
|
connection. wpa_supplicant supports separate frontend programs and an
|
|
example text-based frontend, wpa_cli, is included with wpa_supplicant.
|
|
|
|
Following steps are used when associating with an AP using WPA:
|
|
|
|
- wpa_supplicant requests the kernel driver to scan neighboring BSSes
|
|
- wpa_supplicant selects a BSS based on its configuration
|
|
- wpa_supplicant requests the kernel driver to associate with the chosen
|
|
BSS
|
|
- 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)
|
|
- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
|
|
- If WPA-PSK: wpa_supplicant uses PSK as the master session key
|
|
- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake
|
|
with the Authenticator (AP)
|
|
- wpa_supplicant configures encryption keys for unicast and broadcast
|
|
- normal data packets can be transmitted and received
|
|
|
|
|
|
|
|
Building and installing
|
|
-----------------------
|
|
|
|
In order to be able to build wpa_supplicant, you will first need to
|
|
select which parts of it will be included. This is done by creating a
|
|
build time configuration file, .config, in the wpa_supplicant root
|
|
directory. Configuration options are text lines using following
|
|
format: CONFIG_<option>=y. Lines starting with # are considered
|
|
comments and are ignored. See defconfig file for example configuration
|
|
and list of available option.
|
|
|
|
The build time configuration can be used to select only the needed
|
|
features and limit the binary size and requirements for external
|
|
libraries. The main configuration parts are the selection of which
|
|
driver interfaces (e.g., hostap, madwifi, ..) and which authentication
|
|
methods (e.g., EAP-TLS, EAP-PEAP, ..) are included.
|
|
|
|
Following build time configuration options are used to control IEEE
|
|
802.1X/EAPOL and EAP state machines and all EAP methods. Including
|
|
TLS, PEAP, or TTLS will require linking wpa_supplicant with openssl
|
|
library for TLS implementation.
|
|
|
|
CONFIG_IEEE8021X_EAPOL=y
|
|
CONFIG_EAP_MD5=y
|
|
CONFIG_EAP_MSCHAPV2=y
|
|
CONFIG_EAP_TLS=y
|
|
CONFIG_EAP_PEAP=y
|
|
CONFIG_EAP_TTLS=y
|
|
CONFIG_EAP_GTC=y
|
|
CONFIG_EAP_OTP=y
|
|
CONFIG_EAP_SIM=y
|
|
CONFIG_EAP_AKA=y
|
|
CONFIG_EAP_PSK=y
|
|
CONFIG_EAP_LEAP=y
|
|
|
|
Following option can be used to include GSM SIM/USIM interface for GSM/UMTS
|
|
authentication algorithm (for EAP-SIM/EAP-AKA). This requires pcsc-lite
|
|
(http://www.linuxnet.com/) for smart card access.
|
|
|
|
CONFIG_PCSC=y
|
|
|
|
Following option can be used to replace the native Linux packet socket
|
|
interface with libpcap/libdnet.
|
|
|
|
CONFIG_DNET_PCAP=y
|
|
|
|
Following options can be added to .config to select which driver
|
|
interfaces are included. Prism54.org driver is not yet complete and
|
|
Hermes driver interface needs to be downloaded from Agere (see above).
|
|
Most Linux driver need to include CONFIG_WIRELESS_EXTENSION.
|
|
|
|
CONFIG_WIRELESS_EXTENSION=y
|
|
CONFIG_DRIVER_HOSTAP=y
|
|
CONFIG_DRIVER_PRISM54=y
|
|
CONFIG_DRIVER_HERMES=y
|
|
CONFIG_DRIVER_MADWIFI=y
|
|
CONFIG_DRIVER_ATMEL=y
|
|
CONFIG_DRIVER_WEXT=y
|
|
CONFIG_DRIVER_NDISWRAPPER=y
|
|
CONFIG_DRIVER_BROADCOM=y
|
|
CONFIG_DRIVER_IPW=y
|
|
CONFIG_DRIVER_BSD=y
|
|
CONFIG_DRIVER_NDIS=y
|
|
|
|
Following example includes all features and driver interfaces that are
|
|
included in the wpa_supplicant package:
|
|
|
|
CONFIG_DRIVER_HOSTAP=y
|
|
CONFIG_DRIVER_PRISM54=y
|
|
CONFIG_DRIVER_HERMES=y
|
|
CONFIG_DRIVER_MADWIFI=y
|
|
CONFIG_DRIVER_ATMEL=y
|
|
CONFIG_DRIVER_WEXT=y
|
|
CONFIG_DRIVER_NDISWRAPPER=y
|
|
CONFIG_DRIVER_BROADCOM=y
|
|
CONFIG_DRIVER_IPW=y
|
|
CONFIG_DRIVER_BSD=y
|
|
CONFIG_DRIVER_NDIS=y
|
|
CONFIG_WIRELESS_EXTENSION=y
|
|
CONFIG_IEEE8021X_EAPOL=y
|
|
CONFIG_EAP_MD5=y
|
|
CONFIG_EAP_MSCHAPV2=y
|
|
CONFIG_EAP_TLS=y
|
|
CONFIG_EAP_PEAP=y
|
|
CONFIG_EAP_TTLS=y
|
|
CONFIG_EAP_GTC=y
|
|
CONFIG_EAP_OTP=y
|
|
CONFIG_EAP_SIM=y
|
|
CONFIG_EAP_AKA=y
|
|
CONFIG_EAP_PSK=y
|
|
CONFIG_EAP_LEAP=y
|
|
CONFIG_PCSC=y
|
|
|
|
EAP-PEAP and EAP-TTLS will automatically include configured EAP
|
|
methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection.
|
|
|
|
|
|
After you have created a configuration file, you can build
|
|
wpa_supplicant and wpa_cli with 'make' command. You may then install
|
|
the binaries to a suitable system directory, e.g., /usr/local/bin.
|
|
|
|
Example commands:
|
|
|
|
# build wpa_supplicant and wpa_cli
|
|
make
|
|
# install binaries (this may need root privileges)
|
|
cp wpa_cli wpa_supplicant /usr/local/bin
|
|
|
|
|
|
You will need to make a configuration file, e.g.,
|
|
/etc/wpa_supplicant.conf, with network configuration for the networks
|
|
you are going to use. Configuration file section below includes
|
|
explanation fo the configuration file format and includes various
|
|
examples. Once the configuration is ready, you can test whether the
|
|
configuration work by first running wpa_supplicant with following
|
|
command to start it on foreground with debugging enabled:
|
|
|
|
wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
|
|
|
|
Assuming everything goes fine, you can start using following command
|
|
to start wpa_supplicant on background without debugging:
|
|
|
|
wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
|
|
|
|
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. See following section for more details on command line options
|
|
for wpa_supplicant.
|
|
|
|
|
|
|
|
Command line options
|
|
--------------------
|
|
|
|
usage:
|
|
wpa_supplicant [-BddehLqqvw] -i<ifname> -c<config file> [-D<driver>] \
|
|
[-N -i<ifname> -c<conf> [-D<driver>] ...]
|
|
|
|
options:
|
|
-B = run daemon in the background
|
|
-d = increase debugging verbosity (-dd even more)
|
|
-K = include keys (passwords, etc.) in debug output
|
|
-t = include timestamp in debug messages
|
|
-e = use external IEEE 802.1X Supplicant (e.g., xsupplicant)
|
|
(this disables the internal Supplicant)
|
|
-h = show this help text
|
|
-L = show license (GPL and BSD)
|
|
-q = decrease debugging verbosity (-qq even less)
|
|
-v = show version
|
|
-w = wait for interface to be added, if needed
|
|
-N = start describing new interface
|
|
|
|
drivers:
|
|
hostap = Host AP driver (Intersil Prism2/2.5/3) [default]
|
|
(this can also be used with Linuxant DriverLoader)
|
|
prism54 = Prism54.org driver (Intersil Prism GT/Duette/Indigo)
|
|
not yet fully implemented
|
|
hermes = Agere Systems Inc. driver (Hermes-I/Hermes-II)
|
|
madwifi = MADWIFI 802.11 support (Atheros, etc.)
|
|
atmel = ATMEL AT76C5XXx (USB, PCMCIA)
|
|
wext = Linux wireless extensions (generic)
|
|
ndiswrapper = Linux ndiswrapper
|
|
broadcom = Broadcom wl.o driver
|
|
ipw = Intel ipw2100/2200 driver
|
|
bsd = BSD 802.11 support (Atheros, etc.)
|
|
ndis = Windows NDIS driver
|
|
|
|
In most common cases, wpa_supplicant is started with
|
|
|
|
wpa_supplicant -Bw -c/etc/wpa_supplicant.conf -iwlan0
|
|
|
|
This makes the process fork into background and wait for the wlan0
|
|
interface if it is not available at startup time.
|
|
|
|
The easiest way to debug problems, and to get debug log for bug
|
|
reports, is to start wpa_supplicant on foreground with debugging
|
|
enabled:
|
|
|
|
wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
|
|
|
|
|
|
wpa_supplicant 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:
|
|
|
|
wpa_supplicant \
|
|
-c wpa1.conf -i wlan0 -D hostap -N \
|
|
-c wpa2.conf -i ath0 -D madwifi
|
|
|
|
|
|
Configuration file
|
|
------------------
|
|
|
|
wpa_supplicant is configured using a text file that lists all accepted
|
|
networks and security policies, including pre-shared keys. See
|
|
example configuration file, wpa_supplicant.conf, for detailed
|
|
information about the configuration format and supported fields.
|
|
|
|
Changes to configuration file can be reloaded be sending SIGHUP signal
|
|
to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly,
|
|
reloading can be triggered with 'wpa_cli reconfigure' command.
|
|
|
|
Configuration file can include one or more network blocks, e.g., one
|
|
for each used SSID. wpa_supplicant will automatically select the best
|
|
betwork based on the order of network blocks in the configuration
|
|
file, network security level (WPA/WPA2 is prefered), and signal
|
|
strength.
|
|
|
|
Example configuration files for some common configurations:
|
|
|
|
1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work
|
|
network
|
|
|
|
# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
|
|
ctrl_interface=/var/run/wpa_supplicant
|
|
ctrl_interface_group=wheel
|
|
#
|
|
# home network; allow all valid ciphers
|
|
network={
|
|
ssid="home"
|
|
scan_ssid=1
|
|
key_mgmt=WPA-PSK
|
|
psk="very secret passphrase"
|
|
}
|
|
#
|
|
# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
|
|
network={
|
|
ssid="work"
|
|
scan_ssid=1
|
|
key_mgmt=WPA-EAP
|
|
pairwise=CCMP TKIP
|
|
group=CCMP TKIP
|
|
eap=TLS
|
|
identity="user@example.com"
|
|
ca_cert="/etc/cert/ca.pem"
|
|
client_cert="/etc/cert/user.pem"
|
|
private_key="/etc/cert/user.prv"
|
|
private_key_passwd="password"
|
|
}
|
|
|
|
|
|
2) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
|
|
(e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series)
|
|
|
|
ctrl_interface=/var/run/wpa_supplicant
|
|
ctrl_interface_group=wheel
|
|
network={
|
|
ssid="example"
|
|
scan_ssid=1
|
|
key_mgmt=WPA-EAP
|
|
eap=PEAP
|
|
identity="user@example.com"
|
|
password="foobar"
|
|
ca_cert="/etc/cert/ca.pem"
|
|
phase1="peaplabel=0"
|
|
phase2="auth=MSCHAPV2"
|
|
}
|
|
|
|
|
|
3) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
|
|
unencrypted use. Real identity is sent only within an encrypted TLS tunnel.
|
|
|
|
ctrl_interface=/var/run/wpa_supplicant
|
|
ctrl_interface_group=wheel
|
|
network={
|
|
ssid="example"
|
|
scan_ssid=1
|
|
key_mgmt=WPA-EAP
|
|
eap=TTLS
|
|
identity="user@example.com"
|
|
anonymous_identity="anonymous@example.com"
|
|
password="foobar"
|
|
ca_cert="/etc/cert/ca.pem"
|
|
phase2="auth=MD5"
|
|
}
|
|
|
|
|
|
4) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and
|
|
broadcast); use EAP-TLS for authentication
|
|
|
|
ctrl_interface=/var/run/wpa_supplicant
|
|
ctrl_interface_group=wheel
|
|
network={
|
|
ssid="1x-test"
|
|
scan_ssid=1
|
|
key_mgmt=IEEE8021X
|
|
eap=TLS
|
|
identity="user@example.com"
|
|
ca_cert="/etc/cert/ca.pem"
|
|
client_cert="/etc/cert/user.pem"
|
|
private_key="/etc/cert/user.prv"
|
|
private_key_passwd="password"
|
|
eapol_flags=3
|
|
}
|
|
|
|
|
|
5) Catch all example that allows more or less all configuration modes. The
|
|
configuration options are used based on what security policy is used in the
|
|
selected SSID. This is mostly for testing and is not recommended for normal
|
|
use.
|
|
|
|
ctrl_interface=/var/run/wpa_supplicant
|
|
ctrl_interface_group=wheel
|
|
network={
|
|
ssid="example"
|
|
scan_ssid=1
|
|
key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
|
|
pairwise=CCMP TKIP
|
|
group=CCMP TKIP WEP104 WEP40
|
|
psk="very secret passphrase"
|
|
eap=TTLS PEAP TLS
|
|
identity="user@example.com"
|
|
password="foobar"
|
|
ca_cert="/etc/cert/ca.pem"
|
|
client_cert="/etc/cert/user.pem"
|
|
private_key="/etc/cert/user.prv"
|
|
private_key_passwd="password"
|
|
phase1="peaplabel=0"
|
|
ca_cert2="/etc/cert/ca2.pem"
|
|
client_cert2="/etc/cer/user.pem"
|
|
private_key2="/etc/cer/user.prv"
|
|
private_key2_passwd="password"
|
|
}
|
|
|
|
|
|
|
|
Certificates
|
|
------------
|
|
|
|
Some EAP authentication methods require use of certificates. EAP-TLS
|
|
uses both server side and client certificates whereas EAP-PEAP and
|
|
EAP-TTLS only require the server side certificate. When client
|
|
certificate is used, a matching private key file has to also be
|
|
included in configuration. If the private key uses a passphrase, this
|
|
has to be configured in wpa_supplicant.conf ("private_key_passwd").
|
|
|
|
wpa_supplicant supports X.509 certificates in PEM and DER
|
|
formats. User certificate and private key can be included in the same
|
|
file.
|
|
|
|
If the user certificate and private key is received in PKCS#12/PFX
|
|
format, they need to be converted to suitable PEM/DER format for
|
|
wpa_supplicant. This can be done, e.g., with following commands:
|
|
|
|
# convert client certificate and private key to PEM format
|
|
openssl pkcs12 -in example.pfx -out user.pem -clcerts
|
|
# convert CA certificate (if included in PFX file) to PEM format
|
|
openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
|
|
|
|
|
|
|
|
wpa_cli
|
|
-------
|
|
|
|
wpa_cli is a text-based frontend program for interacting with
|
|
wpa_supplicant. It is used to query current status, change
|
|
configuration, trigger events, and request interactive user input.
|
|
|
|
wpa_cli can show the current authentication status, selected security
|
|
mode, dot11 and dot1x MIBs, etc. In addition, it can configuring some
|
|
variables like EAPOL state machine parameters and trigger events like
|
|
reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user
|
|
interface to request authentication information, like username and
|
|
password, if these are not included in the configuration. This can be
|
|
used to implement, e.g., one-time-passwords or generic token card
|
|
authentication where the authentication is based on a
|
|
challenge-response that uses an external device for generating the
|
|
response.
|
|
|
|
The control interface of wpa_supplicant can be configured to allow
|
|
non-root user access (ctrl_interface_group in the configuration
|
|
file). This makes it possible to run wpa_cli with a normal user
|
|
account.
|
|
|
|
wpa_cli supports two modes: interactive and command line. Both modes
|
|
share the same command set and the main difference is in interactive
|
|
mode providing access to unsolicited messages (event messages,
|
|
username/password requests).
|
|
|
|
Interactive mode is started when wpa_cli is executed without including
|
|
the command as a command line parameter. Commands are then entered on
|
|
the wpa_cli prompt. In command line mode, the same commands are
|
|
entered as command line arguments for wpa_cli.
|
|
|
|
|
|
Interactive authentication parameters request
|
|
|
|
When wpa_supplicant need authentication parameters, like username and
|
|
password, which are not present in the configuration file, it sends a
|
|
request message to all attached frontend programs, e.g., wpa_cli in
|
|
interactive mode. wpa_cli shows these requests with
|
|
"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or
|
|
OTP (one-time-password). <id> is a unique identifier for the current
|
|
network. <text> is description of the request. In case of OTP request,
|
|
it includes the challenge from the authentication server.
|
|
|
|
The reply to these requests can be given with 'identity', 'password',
|
|
and 'otp' commands. <id> needs to be copied from the the matching
|
|
request. 'password' and 'otp' commands can be used regardless of
|
|
whether the request was for PASSWORD or OTP. The main difference
|
|
between these two commands is that values given with 'password' are
|
|
remembered as long as wpa_supplicant is running whereas values given
|
|
with 'otp' are used only once and then forgotten, i.e., wpa_supplicant
|
|
will ask frontend for a new value for every use. This can be used to
|
|
implement one-time-password lists and generic token card -based
|
|
authentication.
|
|
|
|
Example request for password and a matching reply:
|
|
|
|
CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
|
|
> password 1 mysecretpassword
|
|
|
|
Example request for generic token card challenge-response:
|
|
|
|
CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
|
|
> otp 2 9876
|
|
|
|
|
|
wpa_cli commands
|
|
|
|
status = get current WPA/EAPOL/EAP status
|
|
mib = get MIB variables (dot1x, dot11)
|
|
help = show this usage help
|
|
interface [ifname] = show interfaces/select interface
|
|
level <debug level> = change debug level
|
|
license = show full wpa_cli license
|
|
logoff = IEEE 802.1X EAPOL state machine logoff
|
|
logon = IEEE 802.1X EAPOL state machine logon
|
|
set = set variables (shows list of variables when run without arguments)
|
|
pmksa = show PMKSA cache
|
|
reassociate = force reassociation
|
|
reconfigure = force wpa_supplicant to re-read its configuration file
|
|
preauthenticate <BSSID> = force preauthentication
|
|
identity <network id> <identity> = configure identity for an SSID
|
|
password <network id> <password> = configure password for an SSID
|
|
otp <network id> <password> = configure one-time-password for an SSID
|
|
terminate = terminate wpa_supplicant
|
|
quit = exit wpa_cli
|
|
|
|
|
|
|
|
Integrating with pcmcia-cs/cardmgr scripts
|
|
------------------------------------------
|
|
|
|
wpa_supplicant needs to be running when using a wireless network with
|
|
WPA. It can be started either from system startup scripts or from
|
|
pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be
|
|
completed before data frames can be exchanged, so wpa_supplicant
|
|
should be started before DHCP client.
|
|
|
|
Command line option '-w' can be used if wpa_supplicant is started
|
|
before the wireless LAN interface is present (e.g., before inserting
|
|
the PC Card) or is not yet up.
|
|
|
|
For example, following small changes to pcmcia-cs scripts can be used
|
|
to enable WPA support:
|
|
|
|
Add MODE="Managed" and WPA="y" to the network scheme in
|
|
/etc/pcmcia/wireless.opts.
|
|
|
|
Add the following block to the end of 'start' action handler in
|
|
/etc/pcmcia/wireless:
|
|
|
|
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
|
|
|
|
Add the following block to the end of 'stop' action handler (may need
|
|
to be separated from other actions) in /etc/pcmcia/wireless:
|
|
|
|
if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
|
|
killall wpa_supplicant
|
|
fi
|
|
|
|
This will make cardmgr start wpa_supplicant when the card is plugged
|
|
in. wpa_supplicant 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.
|
|
|
|
|
|
|
|
Optional integration with Xsupplicant
|
|
-------------------------------------
|
|
|
|
wpa_supplicant has an integrated IEEE 802.1X Supplicant that supports
|
|
most commonly used EAP methods. In addition, wpa_supplicant has an
|
|
experimental interface for integrating it with Xsupplicant
|
|
(http://www.open1x.org/) for the WPA with EAP authentication.
|
|
|
|
When using WPA-EAP, both wpa_supplicant and Xsupplicant must be
|
|
configured with the network security policy. See Xsupplicant documents
|
|
for information about its configuration. Please also note, that a new
|
|
command line option -W (enable WPA) must be used when starting
|
|
xsupplicant.
|
|
|
|
Example configuration for xsupplicant:
|
|
|
|
network_list = all
|
|
default_netname = jkm
|
|
|
|
jkm
|
|
{
|
|
type = wireless
|
|
allow_types = eap_peap
|
|
identity = <BEGIN_ID>jkm<END_ID>
|
|
eap-peap {
|
|
random_file = /dev/urandom
|
|
root_cert = /home/jkm/CA.pem
|
|
chunk_size = 1398
|
|
allow_types = eap_mschapv2
|
|
eap-mschapv2 {
|
|
username = <BEGIN_UNAME>jkm<END_UNAME>
|
|
password = <BEGIN_PASS>jkm<END_PASS>
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
Example configuration for wpa_supplicant:
|
|
|
|
network={
|
|
ssid="jkm"
|
|
key_mgmt=WPA-EAP
|
|
}
|
|
|
|
|
|
Both wpa_supplicant and xsupplicant need to be started. Please remember
|
|
to add '-W' option for xsupplicant in order to provide keying material
|
|
for wpa_supplicant and '-e' option for wpa_supplicant to disable internal
|
|
IEEE 802.1X implementation.
|
|
|
|
wpa_supplicant -iwlan0 -cwpa_supplicant.conf -e
|
|
xsupplicant -iwlan0 -cxsupplicant.conf -W
|