git.maemo.org Git - wpasupplicant/blob - www/wpa_supplicant/index.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3   <head>
   4     <title>Linux WPA Supplicant (IEEE 802.1X, WPA, WPA2, RSN, IEEE 802.11i)</title>
   5     <meta name="description" content="WPA Supplicant for Linux, BSD, and Windows (IEEE 802.1X, WPA, WPA2, RSN, IEEE 802.11i)">
   6     <meta name="keywords" content="WPA, WPA2, IEEE 802.11i, IEEE 802.1X, WPA Supplicant, wpa_supplicant, TKIP, CCMP, EAP-PEAP, EAP-TLS, EAP-TTLS, EAP-SIM, EAP-AKA, EAP-PSK, EAP-GTC, EAP-MSCHAPv2, EAP-MD5, EAP-FAST, EAP-PAX, EAP-IKEv2IEEE 802.1X Supplicant, IEEE 802.1aa, EAPOL, RSN, pre-authentication, PMKSA caching, BSD WPA Supplicant, FreeBSD WPA Supplicant, wireless, WinXP WPA Supplicant, EAP-TNC, TNCC, IF-IMC, IF-TNCCS">
   7     <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   8   </head>
   9
  10   <body>
  11     <h2>Linux WPA/WPA2/IEEE 802.1X Supplicant</h2>
  12
  13 <p>wpa_supplicant is a WPA Supplicant for Linux, BSD, Mac OS X, and
  14 Windows with
  15 support for WPA and WPA2 (IEEE 802.11i / RSN). It is suitable for both
  16 desktop/laptop computers and embedded systems. Supplicant is the IEEE
  17 802.1X/WPA component that is used in the client stations. It
  18 implements key negotiation with a WPA Authenticator and it controls
  19 the roaming and IEEE 802.11 authentication/association of the wlan
  20 driver.</p>
  21
  22 <p>wpa_supplicant is designed to be a "daemon" program that runs in the
  23 background and acts as the backend component controlling the wireless
  24 connection. wpa_supplicant supports separate frontend programs and a
  25 text-based frontend (wpa_cli) and a GUI (wpa_gui) are included with
  26 wpa_supplicant.</p>
  27
  28 <p>wpa_supplicant uses a flexible build configuration that can be used
  29 to select which features are included. This allows minimal code size
  30 (from ca. 50 kB binary for WPA/WPA2-Personal and 130 kB binary for
  31 WPA/WPA2-Enterprise without debugging code to 450 kB with most
  32 features and full debugging support; these example sizes are from a
  33 build for x86 target).</p>
  34
  35
  36 <h4>Supported WPA/IEEE 802.11i features</h4>
  37
  38 <ul>
  39 <li>WPA-PSK ("WPA-Personal")</li>
  40 <li>WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")</li>
  41 <li>key management for CCMP, TKIP, WEP104, WEP40</li>
  42 <li>WPA and full IEEE 802.11i/RSN/WPA2</li>
  43 <li>RSN: PMKSA caching, pre-authentication</li>
  44 </ul>
  45
  46 <h4>Supported EAP methods (IEEE 802.1X Supplicant)</h4>
  47
  48 <ul>
  49 <li>EAP-TLS</li>
  50 <li>EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)</li>
  51 <li>EAP-PEAP/TLS (both PEAPv0 and PEAPv1)</li>
  52 <li>EAP-PEAP/GTC (both PEAPv0 and PEAPv1)</li>
  53 <li>EAP-PEAP/OTP (both PEAPv0 and PEAPv1)</li>
  54 <li>EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)</li>
  55 <li>EAP-TTLS/EAP-MD5-Challenge</li>
  56 <li>EAP-TTLS/EAP-GTC</li>
  57 <li>EAP-TTLS/EAP-OTP</li>
  58 <li>EAP-TTLS/EAP-MSCHAPv2</li>
  59 <li>EAP-TTLS/EAP-TLS</li>
  60 <li>EAP-TTLS/MSCHAPv2</li>
  61 <li>EAP-TTLS/MSCHAP</li>
  62 <li>EAP-TTLS/PAP</li>
  63 <li>EAP-TTLS/CHAP</li>
  64 <li>EAP-SIM</li>
  65 <li>EAP-AKA</li>
  66 <li>EAP-AKA'</li>
  67 <li>EAP-PSK</li>
  68 <li>EAP-FAST</li>
  69 <li>EAP-PAX</li>
  70 <li>EAP-SAKE</li>
  71 <li>EAP-IKEv2</li>
  72 <li>EAP-GPSK (experimental)</li>
  73 <li>LEAP (note: requires special support from the driver)</li>
  74 </ul>
  75
  76 <p>Following methods are also supported, but since they do not generate keying
  77 material, they cannot be used with WPA or IEEE 802.1X WEP keying.</p>
  78
  79 <ul>
  80 <li>EAP-MD5-Challenge</li>
  81 <li>EAP-MSCHAPv2</li>
  82 <li>EAP-GTC</li>
  83 <li>EAP-OTP</li>
  84 <li>EAP-TNC (Trusted Network Connect; TNCC, IF-IMC, IF-T, IF-TNCCS)</li>
  85 </ul>
  86
  87 <p>More information about EAP methods and interoperability testing is
  88 available in <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/eap_testing.txt">eap_testing.txt</a>.</p>
  89
  90
  91 <h4>Supported TLS/crypto libraries</h4>
  92
  93 <ul>
  94 <li>OpenSSL (default)</li>
  95 <li>GnuTLS</li>
  96 </ul>
  97
  98 <h4>Internal TLS/crypto implementation (optional)</h4>
  99
 100 <ul>
 101 <li>can be used in place of an external TLS/crypto library</li>
 102 <li>TLSv1</li>
 103 <li>X.509 certificate processing</li>
 104 <li>PKCS #1</li>
 105 <li>ASN.1</li>
 106 <li>RSA</li>
 107 <li>bignum</li>
 108 <li>minimal size (ca. 50 kB binary, parts of which are already needed for WPA;
 109   TLSv1/X.509/ASN.1/RSA/bignum parts are about 25 kB on x86)</li>
 110 </ul>
 111
 112 <h4>Supported wireless cards/drivers</h4>
 113
 114 <ul>
 115 <li>Linux drivers that support Linux Wireless Extensions v19 or newer with
 116 WPA/WPA2 extensions</li>
 117 <li><a href="http://hostap.epitest.fi/">Host AP driver for Prism2/2.5/3</a> (WPA and WPA2)</li>
 118 <li><a href="http://www.linuxant.com/driverloader/">Linuxant DriverLoader</a> with Windows NDIS driver supporting WPA/WPA2</li>
 119 <li><a href="http://www.agere.com/support/drivers/">Agere Systems Inc. Linux Driver</a> (Hermes-I/Hermes-II chipset) (WPA, but not WPA2)</li>
 120 <li><a href="http://sourceforge.net/projects/madwifi/">madwifi (Atheros ar521x)</a></li>
 121 <li><a href="http://atmelwlandriver.sourceforge.net/">ATMEL AT76C5XXx</a></li>
 122 <li><a href="http://ndiswrapper.sourceforge.net/">Linux ndiswrapper</a></li>
 123 <li>Broadcom wl.o driver</li>
 124 <li><a href="http://sourceforge.net/projects/ipw2100/">Intel ipw2100</a></li>
 125 <li><a href="http://sourceforge.net/projects/ipw2200/">Intel ipw2200</a></li>
 126 <li>Wired Ethernet drivers</li>
 127 <li>BSD net80211 layer (e.g., Atheros driver) (FreeBSD 6-CURRENT and NetBSD current)</li>
 128 <li>Windows NDIS drivers (Windows; at least XP and 2000, others not tested)</li>
 129 </ul>
 130
 131 <p>wpa_supplicant was designed to be portable for different drivers and
 132 operating systems. Hopefully, support for more wlan cards and OSes will be
 133 added in the future. See <a href="devel/">developers' documentation</a>
 134 for more information about the design of wpa_supplicant and porting to
 135 other drivers.</p>
 136
 137 <h3><a name="download">Download</a></h3>
 138
 139 <p>
 140 <b>wpa_supplicant</b><br>
 141 Copyright (c) 2003-2008, Jouni Malinen &lt;j@w1.fi&gt;
 142 and contributors.
 143 </p>
 144
 145 <p>
 146 This program is free software; you can redistribute it and/or modify
 147 it under the terms of the GNU General Public License version 2 as
 148 published by the Free Software Foundation. See
 149 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=COPYING">COPYING</a>
 150 for more details.
 151 </p>
 152
 153 <p>Alternatively, this software may be distributed, used, and modified
 154 under the terms of BSD license. See <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/README">README</a>
 155 for more details.</p>
 156
 157 <p>
 158 <b>Please see
 159 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/README">README</a>
 160 for the current documentation.</b><br>
 161 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/README-Windows.txt">README-Windows.txt</a>
 162 has some more information about the Windows port of wpa_supplicant.</p>
 163
 164
 165 <ul>
 166 <li><a href="../releases.html">Release graph</a></li>
 167 <li>Latest stable release:
 168 <ul>
 169 <li><a href="../releases/wpa_supplicant-0.5.11.tar.gz">wpa_supplicant-0.5.11.tar.gz</a></li>
 170 <li><a href="../releases/wpa_supplicant-windows-bin-0.5.11.zip">wpa_supplicant-windows-bin-0.5.11.zip</a> (binaries for Windows)</li>
 171 </ul>
 172 <li>Older stable release:
 173 <ul>
 174 <li><a href="../releases/wpa_supplicant-0.4.11.tar.gz">wpa_supplicant-0.4.11.tar.gz</a> (source code for all versions)</li>
 175 <li><a href="../releases/wpa_supplicant-windows-bin-0.4.11.zip">wpa_supplicant-windows-bin-0.4.11.zip</a> (binaries for Windows)</li>
 176 </ul>
 177 <li>Older stable release:
 178 <ul>
 179 <li><a href="../releases/wpa_supplicant-0.3.11.tar.gz">wpa_supplicant-0.3.11.tar.gz</a> (source code for all versions)</li>
 180 <li><a href="../releases/wpa_supplicant-windows-bin-0.3.11.zip">wpa_supplicant-windows-bin-0.3.11.zip</a> (binaries for Windows)</li>
 181 </ul>
 182 <li>Obsolete stable release<BR>
 183 (note: 0.2.x branch is not supported anymore - please upgrade to 0.4.x or 0.5.x):
 184 <ul>
 185 <li><a href="../releases/wpa_supplicant-0.2.8.tar.gz">wpa_supplicant-0.2.8.tar.gz</a></li>
 186 </ul>
 187 <li>Latest development release:
 188 <ul>
 189 <li><a href="../releases/wpa_supplicant-0.6.6.tar.gz">wpa_supplicant-0.6.6.tar.gz</a> (source code for all versions)</li>
 190 <li><a href="../releases/wpa_supplicant-windows-bin-0.6.6.zip">wpa_supplicant-windows-bin-0.6.6.zip</a> (binaries for Windows)</li>
 191 <li><a href="qt4/wpa_gui-qt433-windows-dll.zip">wpa_gui-qt433-windows-dll.zip</a> (Qt4 libraries from wpa_gui/Windows)</li>
 192 </ul>
 193 <li>ChangeLog:
 194 <ul>
 195 <li><a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/ChangeLog">development branch</a></li>
 196 <li><a href="/cgi-bin/viewcvs.cgi/*checkout*/hostap/wpa_supplicant/ChangeLog?rev=stable&amp;content-type=text/plain">stable branch</a>
 197 </ul>
 198 <li><a href="../releases/">Old releases</a></li>
 199 <li><a href="http://lists.shmoo.com/mailman/listinfo/hostap">Mailing list</a></li>
 200 <li><a href="http://lists.shmoo.com/pipermail/hostap/">New mailing list archives</a></li>
 201 <li><a href="/gitweb/gitweb.cgi">Web interface to GIT repository (0.6.x and newer)</a></li>
 202 <li><a href="/cgi-bin/viewcvs.cgi/hostap/">Web interface to CVS repository (0.5.x and older)</a></li>
 203 <li><a href="../releases/snapshots/">Snapshot releases from all active branches</a>
 204 <li><a href="../cvs.html">GIT and read-only anonymous CVS access (pserver)</a></li>
 205 <li><a href="../bugz/">Bug and feature request tracking</a></li>
 206 <li><a href="devel/">Developers' documentation for wpa_supplicant 0.5.x</a></li>
 207 <li><a href="devel-0.4/">Developers' documentation for wpa_supplicant 0.4.x</a></li>
 208 <li><a href="wpa_gui.html">wpa_gui screenshots</a></li>
 209 </ul>
 210
 211 <h3>WPA</h3>
 212
 213 <p>The original security mechanism of IEEE 802.11 standard was not
 214 designed to be strong and has proven to be insufficient for most
 215 networks that require some kind of security. Task group I (Security)
 216 of <a href="http://www.ieee802.org/11/">IEEE 802.11 working group</a>
 217 has worked to address the flaws of the base standard and in
 218 practice completed its work in May 2004. The IEEE 802.11i amendment to
 219 the IEEE 802.11 standard was approved in June 2004 and published in
 220 July 2004.</p>
 221
 222 <p><a href="http://www.wi-fi.org/">Wi-Fi Alliance</a> used a draft
 223 version of the IEEE 802.11i work (draft 3.0) to define a subset of the
 224 security enhancements that can be implemented with existing wlan
 225 hardware. This is called Wi-Fi Protected Access (WPA). This has
 226 now become a mandatory component of interoperability testing and
 227 certification done by Wi-Fi Alliance. Wi-Fi has
 228 <a href="http://www.wi-fi.org/OpenSection/protected_access.asp">information
 229 about WPA</a> at its web site.</p>
 230
 231 <p>IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
 232 for protecting wireless networks. WEP uses RC4 with 40-bit keys,
 233 24-bit initialization vector (IV), and CRC32 to protect against packet
 234 forgery. All these choices have proven to be insufficient: key space is
 235 too small against current attacks, RC4 key scheduling is insufficient
 236 (beginning of the pseudorandom stream should be skipped), IV space is
 237 too small and IV reuse makes attacks easier, there is no replay
 238 protection, and non-keyed authentication does not protect against bit
 239 flipping packet data.</p>
 240
 241 <p>WPA is an intermediate solution for the security issues. It uses
 242 Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a
 243 compromise on strong security and possibility to use existing
 244 hardware. It still uses RC4 for the encryption like WEP, but with
 245 per-packet RC4 keys. In addition, it implements replay protection,
 246 keyed packet authentication mechanism (Michael MIC).</p>
 247
 248 <p>Keys can be managed using two different mechanisms. WPA can either use
 249 an external authentication server (e.g., RADIUS) and EAP just like
 250 IEEE 802.1X is using or pre-shared keys without need for additional
 251 servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
 252 respectively. Both mechanisms will generate a master session key for
 253 the Authenticator (AP) and Supplicant (client station).</p>
 254
 255 <p>WPA implements a new key handshake (4-Way Handshake and Group Key
 256 Handshake) for generating and exchanging data encryption keys between
 257 the Authenticator and Supplicant. This handshake is also used to
 258 verify that both Authenticator and Supplicant know the master session
 259 key. These handshakes are identical regardless of the selected key
 260 management mechanism (only the method for generating master session
 261 key changes).</p>
 262
 263
 264 <h3>IEEE 802.11i / RSN / WPA2</h3>
 265
 266 <p>The design for parts of IEEE 802.11i that were not included in WPA
 267 has finished (May 2004) and this amendment to IEEE 802.11 was approved
 268 in June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
 269 version of WPA called WPA2. This included, e.g., support for more
 270 robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
 271 to replace TKIP, optimizations for handoff (reduced number of messages
 272 in initial key handshake, pre-authentication, and PMKSA caching).</p>
 273
 274 <h3>Using wpa_supplicant</h3>
 275
 276 <p>Following steps are used when associating with an AP using WPA:<p>
 277 <ul>
 278 <li>wpa_supplicant requests the kernel driver to scan neighboring BSSes</li>
 279 <li>wpa_supplicant selects a BSS based on its configuration</li>
 280 <li>wpa_supplicant requests the kernel driver to associate with the chosen
 281   BSS</li>
 282 <li>if WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP
 283   authentication with the authentication server (proxied by the
 284   Authenticator in the AP)</li>
 285 <li>If WPA-EAP: master key is received from the IEEE 802.1X Supplicant</li>
 286 <li>If WPA-PSK: wpa_supplicant uses PSK as the master session key</li>
 287 <li>wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake
 288   with the Authenticator (AP). WPA2 has integrated the initial Group Key
 289   Handshake into the 4-Way Handshake.</li>
 290 <li>wpa_supplicant configures encryption keys for unicast and broadcast</li>
 291 <li>normal data packets can be transmitted and received</li>
 292 </ul>
 293
 294 <h4>Configuration file</h4>
 295
 296 <p>wpa_supplicant is configured using a text file that lists all accepted
 297 networks and security policies, including pre-shared keys. See
 298 example configuration file,
 299 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/wpa_supplicant.conf">wpa_supplicant.conf</a>,
 300 for detailed information about the configuration format and supported
 301 fields. In addition, simpler example configurations are available for
 302 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/plaintext.conf">plaintext</a>,
 303 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/wep.conf">static WEP</a>,
 304 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/ieee8021x.conf">IEEE 802.1X with dynamic WEP (EAP-PEAP/MSCHAPv2)</a>,
 305 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/wpa-psk-tkip.conf">WPA-PSK/TKIP</a>, and
 306 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/wpa2-eap-ccmp.conf">WPA2-EAP/CCMP (EAP-TLS)</a>.
 307 In addition, wpa_supplicant can use OpenSSL engine to avoid need for
 308 exposing private keys in the file system. This can be used for EAP-TLS
 309 authentication with smartcards and TPM tokens.
 310 <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/openCryptoki.conf">Example configuration for using openCryptoki</a>
 311 shows an example network block and related parameters for EAP-TLS
 312 authentication using PKCS#11 TPM token.
 313 </p>
 314
 315 <h3>Feedback, comments, mailing list</h3>
 316
 317 <p>
 318 Any comments, reports on success/failure, ideas for further
 319 improvement, feature requests, etc. are welcome at j@w1.fi.
 320 Please note, that I often receive more email than I have time to answer.
 321 Unfortunately, some messages may not get a reply, but I'll try to go
 322 through my mail whenever time permits.
 323 </p>
 324
 325 <p>Host AP mailing list can also be used for topics related to
 326 wpa_supplicant. Since this list has a broader audience, your likelyhood
 327 of getting responses is higher. This list is recommended for general
 328 questions about wpa_supplicant and its development. In addition, I
 329 will send release notes to it whenever a new version is available.
 330 </p>
 331
 332 <p>
 333 The mailing list information and web archive is at <a
 334 href="http://lists.shmoo.com/mailman/listinfo/hostap">http://lists.shmoo.com/mailman/listinfo/hostap</a>.
 335 Messages to hostap@shmoo.com will be delivered to the
 336 subscribers. Please note, that due to large number of spam and virus
 337 messages sent to the list address, the list is configured to accept
 338 messages only from subscribed addresses. Messages from unsubscribed addresses
 339 may be accepted manually, but their delivery will be delayed.
 340 </p>
 341
 342 <p>
 343 If you want to make sure your bug report of feature request does not
 344 get lost, please report it through the bug tracking system as
 345 <a href="../bugz/enter_bug.cgi">a new
 346 bug/feature request</a>.
 347 </p>
 348
 349 <hr>
 350
 351 The server and hosting for hostap.epitest.fi is kindly provided by
 352 Internet Systems Consortium (ISC).
 353 <a href="http://www.isc.org/"><img src="../isc.png" border="0"></a>
 354
 355     <hr>
 356     <div>
 357     <address><a href="mailto:j@w1.fi">Jouni Malinen</a></address>
 358 <!-- Created: Sat May 22 21:41:58 PDT 2004 -->
 359 <!-- hhmts start -->
 360 Last modified: Sun Dec  7 19:24:16 EET 2008
 361 <!-- hhmts end -->
 362     </div>
 363   </body>
 364 </html>