aboutsummaryrefslogtreecommitdiffstats
path: root/www/wpa_supplicant/index.html
blob: 2b086936caa9e485fc2b03e304ad091d3389489c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>Linux WPA Supplicant (IEEE 802.1X, WPA, WPA2, RSN, IEEE 802.11i)</title>
    <meta name="description" content="WPA Supplicant for Linux, BSD, and Windows (IEEE 802.1X, WPA, WPA2, RSN, IEEE 802.11i)">
    <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">
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  </head>

  <body>
    <h2>Linux WPA/WPA2/IEEE 802.1X Supplicant</h2>

<p>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.</p>

<p>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.</p>

<p>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).</p>


<h4>Supported WPA/IEEE 802.11i features</h4>

<ul>
<li>WPA-PSK ("WPA-Personal")</li>
<li>WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")</li>
<li>key management for CCMP, TKIP, WEP104, WEP40</li>
<li>WPA and full IEEE 802.11i/RSN/WPA2</li>
<li>RSN: PMKSA caching, pre-authentication</li>
</ul>

<h4>Supported EAP methods (IEEE 802.1X Supplicant)</h4>

<ul>
<li>EAP-TLS</li>
<li>EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)</li>
<li>EAP-PEAP/TLS (both PEAPv0 and PEAPv1)</li>
<li>EAP-PEAP/GTC (both PEAPv0 and PEAPv1)</li>
<li>EAP-PEAP/OTP (both PEAPv0 and PEAPv1)</li>
<li>EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)</li>
<li>EAP-TTLS/EAP-MD5-Challenge</li>
<li>EAP-TTLS/EAP-GTC</li>
<li>EAP-TTLS/EAP-OTP</li>
<li>EAP-TTLS/EAP-MSCHAPv2</li>
<li>EAP-TTLS/EAP-TLS</li>
<li>EAP-TTLS/MSCHAPv2</li>
<li>EAP-TTLS/MSCHAP</li>
<li>EAP-TTLS/PAP</li>
<li>EAP-TTLS/CHAP</li>
<li>EAP-SIM</li>
<li>EAP-AKA</li>
<li>EAP-PSK</li>
<li>EAP-FAST</li>
<li>EAP-PAX</li>
<li>EAP-SAKE</li>
<li>EAP-IKEv2</li>
<li>EAP-GPSK (experimental)</li>
<li>LEAP (note: requires special support from the driver)</li>
</ul>

<p>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.</p>

<ul>
<li>EAP-MD5-Challenge</li>
<li>EAP-MSCHAPv2</li>
<li>EAP-GTC</li>
<li>EAP-OTP</li>
<li>EAP-TNC (Trusted Network Connect; TNCC, IF-IMC, IF-T, IF-TNCCS)</li>
</ul>

<p>More information about EAP methods and interoperability testing is
available in <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/eap_testing.txt">eap_testing.txt</a>.</p>


<h4>Supported TLS/crypto libraries</h4>

<ul>
<li>OpenSSL (default)</li>
<li>GnuTLS</li>
</ul>

<h4>Internal TLS/crypto implementation (optional)</h4>

<ul>
<li>can be used in place of an external TLS/crypto library</li>
<li>TLSv1</li>
<li>X.509 certificate processing</li>
<li>PKCS #1</li>
<li>ASN.1</li>
<li>RSA</li>
<li>bignum</li>
<li>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)</li>
</ul>

<h4>Supported wireless cards/drivers</h4>

