contrib/wpa_supplicant/README

   1 WPA Supplicant
   2 ==============
   3
   4 Copyright (c) 2003-2005, Jouni Malinen <jkmaline@cc.hut.fi> and
   5 contributors
   6 All Rights Reserved.
   7
   8 This program is dual-licensed under both the GPL version 2 and BSD
   9 license. Either license may be used at your option.
  10
  11
  12
  13 License
  14 -------
  15
  16 GPL v2:
  17
  18 This program is free software; you can redistribute it and/or modify
  19 it under the terms of the GNU General Public License version 2 as
  20 published by the Free Software Foundation.
  21
  22 This program is distributed in the hope that it will be useful,
  23 but WITHOUT ANY WARRANTY; without even the implied warranty of
  24 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25 GNU General Public License for more details.
  26
  27 You should have received a copy of the GNU General Public License
  28 along with this program; if not, write to the Free Software
  29 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  30
  31 (this copy of the license is in COPYING file)
  32
  33
  34 Alternatively, this software may be distributed under the terms of BSD
  35 license:
  36
  37 Redistribution and use in source and binary forms, with or without
  38 modification, are permitted provided that the following conditions are
  39 met:
  40
  41 1. Redistributions of source code must retain the above copyright
  42    notice, this list of conditions and the following disclaimer.
  43
  44 2. Redistributions in binary form must reproduce the above copyright
  45    notice, this list of conditions and the following disclaimer in the
  46    documentation and/or other materials provided with the distribution.
  47
  48 3. Neither the name(s) of the above-listed copyright holder(s) nor the
  49    names of its contributors may be used to endorse or promote products
  50    derived from this software without specific prior written permission.
  51
  52 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  53 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  54 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  55 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  56 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  57 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  58 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  59 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  60 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  61 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  62 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  63
  64
  65
  66 Features
  67 --------
  68
  69 Supported WPA/IEEE 802.11i features:
  70 - WPA-PSK ("WPA-Personal")
  71 - WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")
  72   Following authentication methods are supported with an integrate IEEE 802.1X
  73   Supplicant:
  74   * EAP-TLS
  75   * EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
  76   * EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
  77   * EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
  78   * EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
  79   * EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
  80   * EAP-TTLS/EAP-MD5-Challenge
  81   * EAP-TTLS/EAP-GTC
  82   * EAP-TTLS/EAP-OTP
  83   * EAP-TTLS/EAP-MSCHAPv2
  84   * EAP-TTLS/EAP-TLS
  85   * EAP-TTLS/MSCHAPv2
  86   * EAP-TTLS/MSCHAP
  87   * EAP-TTLS/PAP
  88   * EAP-TTLS/CHAP
  89   * EAP-SIM
  90   * EAP-AKA
  91   * EAP-PSK
  92   * LEAP (note: requires special support from the driver for IEEE 802.11
  93           authentication)
  94   (following methods are supported, but since they do not generate keying
  95    material, they cannot be used with WPA or IEEE 802.1X WEP keying)
  96   * EAP-MD5-Challenge
  97   * EAP-MSCHAPv2
  98   * EAP-GTC
  99   * EAP-OTP
 100   Alternatively, an external program, e.g., Xsupplicant, can be used for EAP
 101   authentication.
 102 - key management for CCMP, TKIP, WEP104, WEP40
 103 - RSN/WPA2 (IEEE 802.11i)
 104   * pre-authentication
 105   * PMKSA caching
 106
 107
 108
 109 Requirements
 110 ------------
 111
 112 Current hardware/software requirements:
 113 - Linux kernel 2.4.x or 2.6.x with Linux Wireless Extensions v15 or newer
 114 - FreeBSD 6-CURRENT
 115 - Microsoft Windows with WinPcap (at least WinXP, may work with other versions)
 116 - drivers:
 117         Host AP driver for Prism2/2.5/3 (development snapshot/v0.2.x)
 118         (http://hostap.epitest.fi/)
 119         Driver need to be set in Managed mode ('iwconfig wlan0 mode managed').
 120         Please note that station firmware version needs to be 1.7.0 or newer
 121         to work in WPA mode.
 122
 123         Linuxant DriverLoader (http://www.linuxant.com/driverloader/)
 124         with Windows NDIS driver for your wlan card supporting WPA.
 125
 126         Agere Systems Inc. Linux Driver
 127         (http://www.agere.com/support/drivers/)
 128         Please note that the driver interface file (driver_hermes.c) and
 129         hardware specific include files are not included in the
 130         wpa_supplicant distribution. You will need to copy these from the
 131         source package of the Agere driver.
 132
 133         madwifi driver for cards based on Atheros chip set (ar521x)
 134         (http://sourceforge.net/projects/madwifi/)
 135         Please note that you will need to modify the wpa_supplicant .config
 136         file to use the correct path for the madwifi driver root directory
 137         (CFLAGS += -I../madwifi/wpa line in example defconfig).
 138
 139         ATMEL AT76C5XXx driver for USB and PCMCIA cards
 140         (http://atmelwlandriver.sourceforge.net/).
 141
 142         Linux ndiswrapper (http://ndiswrapper.sourceforge.net/) with
 143         Windows NDIS driver.
 144
 145         Broadcom wl.o driver
 146         This is a generic Linux driver for Broadcom IEEE 802.11a/g cards.
 147         However, it is proprietary driver that is not publicly available
 148         except for couple of exceptions, mainly Broadcom-based APs/wireless
 149         routers that use Linux. The driver binary can be downloaded, e.g.,
 150         from Linksys support site (http://www.linksys.com/support/gpl.asp)
 151         for Linksys WRT54G. The GPL tarball includes cross-compiler and
 152         the needed header file, wlioctl.h, for compiling wpa_supplicant.
 153         This driver support in wpa_supplicant is expected to work also with
 154         other devices based on Broadcom driver (assuming the driver includes
 155         client mode support).
 156
 157         Intel ipw2100 driver
 158         (http://sourceforge.net/projects/ipw2100/)
 159
 160         Intel ipw2200 driver
 161         (http://sourceforge.net/projects/ipw2200/)
 162
 163         In theory, any driver that supports Linux wireless extensions can be
 164         used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in
 165         configuration file.
 166
 167         BSD net80211 layer (e.g., Atheros driver)
 168         At the moment, this is for FreeBSD 6-CURRENT branch.
 169
 170         Windows NDIS
 171         The current Windows port requires WinPcap (http://winpcap.polito.it/).
 172         See README-Windows.txt for more information.
 173
 174 wpa_supplicant was designed to be portable for different drivers and
 175 operating systems. Hopefully, support for more wlan cards and OSes will be
 176 added in the future. See developer.txt for more information about the
 177 design of wpa_supplicant and porting to other drivers. One main goal
 178 is to add full WPA/WPA2 support to Linux wireless extensions to allow
 179 new drivers to be supported without having to implement new
 180 driver-specific interface code in wpa_supplicant.
 181
 182 Optional libraries for layer2 packet processing:
 183 - libpcap (tested with 0.7.2, most relatively recent versions assumed to work,
 184         this is likely to be available with most distributions,
 185         http://tcpdump.org/)
 186 - libdnet (tested with v1.4, most versions assumed to work,
 187         http://libdnet.sourceforge.net/)
 188
 189 These libraries are _not_ used in the default Linux build. Instead,
 190 internal Linux specific implementation is used. libpcap/libdnet are
 191 more portable and they can be used by adding CONFIG_DNET_PCAP=y into
 192 .config. They may also be selected automatically for other operating
 193 systems.
 194
 195
 196 Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS:
 197 - openssl (tested with 0.9.7c and 0.9.7d, assumed to work with most
 198   relatively recent versions; this is likely to be available with most
 199   distributions, http://www.openssl.org/)
 200
 201 This library is only needed when EAP-TLS, EAP-PEAP, or EAP-TTLS
 202 support is enabled. WPA-PSK mode does not require this or EAPOL/EAP
 203 implementation. A configuration file, .config, for compilation is
 204 needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5,
 205 EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so
 206 they should only be enabled if testing the EAPOL/EAP state
 207 machines. However, there can be used as inner authentication
 208 algorithms with EAP-PEAP and EAP-TTLS.
 209
 210 See Building and installing section below for more detailed
 211 information about the wpa_supplicant build time configuration.
 212
 213
 214
 215 WPA
 216 ---
 217
 218 The original security mechanism of IEEE 802.11 standard was not
 219 designed to be strong and has proven to be insufficient for most
 220 networks that require some kind of security. Task group I (Security)
 221 of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked
 222 to address the flaws of the base standard and has in practice
 223 completed its work in May 2004. The IEEE 802.11i amendment to the IEEE
 224 802.11 standard was approved in June 2004 and this amendment is likely
 225 to be published in July 2004.
 226
 227 Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the
 228 IEEE 802.11i work (draft 3.0) to define a subset of the security
 229 enhancements that can be implemented with existing wlan hardware. This
 230 is called Wi-Fi Protected Access<TM> (WPA). This has now become a
 231 mandatory component of interoperability testing and certification done
 232 by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web
 233 site (http://www.wi-fi.org/OpenSection/protected_access.asp).
 234
 235 IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
 236 for protecting wireless networks. WEP uses RC4 with 40-bit keys,
 237 24-bit initialization vector (IV), and CRC32 to protect against packet
 238 forgery. All these choices have proven to be insufficient: key space is
 239 too small against current attacks, RC4 key scheduling is insufficient
 240 (beginning of the pseudorandom stream should be skipped), IV space is
 241 too small and IV reuse makes attacks easier, there is no replay
 242 protection, and non-keyed authentication does not protect against bit
 243 flipping packet data.
 244
 245 WPA is an intermediate solution for the security issues. It uses
 246 Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a
 247 compromise on strong security and possibility to use existing
 248 hardware. It still uses RC4 for the encryption like WEP, but with
 249 per-packet RC4 keys. In addition, it implements replay protection,
 250 keyed packet authentication mechanism (Michael MIC).
 251
 252 Keys can be managed using two different mechanisms. WPA can either use
 253 an external authentication server (e.g., RADIUS) and EAP just like
 254 IEEE 802.1X is using or pre-shared keys without need for additional
 255 servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
 256 respectively. Both mechanisms will generate a master session key for
 257 the Authenticator (AP) and Supplicant (client station).
 258
 259 WPA implements a new key handshake (4-Way Handshake and Group Key
 260 Handshake) for generating and exchanging data encryption keys between
 261 the Authenticator and Supplicant. This handshake is also used to
 262 verify that both Authenticator and Supplicant know the master session
 263 key. These handshakes are identical regardless of the selected key
 264 management mechanism (only the method for generating master session
 265 key changes).
 266
 267
 268
 269 IEEE 802.11i / WPA2
 270 -------------------
 271
 272 The design for parts of IEEE 802.11i that were not included in WPA has
 273 finished (May 2004) and this amendment to IEEE 802.11 was approved in
 274 June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
 275 version of WPA called WPA2. This includes, e.g., support for more
 276 robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
 277 to replace TKIP and optimizations for handoff (reduced number of
 278 messages in initial key handshake, pre-authentication, and PMKSA caching).
 279
 280 Some wireless LAN vendors are already providing support for CCMP in
 281 their WPA products. There is no "official" interoperability
 282 certification for CCMP and/or mixed modes using both TKIP and CCMP, so
 283 some interoperability issues can be expected even though many
 284 combinations seem to be working with equipment from different vendors.
 285 Certification for WPA2 is likely to start during the second half of
 286 2004.
 287
 288
 289
 290 wpa_supplicant
 291 --------------
 292
 293 wpa_supplicant is an implementation of the WPA Supplicant component,
 294 i.e., the part that runs in the client stations. It implements WPA key
 295 negotiation with a WPA Authenticator and EAP authentication with
 296 Authentication Server. In addition, it controls the roaming and IEEE
 297 802.11 authentication/association of the wlan driver.
 298
 299 wpa_supplicant is designed to be a "daemon" program that runs in the
 300 background and acts as the backend component controlling the wireless
 301 connection. wpa_supplicant supports separate frontend programs and an
 302 example text-based frontend, wpa_cli, is included with wpa_supplicant.
 303
 304 Following steps are used when associating with an AP using WPA:
 305
 306 - wpa_supplicant requests the kernel driver to scan neighboring BSSes
 307 - wpa_supplicant selects a BSS based on its configuration
 308 - wpa_supplicant requests the kernel driver to associate with the chosen
 309   BSS
 310 - If WPA-EAP: integrated IEEE 802.1X Supplicant or external Xsupplicant
 311   completes EAP authentication with the authentication server (proxied
 312   by the Authenticator in the AP)
 313 - If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
 314 - If WPA-PSK: wpa_supplicant uses PSK as the master session key
 315 - wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake
 316   with the Authenticator (AP)
 317 - wpa_supplicant configures encryption keys for unicast and broadcast
 318 - normal data packets can be transmitted and received
 319
 320
 321
 322 Building and installing
 323 -----------------------
 324
 325 In order to be able to build wpa_supplicant, you will first need to
 326 select which parts of it will be included. This is done by creating a
 327 build time configuration file, .config, in the wpa_supplicant root
 328 directory. Configuration options are text lines using following
 329 format: CONFIG_<option>=y. Lines starting with # are considered
 330 comments and are ignored. See defconfig file for example configuration
 331 and list of available option.
 332
 333 The build time configuration can be used to select only the needed
 334 features and limit the binary size and requirements for external
 335 libraries. The main configuration parts are the selection of which
 336 driver interfaces (e.g., hostap, madwifi, ..) and which authentication
 337 methods (e.g., EAP-TLS, EAP-PEAP, ..) are included.
 338
 339 Following build time configuration options are used to control IEEE
 340 802.1X/EAPOL and EAP state machines and all EAP methods. Including
 341 TLS, PEAP, or TTLS will require linking wpa_supplicant with openssl
 342 library for TLS implementation.
 343
 344 CONFIG_IEEE8021X_EAPOL=y
 345 CONFIG_EAP_MD5=y
 346 CONFIG_EAP_MSCHAPV2=y
 347 CONFIG_EAP_TLS=y
 348 CONFIG_EAP_PEAP=y
 349 CONFIG_EAP_TTLS=y
 350 CONFIG_EAP_GTC=y
 351 CONFIG_EAP_OTP=y
 352 CONFIG_EAP_SIM=y
 353 CONFIG_EAP_AKA=y
 354 CONFIG_EAP_PSK=y
 355 CONFIG_EAP_LEAP=y
 356
 357 Following option can be used to include GSM SIM/USIM interface for GSM/UMTS
 358 authentication algorithm (for EAP-SIM/EAP-AKA). This requires pcsc-lite
 359 (http://www.linuxnet.com/) for smart card access.
 360
 361 CONFIG_PCSC=y
 362
 363 Following option can be used to replace the native Linux packet socket
 364 interface with libpcap/libdnet.
 365
 366 CONFIG_DNET_PCAP=y
 367
 368 Following options can be added to .config to select which driver
 369 interfaces are included. Prism54.org driver is not yet complete and
 370 Hermes driver interface needs to be downloaded from Agere (see above).
 371 Most Linux driver need to include CONFIG_WIRELESS_EXTENSION.
 372
 373 CONFIG_WIRELESS_EXTENSION=y
 374 CONFIG_DRIVER_HOSTAP=y
 375 CONFIG_DRIVER_PRISM54=y
 376 CONFIG_DRIVER_HERMES=y
 377 CONFIG_DRIVER_MADWIFI=y
 378 CONFIG_DRIVER_ATMEL=y
 379 CONFIG_DRIVER_WEXT=y
 380 CONFIG_DRIVER_NDISWRAPPER=y
 381 CONFIG_DRIVER_BROADCOM=y
 382 CONFIG_DRIVER_IPW=y
 383 CONFIG_DRIVER_BSD=y
 384 CONFIG_DRIVER_NDIS=y
 385
 386 Following example includes all features and driver interfaces that are
 387 included in the wpa_supplicant package:
 388
 389 CONFIG_DRIVER_HOSTAP=y
 390 CONFIG_DRIVER_PRISM54=y
 391 CONFIG_DRIVER_HERMES=y
 392 CONFIG_DRIVER_MADWIFI=y
 393 CONFIG_DRIVER_ATMEL=y
 394 CONFIG_DRIVER_WEXT=y
 395 CONFIG_DRIVER_NDISWRAPPER=y
 396 CONFIG_DRIVER_BROADCOM=y
 397 CONFIG_DRIVER_IPW=y
 398 CONFIG_DRIVER_BSD=y
 399 CONFIG_DRIVER_NDIS=y
 400 CONFIG_WIRELESS_EXTENSION=y
 401 CONFIG_IEEE8021X_EAPOL=y
 402 CONFIG_EAP_MD5=y
 403 CONFIG_EAP_MSCHAPV2=y
 404 CONFIG_EAP_TLS=y
 405 CONFIG_EAP_PEAP=y
 406 CONFIG_EAP_TTLS=y
 407 CONFIG_EAP_GTC=y
 408 CONFIG_EAP_OTP=y
 409 CONFIG_EAP_SIM=y
 410 CONFIG_EAP_AKA=y
 411 CONFIG_EAP_PSK=y
 412 CONFIG_EAP_LEAP=y
 413 CONFIG_PCSC=y
 414
 415 EAP-PEAP and EAP-TTLS will automatically include configured EAP
 416 methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection.
 417
 418
 419 After you have created a configuration file, you can build
 420 wpa_supplicant and wpa_cli with 'make' command. You may then install
 421 the binaries to a suitable system directory, e.g., /usr/local/bin.
 422
 423 Example commands:
 424
 425 # build wpa_supplicant and wpa_cli
 426 make
 427 # install binaries (this may need root privileges)
 428 cp wpa_cli wpa_supplicant /usr/local/bin
 429
 430
 431 You will need to make a configuration file, e.g.,
 432 /etc/wpa_supplicant.conf, with network configuration for the networks
 433 you are going to use. Configuration file section below includes
 434 explanation fo the configuration file format and includes various
 435 examples. Once the configuration is ready, you can test whether the
 436 configuration work by first running wpa_supplicant with following
 437 command to start it on foreground with debugging enabled:
 438
 439 wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
 440
 441 Assuming everything goes fine, you can start using following command
 442 to start wpa_supplicant on background without debugging:
 443
 444 wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
 445
 446 Please note that if you included more than one driver interface in the
 447 build time configuration (.config), you may need to specify which
 448 interface to use by including -D<driver name> option on the command
 449 line. See following section for more details on command line options
 450 for wpa_supplicant.
 451
 452
 453
 454 Command line options
 455 --------------------
 456
 457 usage:
 458   wpa_supplicant [-BddehLqqvw] -i<ifname> -c<config file> [-D<driver>] \
 459       [-N -i<ifname> -c<conf> [-D<driver>] ...]
 460
 461 options:
 462   -B = run daemon in the background
 463   -d = increase debugging verbosity (-dd even more)
 464   -K = include keys (passwords, etc.) in debug output
 465   -t = include timestamp in debug messages
 466   -e = use external IEEE 802.1X Supplicant (e.g., xsupplicant)
 467        (this disables the internal Supplicant)
 468   -h = show this help text
 469   -L = show license (GPL and BSD)
 470   -q = decrease debugging verbosity (-qq even less)
 471   -v = show version
 472   -w = wait for interface to be added, if needed
 473   -N = start describing new interface
 474
 475 drivers:
 476   hostap = Host AP driver (Intersil Prism2/2.5/3) [default]
 477         (this can also be used with Linuxant DriverLoader)
 478   prism54 = Prism54.org driver (Intersil Prism GT/Duette/Indigo)
 479         not yet fully implemented
 480   hermes = Agere Systems Inc. driver (Hermes-I/Hermes-II)
 481   madwifi = MADWIFI 802.11 support (Atheros, etc.)
 482   atmel = ATMEL AT76C5XXx (USB, PCMCIA)
 483   wext = Linux wireless extensions (generic)
 484   ndiswrapper = Linux ndiswrapper
 485   broadcom = Broadcom wl.o driver
 486   ipw = Intel ipw2100/2200 driver
 487   bsd = BSD 802.11 support (Atheros, etc.)
 488   ndis = Windows NDIS driver
 489
 490 In most common cases, wpa_supplicant is started with
 491
 492 wpa_supplicant -Bw -c/etc/wpa_supplicant.conf -iwlan0
 493
 494 This makes the process fork into background and wait for the wlan0
 495 interface if it is not available at startup time.
 496
 497 The easiest way to debug problems, and to get debug log for bug
 498 reports, is to start wpa_supplicant on foreground with debugging
 499 enabled:
 500
 501 wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
 502
 503
 504 wpa_supplicant can control multiple interfaces (radios) either by
 505 running one process for each interface separately or by running just
 506 one process and list of options at command line. Each interface is
 507 separated with -N argument. As an example, following command would
 508 start wpa_supplicant for two interfaces:
 509
 510 wpa_supplicant \
 511         -c wpa1.conf -i wlan0 -D hostap -N \
 512         -c wpa2.conf -i ath0 -D madwifi
 513
 514
 515 Configuration file
 516 ------------------
 517
 518 wpa_supplicant is configured using a text file that lists all accepted
 519 networks and security policies, including pre-shared keys. See
 520 example configuration file, wpa_supplicant.conf, for detailed
 521 information about the configuration format and supported fields.
 522
 523 Changes to configuration file can be reloaded be sending SIGHUP signal
 524 to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly,
 525 reloading can be triggered with 'wpa_cli reconfigure' command.
 526
 527 Configuration file can include one or more network blocks, e.g., one
 528 for each used SSID. wpa_supplicant will automatically select the best
 529 betwork based on the order of network blocks in the configuration
 530 file, network security level (WPA/WPA2 is prefered), and signal
 531 strength.
 532
 533 Example configuration files for some common configurations:
 534
 535 1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work
 536    network
 537
 538 # allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
 539 ctrl_interface=/var/run/wpa_supplicant
 540 ctrl_interface_group=wheel
 541 #
 542 # home network; allow all valid ciphers
 543 network={
 544         ssid="home"
 545         scan_ssid=1
 546         key_mgmt=WPA-PSK
 547         psk="very secret passphrase"
 548 }
 549 #
 550 # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
 551 network={
 552         ssid="work"
 553         scan_ssid=1
 554         key_mgmt=WPA-EAP
 555         pairwise=CCMP TKIP
 556         group=CCMP TKIP
 557         eap=TLS
 558         identity="user@example.com"
 559         ca_cert="/etc/cert/ca.pem"
 560         client_cert="/etc/cert/user.pem"
 561         private_key="/etc/cert/user.prv"
 562         private_key_passwd="password"
 563 }
 564
 565
 566 2) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
 567    (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series)
 568
 569 ctrl_interface=/var/run/wpa_supplicant
 570 ctrl_interface_group=wheel
 571 network={
 572         ssid="example"
 573         scan_ssid=1
 574         key_mgmt=WPA-EAP
 575         eap=PEAP
 576         identity="user@example.com"
 577         password="foobar"
 578         ca_cert="/etc/cert/ca.pem"
 579         phase1="peaplabel=0"
 580         phase2="auth=MSCHAPV2"
 581 }
 582
 583
 584 3) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
 585    unencrypted use. Real identity is sent only within an encrypted TLS tunnel.
 586
 587 ctrl_interface=/var/run/wpa_supplicant
 588 ctrl_interface_group=wheel
 589 network={
 590         ssid="example"
 591         scan_ssid=1
 592         key_mgmt=WPA-EAP
 593         eap=TTLS
 594         identity="user@example.com"
 595         anonymous_identity="anonymous@example.com"
 596         password="foobar"
 597         ca_cert="/etc/cert/ca.pem"
 598         phase2="auth=MD5"
 599 }
 600
 601
 602 4) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and
 603    broadcast); use EAP-TLS for authentication
 604
 605 ctrl_interface=/var/run/wpa_supplicant
 606 ctrl_interface_group=wheel
 607 network={
 608         ssid="1x-test"
 609         scan_ssid=1
 610         key_mgmt=IEEE8021X
 611         eap=TLS
 612         identity="user@example.com"
 613         ca_cert="/etc/cert/ca.pem"
 614         client_cert="/etc/cert/user.pem"
 615         private_key="/etc/cert/user.prv"
 616         private_key_passwd="password"
 617         eapol_flags=3
 618 }
 619
 620
 621 5) Catch all example that allows more or less all configuration modes. The
 622    configuration options are used based on what security policy is used in the
 623    selected SSID. This is mostly for testing and is not recommended for normal
 624    use.
 625
 626 ctrl_interface=/var/run/wpa_supplicant
 627 ctrl_interface_group=wheel
 628 network={
 629         ssid="example"
 630         scan_ssid=1
 631         key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
 632         pairwise=CCMP TKIP
 633         group=CCMP TKIP WEP104 WEP40
 634         psk="very secret passphrase"
 635         eap=TTLS PEAP TLS
 636         identity="user@example.com"
 637         password="foobar"
 638         ca_cert="/etc/cert/ca.pem"
 639         client_cert="/etc/cert/user.pem"
 640         private_key="/etc/cert/user.prv"
 641         private_key_passwd="password"
 642         phase1="peaplabel=0"
 643         ca_cert2="/etc/cert/ca2.pem"
 644         client_cert2="/etc/cer/user.pem"
 645         private_key2="/etc/cer/user.prv"
 646         private_key2_passwd="password"
 647 }
 648
 649
 650
 651 Certificates
 652 ------------
 653
 654 Some EAP authentication methods require use of certificates. EAP-TLS
 655 uses both server side and client certificates whereas EAP-PEAP and
 656 EAP-TTLS only require the server side certificate. When client
 657 certificate is used, a matching private key file has to also be
 658 included in configuration. If the private key uses a passphrase, this
 659 has to be configured in wpa_supplicant.conf ("private_key_passwd").
 660
 661 wpa_supplicant supports X.509 certificates in PEM and DER
 662 formats. User certificate and private key can be included in the same
 663 file.
 664
 665 If the user certificate and private key is received in PKCS#12/PFX
 666 format, they need to be converted to suitable PEM/DER format for
 667 wpa_supplicant. This can be done, e.g., with following commands:
 668
 669 # convert client certificate and private key to PEM format
 670 openssl pkcs12 -in example.pfx -out user.pem -clcerts
 671 # convert CA certificate (if included in PFX file) to PEM format
 672 openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
 673
 674
 675
 676 wpa_cli
 677 -------
 678
 679 wpa_cli is a text-based frontend program for interacting with
 680 wpa_supplicant. It is used to query current status, change
 681 configuration, trigger events, and request interactive user input.
 682
 683 wpa_cli can show the current authentication status, selected security
 684 mode, dot11 and dot1x MIBs, etc. In addition, it can configuring some
 685 variables like EAPOL state machine parameters and trigger events like
 686 reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user
 687 interface to request authentication information, like username and
 688 password, if these are not included in the configuration. This can be
 689 used to implement, e.g., one-time-passwords or generic token card
 690 authentication where the authentication is based on a
 691 challenge-response that uses an external device for generating the
 692 response.
 693
 694 The control interface of wpa_supplicant can be configured to allow
 695 non-root user access (ctrl_interface_group in the configuration
 696 file). This makes it possible to run wpa_cli with a normal user
 697 account.
 698
 699 wpa_cli supports two modes: interactive and command line. Both modes
 700 share the same command set and the main difference is in interactive
 701 mode providing access to unsolicited messages (event messages,
 702 username/password requests).
 703
 704 Interactive mode is started when wpa_cli is executed without including
 705 the command as a command line parameter. Commands are then entered on
 706 the wpa_cli prompt. In command line mode, the same commands are
 707 entered as command line arguments for wpa_cli.
 708
 709
 710 Interactive authentication parameters request
 711
 712 When wpa_supplicant need authentication parameters, like username and
 713 password, which are not present in the configuration file, it sends a
 714 request message to all attached frontend programs, e.g., wpa_cli in
 715 interactive mode. wpa_cli shows these requests with
 716 "CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or
 717 OTP (one-time-password). <id> is a unique identifier for the current
 718 network. <text> is description of the request. In case of OTP request,
 719 it includes the challenge from the authentication server.
 720
 721 The reply to these requests can be given with 'identity', 'password',
 722 and 'otp' commands. <id> needs to be copied from the the matching
 723 request. 'password' and 'otp' commands can be used regardless of
 724 whether the request was for PASSWORD or OTP. The main difference
 725 between these two commands is that values given with 'password' are
 726 remembered as long as wpa_supplicant is running whereas values given
 727 with 'otp' are used only once and then forgotten, i.e., wpa_supplicant
 728 will ask frontend for a new value for every use. This can be used to
 729 implement one-time-password lists and generic token card -based
 730 authentication.
 731
 732 Example request for password and a matching reply:
 733
 734 CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
 735 > password 1 mysecretpassword
 736
 737 Example request for generic token card challenge-response:
 738
 739 CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
 740 > otp 2 9876
 741
 742
 743 wpa_cli commands
 744
 745   status = get current WPA/EAPOL/EAP status
 746   mib = get MIB variables (dot1x, dot11)
 747   help = show this usage help
 748   interface [ifname] = show interfaces/select interface
 749   level <debug level> = change debug level
 750   license = show full wpa_cli license
 751   logoff = IEEE 802.1X EAPOL state machine logoff
 752   logon = IEEE 802.1X EAPOL state machine logon
 753   set = set variables (shows list of variables when run without arguments)
 754   pmksa = show PMKSA cache
 755   reassociate = force reassociation
 756   reconfigure = force wpa_supplicant to re-read its configuration file
 757   preauthenticate <BSSID> = force preauthentication
 758   identity <network id> <identity> = configure identity for an SSID
 759   password <network id> <password> = configure password for an SSID
 760   otp <network id> <password> = configure one-time-password for an SSID
 761   terminate = terminate wpa_supplicant
 762   quit = exit wpa_cli
 763
 764
 765
 766 Integrating with pcmcia-cs/cardmgr scripts
 767 ------------------------------------------
 768
 769 wpa_supplicant needs to be running when using a wireless network with
 770 WPA. It can be started either from system startup scripts or from
 771 pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be
 772 completed before data frames can be exchanged, so wpa_supplicant
 773 should be started before DHCP client.
 774
 775 Command line option '-w' can be used if wpa_supplicant is started
 776 before the wireless LAN interface is present (e.g., before inserting
 777 the PC Card) or is not yet up.
 778
 779 For example, following small changes to pcmcia-cs scripts can be used
 780 to enable WPA support:
 781
 782 Add MODE="Managed" and WPA="y" to the network scheme in
 783 /etc/pcmcia/wireless.opts.
 784
 785 Add the following block to the end of 'start' action handler in
 786 /etc/pcmcia/wireless:
 787
 788     if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
 789         /usr/local/bin/wpa_supplicant -Bw -c/etc/wpa_supplicant.conf \
 790                 -i$DEVICE
 791     fi
 792
 793 Add the following block to the end of 'stop' action handler (may need
 794 to be separated from other actions) in /etc/pcmcia/wireless:
 795
 796     if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
 797         killall wpa_supplicant
 798     fi
 799
 800 This will make cardmgr start wpa_supplicant when the card is plugged
 801 in. wpa_supplicant will wait until the interface is set up--either
 802 when a static IP address is configured or when DHCP client is
 803 started--and will then negotiate keys with the AP.
 804
 805
 806
 807 Optional integration with Xsupplicant
 808 -------------------------------------
 809
 810 wpa_supplicant has an integrated IEEE 802.1X Supplicant that supports
 811 most commonly used EAP methods. In addition, wpa_supplicant has an
 812 experimental interface for integrating it with Xsupplicant
 813 (http://www.open1x.org/) for the WPA with EAP authentication.
 814
 815 When using WPA-EAP, both wpa_supplicant and Xsupplicant must be
 816 configured with the network security policy. See Xsupplicant documents
 817 for information about its configuration. Please also note, that a new
 818 command line option -W (enable WPA) must be used when starting
 819 xsupplicant.
 820
 821 Example configuration for xsupplicant:
 822
 823 network_list = all
 824 default_netname = jkm
 825
 826 jkm
 827 {
 828         type = wireless
 829         allow_types = eap_peap
 830         identity = <BEGIN_ID>jkm<END_ID>
 831         eap-peap {
 832                 random_file = /dev/urandom
 833                 root_cert = /home/jkm/CA.pem
 834                 chunk_size = 1398
 835                 allow_types = eap_mschapv2
 836                 eap-mschapv2 {
 837                         username = <BEGIN_UNAME>jkm<END_UNAME>
 838                         password = <BEGIN_PASS>jkm<END_PASS>
 839                 }
 840         }
 841 }
 842
 843
 844 Example configuration for wpa_supplicant:
 845
 846 network={
 847         ssid="jkm"
 848         key_mgmt=WPA-EAP
 849 }
 850
 851
 852 Both wpa_supplicant and xsupplicant need to be started. Please remember
 853 to add '-W' option for xsupplicant in order to provide keying material
 854 for wpa_supplicant and '-e' option for wpa_supplicant to disable internal
 855 IEEE 802.1X implementation.
 856
 857 wpa_supplicant -iwlan0 -cwpa_supplicant.conf -e
 858 xsupplicant -iwlan0 -cxsupplicant.conf -W