]>
Commit | Line | Data |
---|---|---|
6fc6879b JM |
1 | wpa_supplicant for Windows |
2 | ========================== | |
3 | ||
6f78f2fb | 4 | Copyright (c) 2003-2009, Jouni Malinen <j@w1.fi> and contributors |
6fc6879b JM |
5 | All Rights Reserved. |
6 | ||
7 | This program is dual-licensed under both the GPL version 2 and BSD | |
8 | license. Either license may be used at your option. | |
9 | ||
10 | This product includes software developed by the OpenSSL Project | |
2bf6a167 JM |
11 | for use in the OpenSSL Toolkit (http://www.openssl.org/). This |
12 | product includes cryptographic software written by Eric Young | |
13 | (eay@cryptsoft.com). | |
6fc6879b JM |
14 | |
15 | ||
16 | wpa_supplicant has support for being used as a WPA/WPA2/IEEE 802.1X | |
17 | Supplicant on Windows. The current port requires that WinPcap | |
18 | (http://winpcap.polito.it/) is installed for accessing packets and the | |
19 | driver interface. Both release versions 3.0 and 3.1 are supported. | |
20 | ||
21 | The current port is still somewhat experimental. It has been tested | |
22 | mainly on Windows XP (SP2) with limited set of NDIS drivers. In | |
23 | addition, the current version has been reported to work with Windows | |
24 | 2000. | |
25 | ||
26 | All security modes have been verified to work (at least complete | |
27 | authentication and successfully ping a wired host): | |
28 | - plaintext | |
29 | - static WEP / open system authentication | |
30 | - static WEP / shared key authentication | |
31 | - IEEE 802.1X with dynamic WEP keys | |
32 | - WPA-PSK, TKIP, CCMP, TKIP+CCMP | |
33 | - WPA-EAP, TKIP, CCMP, TKIP+CCMP | |
34 | - WPA2-PSK, TKIP, CCMP, TKIP+CCMP | |
35 | - WPA2-EAP, TKIP, CCMP, TKIP+CCMP | |
36 | ||
37 | ||
38 | Binary version | |
39 | -------------- | |
40 | ||
41 | Compiled binary version of the wpa_supplicant and additional tools is | |
42 | available from http://w1.fi/wpa_supplicant/. These binaries can be | |
43 | used after installing WinPcap. | |
44 | ||
45 | wpa_gui uses Qt 4 framework and may need additional dynamic libraries | |
46 | (DLLs). These libraries are available from | |
47 | http://w1.fi/wpa_supplicant/qt4/wpa_gui-qt433-windows-dll.zip | |
48 | You can copy the DLL files from this ZIP package into the same directory | |
49 | with wpa_gui.exe to allow wpa_gui to be started. | |
50 | ||
51 | ||
52 | Building wpa_supplicant with mingw | |
53 | ---------------------------------- | |
54 | ||
55 | The default build setup for wpa_supplicant is to use MinGW and | |
56 | cross-compiling from Linux to MinGW/Windows. It should also be | |
57 | possible to build this under Windows using the MinGW tools, but that | |
58 | is not tested nor supported and is likely to require some changes to | |
59 | the Makefile unless cygwin is used. | |
60 | ||
61 | ||
62 | Building wpa_supplicant with MSVC | |
63 | --------------------------------- | |
64 | ||
65 | wpa_supplicant can be built with Microsoft Visual C++ compiler. This | |
66 | has been tested with Microsoft Visual C++ Toolkit 2003 and Visual | |
67 | Studio 2005 using the included nmake.mak as a Makefile for nmake. IDE | |
68 | can also be used by creating a project that includes the files and | |
69 | defines mentioned in nmake.mak. Example VS2005 solution and project | |
70 | files are included in vs2005 subdirectory. This can be used as a | |
8caa12b4 JM |
71 | starting point for building the programs with VS2005 IDE. Visual Studio |
72 | 2008 Express Edition is also able to use these project files. | |
6fc6879b JM |
73 | |
74 | WinPcap development package is needed for the build and this can be | |
8caa12b4 | 75 | downloaded from http://www.winpcap.org/install/bin/WpdPack_4_0_2.zip. The |
6fc6879b JM |
76 | default nmake.mak expects this to be unpacked into C:\dev\WpdPack so |
77 | that Include and Lib directories are in this directory. The files can be | |
78 | stored elsewhere as long as the WINPCAPDIR in nmake.mak is updated to | |
79 | match with the selected directory. In case a project file in the IDE is | |
80 | used, these Include and Lib directories need to be added to project | |
81 | properties as additional include/library directories. | |
82 | ||
83 | OpenSSL source package can be downloaded from | |
8caa12b4 | 84 | http://www.openssl.org/source/openssl-0.9.8i.tar.gz and built and |
6fc6879b JM |
85 | installed following instructions in INSTALL.W32. Note that if EAP-FAST |
86 | support will be included in the wpa_supplicant, OpenSSL needs to be | |
8caa12b4 | 87 | patched to# support it openssl-0.9.8i-tls-extensions.patch. The example |
6fc6879b JM |
88 | nmake.mak file expects OpenSSL to be installed into C:\dev\openssl, but |
89 | this directory can be modified by changing OPENSSLDIR variable in | |
90 | nmake.mak. | |
91 | ||
92 | If you do not need EAP-FAST support, you may also be able to use Win32 | |
93 | binary installation package of OpenSSL from | |
94 | http://www.slproweb.com/products/Win32OpenSSL.html instead of building | |
95 | the library yourself. In this case, you will need to copy Include and | |
96 | Lib directories in suitable directory, e.g., C:\dev\openssl for the | |
97 | default nmake.mak. Copy {Win32OpenSSLRoot}\include into | |
98 | C:\dev\openssl\include and make C:\dev\openssl\lib subdirectory with | |
99 | files from {Win32OpenSSLRoot}\VC (i.e., libeay*.lib and ssleay*.lib). | |
100 | This will end up using dynamically linked OpenSSL (i.e., .dll files are | |
101 | needed) for it. Alternative, you can copy files from | |
102 | {Win32OpenSSLRoot}\VC\static to create a static build (no OpenSSL .dll | |
103 | files needed). | |
104 | ||
105 | ||
106 | Building wpa_supplicant for cygwin | |
107 | ---------------------------------- | |
108 | ||
109 | wpa_supplicant can be built for cygwin by installing the needed | |
110 | development packages for cygwin. This includes things like compiler, | |
111 | make, openssl development package, etc. In addition, developer's pack | |
112 | for WinPcap (WPdpack.zip) from | |
113 | http://winpcap.polito.it/install/default.htm is needed. | |
114 | ||
115 | .config file should enable only one driver interface, | |
116 | CONFIG_DRIVER_NDIS. In addition, include directories may need to be | |
117 | added to match the system. An example configuration is available in | |
118 | defconfig. The library and include files for WinPcap will either need | |
119 | to be installed in compiler/linker default directories or their | |
120 | location will need to be adding to .config when building | |
121 | wpa_supplicant. | |
122 | ||
123 | Othen than this, the build should be more or less identical to Linux | |
124 | version, i.e., just run make after having created .config file. An | |
125 | additional tool, win_if_list.exe, can be built by running "make | |
126 | win_if_list". | |
127 | ||
128 | ||
129 | Building wpa_gui | |
130 | ---------------- | |
131 | ||
132 | wpa_gui uses Qt application framework from Trolltech. It can be built | |
133 | with the open source version of Qt4 and MinGW. Following commands can | |
134 | be used to build the binary in the Qt 4 Command Prompt: | |
135 | ||
136 | # go to the root directory of wpa_supplicant source code | |
137 | cd wpa_gui-qt4 | |
138 | qmake -o Makefile wpa_gui.pro | |
139 | make | |
140 | # the wpa_gui.exe binary is created into 'release' subdirectory | |
141 | ||
142 | ||
143 | Using wpa_supplicant for Windows | |
144 | -------------------------------- | |
145 | ||
146 | wpa_supplicant, wpa_cli, and wpa_gui behave more or less identically to | |
147 | Linux version, so instructions in README and example wpa_supplicant.conf | |
148 | should be applicable for most parts. In addition, there is another | |
149 | version of wpa_supplicant, wpasvc.exe, which can be used as a Windows | |
150 | service and which reads its configuration from registry instead of | |
151 | text file. | |
152 | ||
153 | When using access points in "hidden SSID" mode, ap_scan=2 mode need to | |
154 | be used (see wpa_supplicant.conf for more information). | |
155 | ||
156 | Windows NDIS/WinPcap uses quite long interface names, so some care | |
157 | will be needed when starting wpa_supplicant. Alternatively, the | |
158 | adapter description can be used as the interface name which may be | |
159 | easier since it is usually in more human-readable | |
160 | format. win_if_list.exe can be used to find out the proper interface | |
161 | name. | |
162 | ||
163 | Example steps in starting up wpa_supplicant: | |
164 | ||
165 | # win_if_list.exe | |
166 | ifname: \Device\NPF_GenericNdisWanAdapter | |
167 | description: Generic NdisWan adapter | |
168 | ||
169 | ifname: \Device\NPF_{769E012B-FD17-4935-A5E3-8090C38E25D2} | |
170 | description: Atheros Wireless Network Adapter (Microsoft's Packet Scheduler) | |
171 | ||
172 | ifname: \Device\NPF_{732546E7-E26C-48E3-9871-7537B020A211} | |
173 | description: Intel 8255x-based Integrated Fast Ethernet (Microsoft's Packet Scheduler) | |
174 | ||
175 | ||
176 | Since the example configuration used Atheros WLAN card, the middle one | |
177 | is the correct interface in this case. The interface name for -i | |
178 | command line option is the full string following "ifname:" (the | |
179 | "\Device\NPF_" prefix can be removed). In other words, wpa_supplicant | |
180 | would be started with the following command: | |
181 | ||
182 | # wpa_supplicant.exe -i'{769E012B-FD17-4935-A5E3-8090C38E25D2}' -c wpa_supplicant.conf -d | |
183 | ||
184 | -d optional enables some more debugging (use -dd for even more, if | |
185 | needed). It can be left out if debugging information is not needed. | |
186 | ||
187 | With the alternative mechanism for selecting the interface, this | |
188 | command has identical results in this case: | |
189 | ||
190 | # wpa_supplicant.exe -iAtheros -c wpa_supplicant.conf -d | |
191 | ||
192 | ||
193 | Simple configuration example for WPA-PSK: | |
194 | ||
195 | #ap_scan=2 | |
196 | ctrl_interface= | |
197 | network={ | |
198 | ssid="test" | |
199 | key_mgmt=WPA-PSK | |
200 | proto=WPA | |
201 | pairwise=TKIP | |
202 | psk="secret passphrase" | |
203 | } | |
204 | ||
205 | (remove '#' from the comment out ap_scan line to enable mode in which | |
206 | wpa_supplicant tries to associate with the SSID without doing | |
207 | scanning; this allows APs with hidden SSIDs to be used) | |
208 | ||
209 | ||
210 | wpa_cli.exe and wpa_gui.exe can be used to interact with the | |
211 | wpa_supplicant.exe program in the same way as with Linux. Note that | |
212 | ctrl_interface is using UNIX domain sockets when built for cygwin, but | |
213 | the native build for Windows uses named pipes and the contents of the | |
214 | ctrl_interface configuration item is used to control access to the | |
215 | interface. Anyway, this variable has to be included in the configuration | |
216 | to enable the control interface. | |
217 | ||
218 | ||
219 | Example SDDL string formats: | |
220 | ||
221 | (local admins group has permission, but nobody else): | |
222 | ||
223 | ctrl_interface=SDDL=D:(A;;GA;;;BA) | |
224 | ||
225 | ("A" == "access allowed", "GA" == GENERIC_ALL == all permissions, and | |
226 | "BA" == "builtin administrators" == the local admins. The empty fields | |
227 | are for flags and object GUIDs, none of which should be required in this | |
228 | case.) | |
229 | ||
230 | (local admins and the local "power users" group have permissions, | |
231 | but nobody else): | |
232 | ||
233 | ctrl_interface=SDDL=D:(A;;GA;;;BA)(A;;GA;;;PU) | |
234 | ||
235 | (One ACCESS_ALLOWED ACE for GENERIC_ALL for builtin administrators, and | |
236 | one ACCESS_ALLOWED ACE for GENERIC_ALL for power users.) | |
237 | ||
238 | (close to wide open, but you have to be a valid user on | |
239 | the machine): | |
240 | ||
241 | ctrl_interface=SDDL=D:(A;;GA;;;AU) | |
242 | ||
243 | (One ACCESS_ALLOWED ACE for GENERIC_ALL for the "authenticated users" | |
244 | group.) | |
245 | ||
246 | This one would allow absolutely everyone (including anonymous | |
247 | users) -- this is *not* recommended, since named pipes can be attached | |
248 | to from anywhere on the network (i.e. there's no "this machine only" | |
249 | like there is with 127.0.0.1 sockets): | |
250 | ||
251 | ctrl_interface=SDDL=D:(A;;GA;;;BU)(A;;GA;;;AN) | |
252 | ||
253 | (BU == "builtin users", "AN" == "anonymous") | |
254 | ||
255 | See also [1] for the format of ACEs, and [2] for the possible strings | |
256 | that can be used for principal names. | |
257 | ||
258 | [1] | |
259 | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/ace_strings.asp | |
260 | [2] | |
261 | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/sid_strings.asp | |
262 | ||
263 | ||
264 | Starting wpa_supplicant as a Windows service (wpasvc.exe) | |
265 | --------------------------------------------------------- | |
266 | ||
267 | wpa_supplicant can be started as a Windows service by using wpasvc.exe | |
268 | program that is alternative build of wpa_supplicant.exe. Most of the | |
269 | core functionality of wpasvc.exe is identical to wpa_supplicant.exe, | |
270 | but it is using Windows registry for configuration information instead | |
271 | of a text file and command line parameters. In addition, it can be | |
272 | registered as a service that can be started automatically or manually | |
273 | like any other Windows service. | |
274 | ||
275 | The root of wpa_supplicant configuration in registry is | |
276 | HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant. This level includes global | |
277 | parameters and a 'interfaces' subkey with all the interface configuration | |
278 | (adapter to confname mapping). Each such mapping is a subkey that has | |
279 | 'adapter', 'config', and 'ctrl_interface' values. | |
280 | ||
281 | This program can be run either as a normal command line application, | |
282 | e.g., for debugging, with 'wpasvc.exe app' or as a Windows service. | |
283 | Service need to be registered with 'wpasvc.exe reg <full path to | |
284 | wpasvc.exe>'. Alternatively, 'wpasvc.exe reg' can be used to register | |
285 | the service with the current location of wpasvc.exe. After this, wpasvc | |
286 | can be started like any other Windows service (e.g., 'net start wpasvc') | |
287 | or it can be configured to start automatically through the Services tool | |
288 | in administrative tasks. The service can be unregistered with | |
289 | 'wpasvc.exe unreg'. | |
290 | ||
291 | If the service is set to start during system bootup to make the | |
292 | network connection available before any user has logged in, there may | |
293 | be a long (half a minute or so) delay in starting up wpa_supplicant | |
294 | due to WinPcap needing a driver called "Network Monitor Driver" which | |
295 | is started by default on demand. | |
296 | ||
297 | To speed up wpa_supplicant start during system bootup, "Network | |
298 | Monitor Driver" can be configured to be started sooner by setting its | |
299 | startup type to System instead of the default Demand. To do this, open | |
300 | up Device Manager, select Show Hidden Devices, expand the "Non | |
301 | Plug-and-Play devices" branch, double click "Network Monitor Driver", | |
302 | go to the Driver tab, and change the Demand setting to System instead. | |
303 | ||
304 | Configuration data is in HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs | |
305 | key. Each configuration profile has its own key under this. In terms of text | |
306 | files, each profile would map to a separate text file with possibly multiple | |
307 | networks. Under each profile, there is a networks key that lists all | |
308 | networks as a subkey. Each network has set of values in the same way as | |
309 | network block in the configuration file. In addition, blobs subkey has | |
310 | possible blobs as values. | |
311 | ||
312 | HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs\test\networks\0000 | |
313 | ssid="example" | |
314 | key_mgmt=WPA-PSK | |
315 | ||
316 | See win_example.reg for an example on how to setup wpasvc.exe | |
317 | parameters in registry. It can also be imported to registry as a | |
318 | starting point for the configuration. | |
319 | ||
320 | ||
321 | ||
322 | License information for third party software used in this product: | |
323 | ||
324 | OpenSSL License | |
325 | --------------- | |
326 | ||
327 | /* ==================================================================== | |
328 | * Copyright (c) 1998-2004 The OpenSSL Project. All rights reserved. | |
329 | * | |
330 | * Redistribution and use in source and binary forms, with or without | |
331 | * modification, are permitted provided that the following conditions | |
332 | * are met: | |
333 | * | |
334 | * 1. Redistributions of source code must retain the above copyright | |
335 | * notice, this list of conditions and the following disclaimer. | |
336 | * | |
337 | * 2. Redistributions in binary form must reproduce the above copyright | |
338 | * notice, this list of conditions and the following disclaimer in | |
339 | * the documentation and/or other materials provided with the | |
340 | * distribution. | |
341 | * | |
342 | * 3. All advertising materials mentioning features or use of this | |
343 | * software must display the following acknowledgment: | |
344 | * "This product includes software developed by the OpenSSL Project | |
345 | * for use in the OpenSSL Toolkit. (http://www.openssl.org/)" | |
346 | * | |
347 | * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to | |
348 | * endorse or promote products derived from this software without | |
349 | * prior written permission. For written permission, please contact | |
350 | * openssl-core@openssl.org. | |
351 | * | |
352 | * 5. Products derived from this software may not be called "OpenSSL" | |
353 | * nor may "OpenSSL" appear in their names without prior written | |
354 | * permission of the OpenSSL Project. | |
355 | * | |
356 | * 6. Redistributions of any form whatsoever must retain the following | |
357 | * acknowledgment: | |
358 | * "This product includes software developed by the OpenSSL Project | |
359 | * for use in the OpenSSL Toolkit (http://www.openssl.org/)" | |
360 | * | |
361 | * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY | |
362 | * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
363 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | |
364 | * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR | |
365 | * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
366 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | |
367 | * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | |
368 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
369 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | |
370 | * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
371 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | |
372 | * OF THE POSSIBILITY OF SUCH DAMAGE. | |
373 | * ==================================================================== | |
374 | * | |
375 | * This product includes cryptographic software written by Eric Young | |
376 | * (eay@cryptsoft.com). This product includes software written by Tim | |
377 | * Hudson (tjh@cryptsoft.com). | |
378 | * | |
379 | */ | |
380 | ||
381 | Original SSLeay License | |
382 | ----------------------- | |
383 | ||
384 | /* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) | |
385 | * All rights reserved. | |
386 | * | |
387 | * This package is an SSL implementation written | |
388 | * by Eric Young (eay@cryptsoft.com). | |
389 | * The implementation was written so as to conform with Netscapes SSL. | |
390 | * | |
391 | * This library is free for commercial and non-commercial use as long as | |
392 | * the following conditions are aheared to. The following conditions | |
393 | * apply to all code found in this distribution, be it the RC4, RSA, | |
394 | * lhash, DES, etc., code; not just the SSL code. The SSL documentation | |
395 | * included with this distribution is covered by the same copyright terms | |
396 | * except that the holder is Tim Hudson (tjh@cryptsoft.com). | |
397 | * | |
398 | * Copyright remains Eric Young's, and as such any Copyright notices in | |
399 | * the code are not to be removed. | |
400 | * If this package is used in a product, Eric Young should be given attribution | |
401 | * as the author of the parts of the library used. | |
402 | * This can be in the form of a textual message at program startup or | |
403 | * in documentation (online or textual) provided with the package. | |
404 | * | |
405 | * Redistribution and use in source and binary forms, with or without | |
406 | * modification, are permitted provided that the following conditions | |
407 | * are met: | |
408 | * 1. Redistributions of source code must retain the copyright | |
409 | * notice, this list of conditions and the following disclaimer. | |
410 | * 2. Redistributions in binary form must reproduce the above copyright | |
411 | * notice, this list of conditions and the following disclaimer in the | |
412 | * documentation and/or other materials provided with the distribution. | |
413 | * 3. All advertising materials mentioning features or use of this software | |
414 | * must display the following acknowledgement: | |
415 | * "This product includes cryptographic software written by | |
416 | * Eric Young (eay@cryptsoft.com)" | |
417 | * The word 'cryptographic' can be left out if the rouines from the library | |
418 | * being used are not cryptographic related :-). | |
419 | * 4. If you include any Windows specific code (or a derivative thereof) from | |
420 | * the apps directory (application code) you must include an acknowledgement: | |
421 | * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)" | |
422 | * | |
423 | * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND | |
424 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
425 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
426 | * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |
427 | * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
428 | * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
429 | * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
430 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
431 | * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
432 | * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
433 | * SUCH DAMAGE. | |
434 | * | |
435 | * The licence and distribution terms for any publically available version or | |
436 | * derivative of this code cannot be changed. i.e. this code cannot simply be | |
437 | * copied and put under another distribution licence | |
438 | * [including the GNU Public Licence.] | |
439 | */ | |
440 | ||
441 | ||
442 | ||
443 | Qt Open Source Edition | |
444 | ---------------------- | |
445 | ||
446 | The Qt GUI Toolkit is Copyright (C) 1994-2007 Trolltech ASA. | |
447 | Qt Open Source Edition is licensed under GPL version 2. | |
448 | ||
449 | Source code for the library is available at | |
450 | http://w1.fi/wpa_supplicant/qt4/qt-win-opensource-src-4.3.3.zip |