<ul>
<li>Linux drivers that support Linux Wireless Extensions v19 or newer with
WPA/WPA2 extensions</li>
<li><a href="http://hostap.epitest.fi/">Host AP driver for Prism2/2.5/3</a> (WPA and WPA2)</li>
<li><a href="http://www.linuxant.com/driverloader/">Linuxant DriverLoader</a> with Windows NDIS driver supporting WPA/WPA2</li>
<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>
<li><a href="http://sourceforge.net/projects/madwifi/">madwifi (Atheros ar521x)</a></li>
<li><a href="http://atmelwlandriver.sourceforge.net/">ATMEL AT76C5XXx</a></li>
<li><a href="http://ndiswrapper.sourceforge.net/">Linux ndiswrapper</a></li>
<li>Broadcom wl.o driver</li>
<li><a href="http://sourceforge.net/projects/ipw2100/">Intel ipw2100</a></li>
<li><a href="http://sourceforge.net/projects/ipw2200/">Intel ipw2200</a></li>
<li>Wired Ethernet drivers</li>
<li>BSD net80211 layer (e.g., Atheros driver) (FreeBSD 6-CURRENT and NetBSD current)</li>
<li>Windows NDIS drivers (Windows; at least XP and 2000, others not tested)</li>
</ul>

<p>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 <a href="devel/">developers' documentation</a>
for more information about the design of wpa_supplicant and porting to
other drivers.</p>

<h3><a name="download">Download</a></h3>

<p>
<b>wpa_supplicant</b><br>
Copyright (c) 2003-2008, Jouni Malinen &lt;j@w1.fi&gt;
and contributors.
</p>

<p>
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
<a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=COPYING">COPYING</a>
for more details.
</p>

<p>Alternatively, this software may be distributed, used, and modified
under the terms of BSD license. See <a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/README">README</a>
for more details.</p>

<p>
<b>Please see
<a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/README">README</a>
for the current documentation.</b><br>
<a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/README-Windows.txt">README-Windows.txt</a>
has some more information about the Windows port of wpa_supplicant.</p>


<ul>
<li><a href="../releases.html">Release graph</a></li>
<li>Latest stable release:
<ul>
<li><a href="../releases/wpa_supplicant-0.5.10.tar.gz">wpa_supplicant-0.5.10.tar.gz</a></li>
<li><a href="../releases/wpa_supplicant-windows-bin-0.5.10.zip">wpa_supplicant-windows-bin-0.5.10.zip</a> (binaries for Windows)</li>
</ul>
<li>Older stable release:
<ul>
<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>
<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>
</ul>
<li>Older stable release:
<ul>
<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>
<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>
</ul>
<li>Obsolete stable release<BR>
(note: 0.2.x branch is not supported anymore - please upgrade to 0.4.x or 0.5.x):
<ul>
<li><a href="../releases/wpa_supplicant-0.2.8.tar.gz">wpa_supplicant-0.2.8.tar.gz</a></li>
</ul>
<li>Latest development release:
<ul>
<li><a href="../releases/wpa_supplicant-0.6.5.tar.gz">wpa_supplicant-0.6.5.tar.gz</a> (source code for all versions)</li>
<li><a href="../releases/wpa_supplicant-windows-bin-0.6.5.zip">wpa_supplicant-windows-bin-0.6.5.zip</a> (binaries for Windows)</li>
<li><a href="qt4/wpa_gui-qt433-windows-dll.zip">wpa_gui-qt433-windows-dll.zip</a> (Qt4 libraries from wpa_gui/Windows)</li>
</ul>
<li>ChangeLog:
<ul>
<li><a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/ChangeLog">development branch</a></li>
<li><a href="/cgi-bin/viewcvs.cgi/*checkout*/hostap/wpa_supplicant/ChangeLog?rev=stable&amp;content-type=text/plain">stable branch</a>
</ul>
<li><a href="../releases/">Old releases</a></li>
<li><a href="http://lists.shmoo.com/mailman/listinfo/hostap">Mailing list</a></li>
<li><a href="http://lists.shmoo.com/pipermail/hostap/">New mailing list archives</a></li>
<li><a href="/gitweb/gitweb.cgi">Web interface to GIT repository (0.6.x and newer)</a></li>
<li><a href="/cgi-bin/viewcvs.cgi/hostap/">Web interface to CVS repository (0.5.x and older)</a></li>
<li><a href="../releases/snapshots/">Snapshot releases from all active branches</a>
<li><a href="../cvs.html">GIT and read-only anonymous CVS access (pserver)</a></li>
<li><a href="../bugz/">Bug and feature request tracking</a></li>
<li><a href="devel/">Developers' documentation for wpa_supplicant 0.5.x</a></li>
<li><a href="devel-0.4/">Developers' documentation for wpa_supplicant 0.4.x</a></li>
<li><a href="wpa_gui.html">wpa_gui screenshots</a></li>
</ul>

