http://hostap.epitest.fi/wpa_supplicant/

Linux WPA/WPA2/IEEE 802.1X Supplicant

wpa_supplicant is a WPA Supplicant for Linux, BSD, Mac OS X, andWindows withsupport for WPA and WPA2 (IEEE 802.11i / RSN). It is suitable for bothdesktop/laptop computers and embedded systems. Supplicant is the IEEE802.1X/WPA component that is used in the client stations. Itimplements key negotiation with a WPA Authenticator and it controlsthe roaming and IEEE 802.11 authentication/association of the wlandriver.

wpa_supplicant is designed to be a "daemon" program that runs in thebackground and acts as the backend component controlling the wirelessconnection. wpa_supplicant supports separate frontend programs and atext-based frontend (wpa_cli) and a GUI (wpa_gui) are included withwpa_supplicant.

wpa_supplicant uses a flexible build configuration that can be usedto select which features are included. This allows minimal code size(from ca. 50 kB binary for WPA/WPA2-Personal and 130 kB binary forWPA/WPA2-Enterprise without debugging code to 450 kB with mostfeatures and full debugging support; these example sizes are from abuild for x86 target).

Supported WPA/IEEE 802.11i features

• WPA-PSK ("WPA-Personal")
• WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")
• key management for CCMP, TKIP, WEP104, WEP40
• WPA and full IEEE 802.11i/RSN/WPA2
• RSN: PMKSA caching, pre-authentication
• IEEE 802.11r
• IEEE 802.11w
• Wi-Fi Protected Setup (WPS)

Supported EAP methods (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-AKA'
• EAP-PSK
• EAP-FAST
• EAP-PAX
• EAP-SAKE
• EAP-IKEv2
• EAP-GPSK
• LEAP (note: requires special support from the driver)

Following methods are also supported, but since they do not generate keyingmaterial, they cannot be used with WPA or IEEE 802.1X WEP keying.

• EAP-MD5-Challenge
• EAP-MSCHAPv2
• EAP-GTC
• EAP-OTP
• EAP-TNC (Trusted Network Connect; TNCC, IF-IMC, IF-T, IF-TNCCS)

More information about EAP methods and interoperability testing isavailable in eap_testing.txt.

Supported TLS/crypto libraries

• OpenSSL (default)
• GnuTLS

Internal TLS/crypto implementation (optional)

• can be used in place of an external TLS/crypto library
• TLSv1
• X.509 certificate processing
• PKCS #1
• ASN.1
• RSA
• bignum
• minimal size (ca. 50 kB binary, parts of which are already needed for WPA; TLSv1/X.509/ASN.1/RSA/bignum parts are about 25 kB on x86)

Supported wireless cards/drivers

• Linux drivers that support nl80211/cfg80211 (most new drivers)
• Linux drivers that support Linux Wireless Extensions v19 or newer withWPA/WPA2 extensions
• Host AP driver for Prism2/2.5/3 (WPA and WPA2)
• Linuxant DriverLoader with Windows NDIS driver supporting WPA/WPA2
• Agere Systems Inc. Linux Driver (Hermes-I/Hermes-II chipset) (WPA, but not WPA2)
• madwifi (Atheros ar521x)
• ATMEL AT76C5XXx
• Linux ndiswrapper
• Broadcom wl.o driver
• Intel ipw2100
• Intel ipw2200
• Wired Ethernet drivers
• BSD net80211 layer (e.g., Atheros driver) (FreeBSD 6-CURRENT and NetBSD current)
• Windows NDIS drivers (Windows; at least XP and 2000, others not tested)

wpa_supplicant was designed to be portable for different drivers andoperating systems. Hopefully, support for more wlan cards and OSes will beadded in the future. See developers' documentationfor more information about the design of wpa_supplicant and porting toother drivers.

Download

wpa_supplicant
Copyright (c) 2003-2010, Jouni Malinen <j@w1.fi>and contributors.

This program is free software; you can redistribute it and/or modifyit under the terms of the GNU General Public License version 2 aspublished by the Free Software Foundation. SeeCOPYINGfor more details.

Alternatively, this software may be distributed, used, and modifiedunder the terms of BSD license. See READMEfor more details.

Please seeREADMEfor the current documentation.
README-Windows.txthas some more information about the Windows port of wpa_supplicant.

• Release graph
• Latest stable release:
  • wpa_supplicant-0.7.3.tar.gz (source code for all versions)
  • wpa_supplicant-0.7.3.exe (binary installer for Windows)
  • wpa_supplicant-windows-bin-0.7.3.zip (binaries for Windows)
• Previous stable release:
  • wpa_supplicant-0.6.10.tar.gz (source code for all versions)
  • wpa_supplicant-0.6.10.exe (binary installer for Windows)
  • wpa_supplicant-windows-bin-0.6.10.zip (binaries for Windows)
  • wpa_gui-qt433-windows-dll.zip (Qt4 libraries from wpa_gui/Windows)
• ChangeLog:
  • development branch
  • stable branch
  • previous stable branch
• Old releases
• Mailing list
• New mailing list archives
• Web interface to GIT repository (0.6.x and newer)
• Web interface to CVS repository (0.5.x and older)
• Snapshot releases from all active branches
• GIT and read-only anonymous CVS access (pserver)
• Bug and feature request tracking
• Developers' documentation for wpa_supplicant 0.6.x
• wpa_gui screenshots

WPA

The original security mechanism of IEEE 802.11 standard was notdesigned to be strong and has proven to be insufficient for mostnetworks that require some kind of security. Task group I (Security)of IEEE 802.11 working grouphas worked to address the flaws of the base standard and inpractice completed its work in May 2004. The IEEE 802.11i amendment tothe IEEE 802.11 standard was approved in June 2004 and published inJuly 2004.

Wi-Fi Alliance used a draftversion of the IEEE 802.11i work (draft 3.0) to define a subset of thesecurity enhancements that can be implemented with existing wlanhardware. This is called Wi-Fi Protected Access (WPA). This hasnow become a mandatory component of interoperability testing andcertification done by Wi-Fi Alliance. Wi-Fi hasinformationabout WPA at its web site.

IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithmfor protecting wireless networks. WEP uses RC4 with 40-bit keys,24-bit initialization vector (IV), and CRC32 to protect against packetforgery. All these choices have proven to be insufficient: key space istoo small against current attacks, RC4 key scheduling is insufficient(beginning of the pseudorandom stream should be skipped), IV space istoo small and IV reuse makes attacks easier, there is no replayprotection, and non-keyed authentication does not protect against bitflipping packet data.

WPA is an intermediate solution for the security issues. It usesTemporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is acompromise on strong security and possibility to use existinghardware. It still uses RC4 for the encryption like WEP, but withper-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 usean external authentication server (e.g., RADIUS) and EAP just likeIEEE 802.1X is using or pre-shared keys without need for additionalservers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",respectively. Both mechanisms will generate a master session key forthe Authenticator (AP) and Supplicant (client station).

WPA implements a new key handshake (4-Way Handshake and Group KeyHandshake) for generating and exchanging data encryption keys betweenthe Authenticator and Supplicant. This handshake is also used toverify that both Authenticator and Supplicant know the master sessionkey. These handshakes are identical regardless of the selected keymanagement mechanism (only the method for generating master sessionkey changes).

IEEE 802.11i / RSN / WPA2

The design for parts of IEEE 802.11i that were not included in WPAhas finished (May 2004) and this amendment to IEEE 802.11 was approvedin June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a newversion of WPA called WPA2. This included, e.g., support for morerobust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)to replace TKIP, optimizations for handoff (reduced number of messagesin initial key handshake, pre-authentication, and PMKSA caching).

