WPA Supplicant
==============

Copyright (c) 2003-2004, Jouni Malinen <jkmaline@cc.hut.fi>
All Rights Reserved.

This program is dual-licensed under both the GPL version 2 and BSD
licensed. 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 th 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")
  (this requires an external program, Xsupplicant, for EAP authentication)
- key management for CCMP, TKIP, WEP104, WEP40


Requirements
------------

Current hardware/software requirements:
- Linux kernel 2.4.x or 2.6.x
- Linux Wireless Extensions v15 or newer
- drivers:
	Host AP driver for Prism2/2.5/3 (development snapshot/v0.2.x)
	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.

wpa_supplicant was designed to be portable for different drivers and
operating systems. Hopefully, support for more wlan cards will be
added in the future. See developer.txt for more information about the
design of wpa_supplicant and porting to other drivers.

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 build. Instead, internal
Linux specific implementation is used. libpcap/libdnet are more
portable and they can be used by modifying Makefile (define
USE_DNET_PCAP and link with these libraries).


WPA
---

The original security mechanism of IEEE 802.11 standard was not
designed to be strong and has proved 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 been
working to address the flaws of the base standard and is nearing
completion in the end of 2003 or early 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 choice have proved 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 are
nearing their completion in the end of 2003 and the amendment for the
IEEE 802.11 is expected to be released during 2004. Wi-Fi Alliance is
planning on generating a new version of WPA called WPA2 based on the
final IEEE 802.11i results. This included, e.g., support for more
robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
to replace TKIP, optimizations for handoff (pre-authentication, key
caching), and IBSS security.

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.


wpa_supplicant
--------------

wpa_supplicant is an implementation of the WPA Supplicant component,
i.e., the part that runs in the client stations. It implements key
negotiation with a WPA Authenticator and it controls the roaming and
IEEE 802.11 authentication/association of the wlan driver. This
implementation does not include an internal IEEE 802.1X Supplicant for
EAP. Instead, an external program, Xsupplicant (http://www.open1x.org/)
is used for this part of the WPA authentication when WPA is used with
EAP.

wpa_supplicant is designed to be a "daemon" program that runs in the
background and acts as the backend component controlling the wireless
connection. A separate frontend program is planned, but not yet
implemented, for providing user interface for controlling the backend
and displaying status information.

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: Xsupplicant completes EAP authentication with the
  authentication server (proxied by the Authenticator in the AP)
- If WPA-EAP: Xsupplicant sends master session key to wpa_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



Command line options
--------------------

usage:
  wpa_supplicant [-BddhLqqvw] -i<ifname> -c<config file> [-D<driver>]

options:
  -B = run daemon in the background
  -d = increase debugging verbosity (-dd even more)
  -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

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

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.


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').


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.



Integration with Xsupplicant
----------------------------

wpa_supplicant has an experimental interface for integrating it with
Xsupplicant for the WPA with EAP authentication. Xsupplicant needs to
be modified to send master session key to wpa_supplicant after
successful EAP authentication. The included patch (xsupplicant.patch)
can be used with the latest CVS snapshot of the Xsupplicant.

Note: xsupplicant.patch may not be synchronized with all Xsupplicant
CVS changes, so it may have conflicts. Xsupplicant is currently being
restructured so this mode of operation will remain experimental for
the time being. Easier solution can be expected once a new, stable
release of Xsupplicant becomes available.

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; added by xsupplicant.patch) must
be used when starting xsupplicant.
