Linux WPA/WPA2/IEEE 802.1X Supplicant

wpa_supplicant is a WPA Supplicant for Linux, BSD, Mac OS X, and Windows with support for WPA and WPA2 (IEEE 802.11i / RSN). It is suitable for both desktop/laptop computers and embedded systems. Supplicant is the IEEE 802.1X/WPA component that is used 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.

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 a text-based frontend (wpa_cli) and a GUI (wpa_gui) are included with wpa_supplicant.

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

Supported WPA/IEEE 802.11i features

Supported EAP methods (IEEE 802.1X Supplicant)

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

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

Supported TLS/crypto libraries

Internal TLS/crypto implementation (optional)

Supported wireless cards/drivers

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 developers' documentation for more information about the design of wpa_supplicant and porting to other drivers.

Download

wpa_supplicant
Copyright (c) 2003-2008, Jouni Malinen <[email protected]> and contributors.

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. See COPYING for more details.

Alternatively, this software may be distributed, used, and modified under the terms of BSD license. See README for more details.

Please see README for the current documentation.
README-Windows.txt has some more information about the Windows port of wpa_supplicant.

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 has worked to address the flaws of the base standard and 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 published in July 2004.

Wi-Fi Alliance 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 (WPA). This has now become a mandatory component of interoperability testing and certification done by Wi-Fi Alliance. Wi-Fi has information about WPA at its web site.

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 / RSN / 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 included, e.g., support for more robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC) to replace TKIP, optimizations for handoff (reduced number of messages in initial key handshake, pre-authentication, and PMKSA caching).

Using wpa_supplicant

Following steps are used when associating with an AP using WPA:

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. In addition, simpler example configurations are available for plaintext, static WEP, IEEE 802.1X with dynamic WEP (EAP-PEAP/MSCHAPv2), WPA-PSK/TKIP, and WPA2-EAP/CCMP (EAP-TLS). In addition, wpa_supplicant can use OpenSSL engine to avoid need for exposing private keys in the file system. This can be used for EAP-TLS authentication with smartcards and TPM tokens. Example configuration for using openCryptoki shows an example network block and related parameters for EAP-TLS authentication using PKCS#11 TPM token.

Feedback, comments, mailing list

Any comments, reports on success/failure, ideas for further improvement, feature requests, etc. are welcome at [email protected]. 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 go through my mail whenever time permits.

Host AP mailing list can also be used for topics related to wpa_supplicant. Since this list has a broader audience, your likelyhood of getting responses is higher. This list is recommended for general questions about wpa_supplicant and its development. In addition, I will 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 [email protected] will be delivered to the subscribers. Please note, that due to large number of spam and virus messages sent to the list address, the list is configured to accept messages only from subscribed addresses. Messages from unsubscribed addresses may be accepted manually, but their delivery will be delayed.

If you want to make sure your bug report of feature request does not get lost, please report it through the bug tracking system as a new bug/feature request.


The server and hosting for hostap.epitest.fi is kindly provided by Internet Systems Consortium (ISC).
Jouni Malinen
Last modified: Sun Aug 10 20:31:01 EEST 2008