Using 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 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). WPA2 has integrated the initial Group Key Handshake into the 4-Way Handshake.
• wpa_supplicant configures encryption keys for unicast and broadcast
• normal data packets can be transmitted and received

Configuration file

wpa_supplicant is configured using a text file that lists all acceptednetworks and security policies, including pre-shared keys. Seeexample configuration file,wpa_supplicant.conf,for detailed information about the configuration format and supportedfields. In addition, simpler example configurations are available forplaintext,static WEP,IEEE 802.1X with dynamic WEP (EAP-PEAP/MSCHAPv2),WPA-PSK/TKIP, andWPA2-EAP/CCMP (EAP-TLS).In addition, wpa_supplicant can use OpenSSL engine to avoid need forexposing private keys in the file system. This can be used for EAP-TLSauthentication with smartcards and TPM tokens.Example configuration for using openCryptokishows an example network block and related parameters for EAP-TLSauthentication using PKCS#11 TPM token.

Feedback, comments, mailing list

Any comments, reports on success/failure, ideas for furtherimprovement, feature requests, etc. are welcome at j@w1.fi.Please note, that I often receive more email than I have time to answer.Unfortunately, some messages may not get a reply, but I'll try to gothrough my mail whenever time permits.

Host AP mailing list can also be used for topics related towpa_supplicant. Since this list has a broader audience, your likelyhoodof getting responses is higher. This list is recommended for generalquestions about wpa_supplicant and its development. In addition, Iwill send release notes to it whenever a new version is available.

The mailing list information and web archive is at http://lists.shmoo.com/mailman/listinfo/hostap.Messages to hostap@shmoo.com will be delivered to thesubscribers. Please note, that due to large number of spam and virusmessages sent to the list address, the list is configured to acceptmessages only from subscribed addresses. Messages from unsubscribed addressesmay be accepted manually, but their delivery will be delayed.

If you want to make sure your bug report of feature request does notget lost, please report it through the bug tracking system asa newbug/feature request.

---

Jouni Malinen

Last modified: Tue Sep 7 19:42:20 EEST 2010