<h3>WPA</h3>

<p>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 <a href="http://www.ieee802.org/11/">IEEE 802.11 working group</a>
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.</p>

<p><a href="http://www.wi-fi.org/">Wi-Fi Alliance</a> 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
<a href="http://www.wi-fi.org/OpenSection/protected_access.asp">information
about WPA</a> at its web site.</p>

<p>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.</p>

<p>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).</p>

<p>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).</p>

<p>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).</p>


<h3>IEEE 802.11i / RSN / WPA2</h3>

<p>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).</p>

<h3>Using wpa_supplicant</h3>

<p>Following steps are used when associating with an AP using WPA:<p>
<ul>
<li>wpa_supplicant requests the kernel driver to scan neighboring BSSes</li>
<li>wpa_supplicant selects a BSS based on its configuration</li>
<li>wpa_supplicant requests the kernel driver to associate with the chosen
  BSS</li>
<li>if WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP
  authentication with the authentication server (proxied by the
  Authenticator in the AP)</li>
<li>If WPA-EAP: master key is received from the IEEE 802.1X Supplicant</li>
<li>If WPA-PSK: wpa_supplicant uses PSK as the master session key</li>
<li>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.</li>
<li>wpa_supplicant configures encryption keys for unicast and broadcast</li>
<li>normal data packets can be transmitted and received</li>
</ul>

<h4>Configuration file</h4>

<p>wpa_supplicant is configured using a text file that lists all accepted
networks and security policies, including pre-shared keys. See
example configuration file,
<a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/wpa_supplicant.conf">wpa_supplicant.conf</a>,
for detailed information about the configuration format and supported
fields. In addition, simpler example configurations are available for
<a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/plaintext.conf">plaintext</a>,
<a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/wep.conf">static WEP</a>,
<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>,
<a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/wpa-psk-tkip.conf">WPA-PSK/TKIP</a>, and
<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>.
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.
<a href="/gitweb/gitweb.cgi?p=hostap.git;a=blob_plain;f=wpa_supplicant/examples/openCryptoki.conf">Example configuration for using openCryptoki</a>
shows an example network block and related parameters for EAP-TLS
authentication using PKCS#11 TPM token.
</p>

<h3>Feedback, comments, mailing list</h3>

<p>
Any comments, reports on success/failure, ideas for further
improvement, 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 go
through my mail whenever time permits.
</p>

<p>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.
</p>

<p>
The mailing list information and web archive is at <a
href="http://lists.shmoo.com/mailman/listinfo/hostap">http://lists.shmoo.com/mailman/listinfo/hostap</a>.
Messages to hostap@shmoo.com 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.
</p>

<p>
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 href="../bugz/enter_bug.cgi">a new
bug/feature request</a>.
</p>

<hr>

The server and hosting for hostap.epitest.fi is kindly provided by
Internet Systems Consortium (ISC).
<a href="http://www.isc.org/"><img src="../isc.png" border="0"></a>

    <hr>
    <div>
    <address><a href="mailto:j@w1.fi">Jouni Malinen</a></address>
<!-- Created: Sat May 22 21:41:58 PDT 2004 -->
<!-- hhmts start -->
Last modified: Sat Nov  1 17:11:27 EET 2008
<!-- hhmts end -->
    </div>
  </body>
</html>