2N/A#pragma ident "%Z%%M% %I% %E% SMI"
2N/ACopyright (c) 2003-2004, Jouni Malinen <jkmaline@cc.hut.fi>
2N/ASun elects to license this software under the BSD license.
2N/ARedistribution and use in source and binary forms, with or without
2N/Amodification, are permitted provided that the following conditions are
2N/A1. Redistributions of source code must retain the above copyright
2N/A notice, this list of conditions and the following disclaimer.
2N/A2. Redistributions in binary form must reproduce the above copyright
2N/A notice, this list of conditions and the following disclaimer in the
2N/A documentation
and/or other materials provided with the distribution.
2N/A3. Neither the name(s) of the above-listed copyright holder(s) nor the
2N/A names of its contributors may be used to endorse or promote products
2N/A derived from this software without specific prior written permission.
2N/ATHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
2N/A"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
2N/ALIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
2N/AA PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
2N/AOWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
2N/ASPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
2N/ALIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
2N/ADATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
2N/ATHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
2N/A(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
2N/AOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2N/A- WPA-PSK ("WPA-Personal")
2N/A- WPA with EAP (
e.g., with RADIUS authentication server) ("WPA-Enterprise")
2N/A Following authentication methods are supported with an integrate IEEE 802.1X
2N/A * LEAP (note: only with WEP keys,
i.e., not for WPA; in addition, LEAP
2N/A requires special support from the driver for IEEE 802.11
2N/A (following methods are supported, but since they do not generate keying
2N/A material, they cannot be used with WPA or IEEE 802.1X WEP keying)
2N/A Alternatively, an external program,
e.g., Xsupplicant, can be used for EAP
2N/A- key management for CCMP, TKIP, WEP104, WEP40
2N/A * pre-authentication
2N/A- Linux Wireless Extensions v15 or newer
2N/A in Managed mode ('iwconfig wlan0 mode managed'). Please note that
2N/A station firmware version needs to be 1.7.0 or newer to work in
2N/A with Windows NDIS driver for your wlan card supporting WPA.
2N/A Agere Systems Inc. Linux Driver
2N/A hardware specific include files are not included in the
2N/A wpa_supplicant distribution. You will need to copy these from the
2N/A source package of the Agere driver.
2N/A madwifi driver for cards based on Atheros chip set (ar521x)
2N/A Please note that you will need to modify the wpa_supplicant Makefile
2N/A to use correct path for madwifi driver root directory
2N/A ATMEL AT76C5XXx driver for USB and PCMCIA cards
2N/A Windows NDIS driver.
2N/A In theory, any driver that supports Linux wireless extensions can be
2N/A used with IEEE 802.1X (
i.e., not WPA) when using ap_scan=0 option in
2N/Awpa_supplicant was designed to be portable for different drivers and
2N/Aoperating systems. Hopefully, support for more wlan cards will be
2N/Adesign of wpa_supplicant and porting to other drivers. One main goal
2N/Ais to add full
WPA/WPA2 support to Linux wireless extensions to allow
2N/Anew drivers to be supported without having to implement new
2N/Adriver-specific interface code in wpa_supplicant.
2N/AOptional libraries for layer2 packet processing:
2N/A- libpcap (tested with 0.7.2, most relatively recent versions assumed to work,
2N/A this is likely to be available with most distributions,
2N/A- libdnet (tested with v1.4, most versions assumed to work,
2N/AThese libraries are _not_ used in the default build. Instead, internal
2N/Aportable and they can be used by modifying Makefile (define
2N/AUSE_DNET_PCAP and link with these libraries).
2N/AOptional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS:
2N/A- openssl (tested with 0.9.7c and 0.9.7d, assumed to work with most
2N/A relatively recent versions; this is likely to be available with most
2N/AThis library is only needed when EAP-TLS, EAP-PEAP, or EAP-TTLS
2N/Asupport is enabled. WPA-PSK mode does not require this or
EAPOL/EAP 2N/Aimplementation. A configuration file, .config, for compilation is
2N/Aneeded to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5,
2N/AEAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so
2N/Amachines. However, there can be used as inner authentication
2N/Aalgorithms with EAP-PEAP and EAP-TTLS.
2N/ASee Building and installing section below for more detailed
2N/Ainformation about the wpa_supplicant build time configuration.
2N/AThe original security mechanism of IEEE 802.11 standard was not
2N/Adesigned to be strong and has proved to be insufficient for most
2N/Anetworks that require some kind of security. Task group I (Security)
2N/Ato address the flaws of the base standard and has in practice
2N/Acompleted its work in May 2004. The IEEE 802.11i amendment to the IEEE
2N/A802.11 standard was approved in June 2004 and this amendment is likely
2N/Ato be published in July 2004.
2N/AIEEE 802.11i work (draft 3.0) to define a subset of the security
2N/Aenhancements that can be implemented with existing wlan hardware. This
2N/Ais called Wi-Fi Protected Access<TM> (WPA). This has now become a
2N/Amandatory component of interoperability testing and certification done
2N/Aby Wi-Fi Alliance. Wi-Fi provides information about WPA at its web
2N/AIEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
2N/Afor protecting wireless networks. WEP uses RC4 with 40-bit keys,
2N/A24-bit initialization vector (IV), and CRC32 to protect against packet
2N/Aforgery. All these choice have proved to be insufficient: key space is
2N/Atoo small against current attacks, RC4 key scheduling is insufficient
2N/A(beginning of the pseudorandom stream should be skipped), IV space is
2N/Atoo small and IV reuse makes attacks easier, there is no replay
2N/Aprotection, and non-keyed authentication does not protect against bit
2N/Aflipping packet data.
2N/AWPA is an intermediate solution for the security issues. It uses
2N/Atemporal key integrity protocol (TKIP) to replace WEP. TKIP is a
2N/Acompromise on strong security and possibility to use existing
2N/Ahardware. It still uses RC4 for the encryption like WEP, but with
2N/Aper-packet RC4 keys. In addition, it implements replay protection,
2N/Akeyed packet authentication mechanism (Michael MIC).
2N/AKeys can be managed using two different mechanisms. WPA can either use
2N/Aan external authentication server (
e.g., RADIUS) and EAP just like
2N/AIEEE 802.1X is using or pre-shared keys without need for additional
2N/Aservers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
2N/Arespectively. Both mechanisms will generate a master session key for
2N/Athe Authenticator (AP) and Supplicant (client station).
2N/AWPA implements a new key handshake (4-Way Handshake and Group Key
2N/AHandshake) for generating and exchanging data encryption keys between
2N/Athe Authenticator and Supplicant. This handshake is also used to
2N/Averify that both Authenticator and Supplicant know the master session
2N/Akey. These handshakes are identical regardless of the selected key
2N/Amanagement mechanism (only the method for generating master session
2N/AThe design for parts of IEEE 802.11i that were not included in WPA has
2N/Afinished (May 2004) and this amendment to IEEE 802.11 was approved in
2N/AJune 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
2N/Aversion of WPA called WPA2. This includes,
e.g., support for more
2N/Arobust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
2N/Ato replace TKIP and optimizations for handoff (reduced number of
2N/Amessages in initial key handshake, pre-authentication, key caching).
2N/ASome wireless LAN vendors are already providing support for CCMP in
2N/Atheir WPA products. There is no "official" interoperability
2N/Acertification for CCMP
and/or mixed modes using both TKIP and CCMP, so
2N/Asome interoperability issues can be expected even though many
2N/Acombinations seem to be working with equipment from different vendors.
2N/ACertification for WPA2 is likely to start during the second half of
2N/Awpa_supplicant is an implementation of the WPA Supplicant component,
2N/Ai.e., the part that runs in the client stations. It implements WPA key
2N/Anegotiation with a WPA Authenticator and EAP authentication with
2N/AAuthentication Server. In addition, it controls the roaming and IEEE
2N/Awpa_supplicant is designed to be a "daemon" program that runs in the
2N/Abackground and acts as the backend component controlling the wireless
2N/Aconnection. wpa_supplicant supports separate frontend programs and an
2N/Aexample text-based frontend, wpa_cli, is included with wpa_supplicant.
2N/AFollowing steps are used when associating with an AP using WPA:
2N/A- wpa_supplicant requests the kernel driver to scan neighboring BSSes
2N/A- wpa_supplicant selects a BSS based on its configuration
2N/A- wpa_supplicant requests the kernel driver to associate with the chosen
2N/A- If WPA-EAP: integrated IEEE 802.1X Supplicant or external Xsupplicant
2N/A completes EAP authentication with the authentication server (proxied
2N/A by the Authenticator in the AP)
2N/A- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
2N/A- If WPA-PSK: wpa_supplicant uses PSK as the master session key
2N/A- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake
2N/A with the Authenticator (AP)
2N/A- wpa_supplicant configures encryption keys for unicast and broadcast
2N/A- normal data packets can be transmitted and received
2N/ABuilding and installing
2N/A-----------------------
2N/AIn order to be able to build wpa_supplicant, you will first need to
2N/Aselect which parts of it will be included. This is done by creating a
2N/Abuild time configuration file, .config, in the wpa_supplicant root
2N/Adirectory. Configuration options are text lines using following
2N/Aformat: CONFIG_<option>=y. Lines starting with # are considered
2N/Acomments and are ignored.
2N/AThe build time configuration can be used to select only the needed
2N/Afeatures and limit the binary size and requirements for external
2N/Alibraries. The main configuration parts are the selection of which
2N/Adriver interfaces (
e.g., hostap, madwifi, ..) and which authentication
2N/Amethods (
e.g., EAP-TLS, EAP-PEAP, ..) are included.
2N/AFollowing build time configuration options are used to control IEEE
2N/A802.1X/EAPOL and EAP state machines and all EAP methods. Including
2N/ATLS, PEAP, or TTLS will require linking wpa_supplicant with openssl
2N/Alibrary for TLS implementation.
2N/ACONFIG_IEEE8021X_EAPOL=y
2N/AFollowing option can be used to include GSM
SIM/USIM interface for GSM
2N/Aauthentication algorithm (for EAP-SIM). This requires pcsc-lite
2N/AFollowing options can be added to .config to select which driver
2N/AHermes driver interface needs to be downloaded from Agere (see above).
2N/AMost Linux driver need to include CONFIG_WIRELESS_EXTENSION.
2N/ACONFIG_WIRELESS_EXTENSION=y
2N/ACONFIG_DRIVER_HOSTAP=y
2N/ACONFIG_DRIVER_PRISM54=y
2N/ACONFIG_DRIVER_HERMES=y
2N/ACONFIG_DRIVER_MADWIFI=y
2N/ACONFIG_DRIVER_ATMEL=y
2N/ACONFIG_DRIVER_NDISWRAPPER=y
2N/AFollowing example includes all features and driver interfaces that are
2N/Aincluded in the wpa_supplicant package:
2N/ACONFIG_DRIVER_HOSTAP=y
2N/ACONFIG_DRIVER_PRISM54=y
2N/ACONFIG_DRIVER_HERMES=y
2N/ACONFIG_DRIVER_MADWIFI=y
2N/ACONFIG_DRIVER_ATMEL=y
2N/ACONFIG_DRIVER_NDISWRAPPER=y
2N/ACONFIG_WIRELESS_EXTENSION=y
2N/ACONFIG_IEEE8021X_EAPOL=y
2N/AEAP-PEAP and EAP-TTLS will automatically include configured EAP
2N/Amethods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection.
2N/AAfter you have created a configuration file, you can build
2N/Awpa_supplicant and wpa_cli with 'make' command. You may then install
2N/A# build wpa_supplicant and wpa_cli
2N/A# install binaries (this may need root privileges)
2N/AYou will need to make a configuration file,
e.g.,
2N/Ayou are going to use. Configuration file section below includes
2N/Aexplanation fo the configuration file format and includes various
2N/Aexamples. Once the configuration is ready, you can test whether the
2N/Aconfiguration work by first running wpa_supplicant with following
2N/Acommand to start it on foreground with debugging enabled:
2N/AAssuming everything goes fine, you can start using following command
2N/Ato start wpa_supplicant on background without debugging:
2N/APlease note that if you included more than one driver interface in the
2N/Abuild time configuration (.config), you may need to specify which
2N/Ainterface to use by including -D<driver name> option on the command
2N/Aline. See following section for more details on command line options
2N/A wpa_supplicant [-BddehLqqvw] -i<ifname> -c<config file> [-D<driver>]
2N/A -B = run daemon in the background
2N/A -d = increase debugging verbosity (-dd even more)
2N/A -e = use external IEEE 802.1X Supplicant (
e.g., xsupplicant)
2N/A (this disables the internal Supplicant)
2N/A -h = show this help text
2N/A -L = show license (GPL and BSD)
2N/A -q = decrease debugging verbosity (-qq even less)
2N/A -w = wait for interface to be added, if needed
2N/A hostap = Host AP driver (Intersil Prism2/2.5/3) [default]
2N/A (this can also be used with Linuxant DriverLoader)
2N/A not yet fully implemented
2N/A madwifi = MADWIFI 802.11 support (Atheros, etc.)
2N/A atmel = ATMEL AT76C5XXx (USB, PCMCIA)
2N/A wext = Linux wireless extensions (generic)
2N/A ndiswrapper = Linux ndiswrapper
2N/AIn most common cases, wpa_supplicant is started with
2N/AThis makes the process fork into background and wait for the wlan0
2N/Ainterface if it is not available at startup time.
2N/Awpa_supplicant is configured using a text file that lists all accepted
2N/Anetworks and security policies, including pre-shared keys. See
2N/Ainformation about the configuration format and supported fields.
2N/AChanges to configuration file can be reloaded be sending SIGHUP signal
2N/Ato wpa_supplicant ('killall -HUP wpa_supplicant'). Similarily,
2N/Areloading can be triggered with 'wpa_cli reconfigure' command.
2N/AConfiguration file can include one or more network blocks,
e.g., one
2N/Afor each used SSID. wpa_supplicant will automatically select the best
2N/Abetwork based on the order of network blocks in the configuration
2N/Afile, network security level (
WPA/WPA2 is prefered), and signal
2N/AExample configuration files for some common configurations:
2N/A1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work
2N/A# allow frontend (
e.g., wpa_cli) to be used by all users in 'wheel' group
2N/Actrl_interface_group=wheel
2N/A# home network; allow all valid ciphers
2N/A psk="very secret passphrase"
2N/A# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
2N/A identity="user@example.com"
2N/A private_key_passwd="password"
2N/A (
e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series)
2N/Actrl_interface_group=wheel
2N/A identity="user@example.com"
2N/A phase1="peaplabel=0"
2N/A phase2="auth=MSCHAPV2"
2N/A unencrypted use. Real identity is sent only within an encrypted TLS tunnel.
2N/Actrl_interface_group=wheel
2N/A identity="user@example.com"
2N/A anonymous_identity="anonymous@example.com"
2N/A4) IEEE 802.1X (
i.e., no WPA) with dynamic WEP keys (require both unicast and
2N/A broadcast); use EAP-TLS for authentication
2N/Actrl_interface_group=wheel
2N/A identity="user@example.com"
2N/A private_key_passwd="password"
2N/A5) Catch all example that allows more or less all configuration modes. The
2N/A configuration options are used based on what security policy is used in the
2N/A selected SSID. This is mostly for testing and is not recommended for normal
2N/Actrl_interface_group=wheel
2N/A key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
2N/A group=CCMP TKIP WEP104 WEP40
2N/A psk="very secret passphrase"
2N/A identity="user@example.com"
2N/A private_key_passwd="password"
2N/A phase1="peaplabel=0"
2N/A private_key2_passwd="password"
2N/ASome EAP authentication methods require use of certificates. EAP-TLS
2N/Auses both server side and client certificates whereas EAP-PEAP and
2N/AEAP-TTLS only require the server side certificate. When client
2N/Acertificate is used, a matching private key file has to also be
2N/Aincluded in configuration. If the private key uses a passphrase, this
2N/Awpa_supplicant supports X.509 certificates in PEM and DER
2N/Aformats. User certificate and private key can be included in the same
2N/AIf the user certificate and private key is received in PKCS#12/PFX
2N/Aformat, they need to be converted to suitable
PEM/DER format for
2N/Awpa_supplicant. This can be done,
e.g., with following commands:
2N/A# convert client certificate and private key to PEM format
2N/A# convert CA certificate (if included in PFX file) to PEM format
2N/Awpa_cli is a text-based frontend program for interacting with
2N/Awpa_supplicant. It is used to query current status, change
2N/Aconfiguration, trigger events, and request interactive user input.
2N/Awpa_cli can show the current authentication status, selected security
2N/Amode, dot11 and dot1x MIBs, etc. In addition, it can configuring some
2N/Avariables like EAPOL state machine parameters and trigger events like
2N/Ainterface to request authentication information, like username and
2N/Apassword, if these are not included in the configuration. This can be
2N/Aused to implement,
e.g., one-time-passwords or generic token card
2N/Aauthentication where the authentication is based on a
2N/Achallenge-response that uses an external device for generating the
2N/AThe control interface of wpa_supplicant can be configured to allow
2N/Anon-root user access (ctrl_interface_group in the configuration
2N/Afile). This makes it possible to run wpa_cli with a normal user
2N/Awpa_cli supports two modes: interactive and command line. Both modes
2N/Ashare the same command set and the main difference is in interactive
2N/Amode providing access to unsolicited messages (event messages,
2N/AInteractive mode is started when wpa_cli is executed without including
2N/Athe command as a command line parameter. Commands are then entered on
2N/Athe wpa_cli prompt. In command line mode, the same commands are
2N/Aentered as command line arguments for wpa_cli.
2N/AInteractive authentication parameters request
2N/AWhen wpa_supplicant need authentication parameters, like username and
2N/Apassword, which are not present in the configuration file, it sends a
2N/Arequest message to all attached frontend programs,
e.g., wpa_cli in
2N/Ainteractive mode. wpa_cli shows these requests with
2N/A"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or
2N/AOTP (one-time-password). <id> is a unique identifier for the current
2N/Anetwork. <text> is description of the request. In case of OTP request,
2N/Ait includes the challenge from the authentication server.
2N/AThe reply to these requests can be given with 'identity', 'password',
2N/Aand 'otp' commands. <id> needs to be copied from the the matching
2N/Arequest. 'password' and 'otp' commands can be used regardless of
2N/Awhether the request was for PASSWORD or OTP. The main difference
2N/Abetween these two commands is that values given with 'password' are
2N/Aremembered as long as wpa_supplicant is running whereas values given
2N/Awith 'otp' are used only once and then forgotten,
i.e., wpa_supplicant
2N/Awill ask frontend for a new value for every use. This can be used to
2N/Aimplement one-time-password lists and generic token card -based
2N/AExample request for password and a matching reply:
2N/ACTRL-REQ-PASSWORD-1:Password needed for SSID foobar
2N/A> password 1 mysecretpassword
2N/AExample request for generic token card challenge-response:
2N/ACTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
2N/A mib = get MIB variables (dot1x, dot11)
2N/A help = show this usage help
2N/A level <debug level> = change debug level
2N/A license = show full wpa_cli license
2N/A logoff = IEEE 802.1X EAPOL state machine logoff
2N/A logon = IEEE 802.1X EAPOL state machine logon
2N/A set = set variables (shows list of variables when run without arguments)
2N/A pmksa = show PMKSA cache
2N/A reassociate = force reassociation
2N/A reconfigure = force wpa_supplicant to re-read its configuration file
2N/A preauthenticate <BSSID> = force preauthentication
2N/A identity <network id> <identity> = configure identity for an SSID
2N/A password <network id> <password> = configure password for an SSID
2N/A otp <network id> <password> = configure one-time-password for an SSID
2N/A------------------------------------------
2N/Awpa_supplicant needs to be running when using a wireless network with
2N/AWPA. It can be started either from system startup scripts or from
2N/Acompleted before data frames can be exchanged, so wpa_supplicant
2N/Ashould be started before DHCP client.
2N/ACommand line option '-w' can be used if wpa_supplicant is started
2N/Abefore the wireless LAN interface is present (
e.g., before inserting
2N/Athe PC Card) or is not yet up.
2N/AFor example, following small changes to pcmcia-cs scripts can be used
2N/Ato enable WPA support:
2N/AAdd MODE="Managed" and WPA="y" to the network scheme in
2N/AAdd the following block to the end of 'start' action handler in
2N/AAdd the following block to the end of 'stop' action handler (may need
2N/A killall wpa_supplicant
2N/AThis will make cardmgr start wpa_supplicant when the card is plugged
2N/Ain. wpa_supplicant will wait until the interface is set up--either
2N/Awhen a static IP address is configured or when DHCP client is
2N/Astarted--and will then negotiate keys with the AP.
2N/AOptional integration with Xsupplicant
2N/A-------------------------------------
2N/Awpa_supplicant has an integrated IEEE 802.1X Supplicant that supports
2N/Amost commonly used EAP methods. In addition, wpa_supplicant has an
2N/Aexperimental interface for integrating it with Xsupplicant
2N/AXsupplicant needs to be modified to send master session key to
2N/Awpa_supplicant after successful EAP authentication. The included patch
2N/Axsupplicant CVS on February 6, 2004, so any snapshot after that should
2N/Ahave the needed functionality already included.
2N/AWhen using WPA-EAP, both wpa_supplicant and Xsupplicant must be
2N/Aconfigured with the network security policy. See Xsupplicant documents
2N/Afor information about its configuration. Please also note, that a new
2N/Abe used when starting xsupplicant.
2N/AExample configuration for xsupplicant:
2N/Adefault_netname = jkm
2N/A allow_types = eap_peap
2N/A identity = <BEGIN_ID>jkm<END_ID>
2N/A allow_types = eap_mschapv2
2N/A username = <BEGIN_UNAME>jkm<END_UNAME>
2N/A password = <BEGIN_PASS>jkm<END_PASS>
2N/AExample configuration for wpa_supplicant:
2N/ABoth wpa_supplicant and xsupplicant need to be started. Please remember
2N/Ato add '-W' option for xsupplicant in order to provide keying material
2N/Afor wpa_supplicant and '-e' option for wpa_supplicant to disable internal
2N/AIEEE 802.1X implementation.