]>
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 | ||
d755e01b JM |
7 | This program is licensed under the BSD license (the one with |
8 | advertisement clause removed). | |
6fc6879b | 9 | |
6fc6879b JM |
10 | |
11 | wpa_supplicant has support for being used as a WPA/WPA2/IEEE 802.1X | |
12 | Supplicant on Windows. The current port requires that WinPcap | |
13 | (http://winpcap.polito.it/) is installed for accessing packets and the | |
14 | driver interface. Both release versions 3.0 and 3.1 are supported. | |
15 | ||
16 | The current port is still somewhat experimental. It has been tested | |
17 | mainly on Windows XP (SP2) with limited set of NDIS drivers. In | |
18 | addition, the current version has been reported to work with Windows | |
19 | 2000. | |
20 | ||
21 | All security modes have been verified to work (at least complete | |
22 | authentication and successfully ping a wired host): | |
23 | - plaintext | |
24 | - static WEP / open system authentication | |
25 | - static WEP / shared key authentication | |
26 | - IEEE 802.1X with dynamic WEP keys | |
27 | - WPA-PSK, TKIP, CCMP, TKIP+CCMP | |
28 | - WPA-EAP, TKIP, CCMP, TKIP+CCMP | |
29 | - WPA2-PSK, TKIP, CCMP, TKIP+CCMP | |
30 | - WPA2-EAP, TKIP, CCMP, TKIP+CCMP | |
31 | ||
32 | ||
6fc6879b JM |
33 | Building wpa_supplicant with mingw |
34 | ---------------------------------- | |
35 | ||
36 | The default build setup for wpa_supplicant is to use MinGW and | |
37 | cross-compiling from Linux to MinGW/Windows. It should also be | |
38 | possible to build this under Windows using the MinGW tools, but that | |
39 | is not tested nor supported and is likely to require some changes to | |
40 | the Makefile unless cygwin is used. | |
41 | ||
42 | ||
43 | Building wpa_supplicant with MSVC | |
44 | --------------------------------- | |
45 | ||
46 | wpa_supplicant can be built with Microsoft Visual C++ compiler. This | |
47 | has been tested with Microsoft Visual C++ Toolkit 2003 and Visual | |
48 | Studio 2005 using the included nmake.mak as a Makefile for nmake. IDE | |
49 | can also be used by creating a project that includes the files and | |
50 | defines mentioned in nmake.mak. Example VS2005 solution and project | |
51 | files are included in vs2005 subdirectory. This can be used as a | |
8caa12b4 JM |
52 | starting point for building the programs with VS2005 IDE. Visual Studio |
53 | 2008 Express Edition is also able to use these project files. | |
6fc6879b JM |
54 | |
55 | WinPcap development package is needed for the build and this can be | |
8caa12b4 | 56 | downloaded from http://www.winpcap.org/install/bin/WpdPack_4_0_2.zip. The |
6fc6879b JM |
57 | default nmake.mak expects this to be unpacked into C:\dev\WpdPack so |
58 | that Include and Lib directories are in this directory. The files can be | |
59 | stored elsewhere as long as the WINPCAPDIR in nmake.mak is updated to | |
60 | match with the selected directory. In case a project file in the IDE is | |
61 | used, these Include and Lib directories need to be added to project | |
62 | properties as additional include/library directories. | |
63 | ||
64 | OpenSSL source package can be downloaded from | |
8caa12b4 | 65 | http://www.openssl.org/source/openssl-0.9.8i.tar.gz and built and |
6fc6879b JM |
66 | installed following instructions in INSTALL.W32. Note that if EAP-FAST |
67 | support will be included in the wpa_supplicant, OpenSSL needs to be | |
8caa12b4 | 68 | patched to# support it openssl-0.9.8i-tls-extensions.patch. The example |
6fc6879b JM |
69 | nmake.mak file expects OpenSSL to be installed into C:\dev\openssl, but |
70 | this directory can be modified by changing OPENSSLDIR variable in | |
71 | nmake.mak. | |
72 | ||
73 | If you do not need EAP-FAST support, you may also be able to use Win32 | |
74 | binary installation package of OpenSSL from | |
75 | http://www.slproweb.com/products/Win32OpenSSL.html instead of building | |
76 | the library yourself. In this case, you will need to copy Include and | |
77 | Lib directories in suitable directory, e.g., C:\dev\openssl for the | |
78 | default nmake.mak. Copy {Win32OpenSSLRoot}\include into | |
79 | C:\dev\openssl\include and make C:\dev\openssl\lib subdirectory with | |
80 | files from {Win32OpenSSLRoot}\VC (i.e., libeay*.lib and ssleay*.lib). | |
81 | This will end up using dynamically linked OpenSSL (i.e., .dll files are | |
82 | needed) for it. Alternative, you can copy files from | |
83 | {Win32OpenSSLRoot}\VC\static to create a static build (no OpenSSL .dll | |
84 | files needed). | |
85 | ||
86 | ||
87 | Building wpa_supplicant for cygwin | |
88 | ---------------------------------- | |
89 | ||
90 | wpa_supplicant can be built for cygwin by installing the needed | |
91 | development packages for cygwin. This includes things like compiler, | |
92 | make, openssl development package, etc. In addition, developer's pack | |
93 | for WinPcap (WPdpack.zip) from | |
94 | http://winpcap.polito.it/install/default.htm is needed. | |
95 | ||
96 | .config file should enable only one driver interface, | |
97 | CONFIG_DRIVER_NDIS. In addition, include directories may need to be | |
98 | added to match the system. An example configuration is available in | |
99 | defconfig. The library and include files for WinPcap will either need | |
100 | to be installed in compiler/linker default directories or their | |
101 | location will need to be adding to .config when building | |
102 | wpa_supplicant. | |
103 | ||
104 | Othen than this, the build should be more or less identical to Linux | |
105 | version, i.e., just run make after having created .config file. An | |
106 | additional tool, win_if_list.exe, can be built by running "make | |
107 | win_if_list". | |
108 | ||
109 | ||
110 | Building wpa_gui | |
111 | ---------------- | |
112 | ||
113 | wpa_gui uses Qt application framework from Trolltech. It can be built | |
114 | with the open source version of Qt4 and MinGW. Following commands can | |
115 | be used to build the binary in the Qt 4 Command Prompt: | |
116 | ||
117 | # go to the root directory of wpa_supplicant source code | |
118 | cd wpa_gui-qt4 | |
119 | qmake -o Makefile wpa_gui.pro | |
120 | make | |
121 | # the wpa_gui.exe binary is created into 'release' subdirectory | |
122 | ||
123 | ||
124 | Using wpa_supplicant for Windows | |
125 | -------------------------------- | |
126 | ||
127 | wpa_supplicant, wpa_cli, and wpa_gui behave more or less identically to | |
128 | Linux version, so instructions in README and example wpa_supplicant.conf | |
129 | should be applicable for most parts. In addition, there is another | |
130 | version of wpa_supplicant, wpasvc.exe, which can be used as a Windows | |
131 | service and which reads its configuration from registry instead of | |
132 | text file. | |
133 | ||
134 | When using access points in "hidden SSID" mode, ap_scan=2 mode need to | |
135 | be used (see wpa_supplicant.conf for more information). | |
136 | ||
137 | Windows NDIS/WinPcap uses quite long interface names, so some care | |
138 | will be needed when starting wpa_supplicant. Alternatively, the | |
139 | adapter description can be used as the interface name which may be | |
140 | easier since it is usually in more human-readable | |
141 | format. win_if_list.exe can be used to find out the proper interface | |
142 | name. | |
143 | ||
144 | Example steps in starting up wpa_supplicant: | |
145 | ||
146 | # win_if_list.exe | |
147 | ifname: \Device\NPF_GenericNdisWanAdapter | |
148 | description: Generic NdisWan adapter | |
149 | ||
150 | ifname: \Device\NPF_{769E012B-FD17-4935-A5E3-8090C38E25D2} | |
151 | description: Atheros Wireless Network Adapter (Microsoft's Packet Scheduler) | |
152 | ||
153 | ifname: \Device\NPF_{732546E7-E26C-48E3-9871-7537B020A211} | |
154 | description: Intel 8255x-based Integrated Fast Ethernet (Microsoft's Packet Scheduler) | |
155 | ||
156 | ||
157 | Since the example configuration used Atheros WLAN card, the middle one | |
158 | is the correct interface in this case. The interface name for -i | |
159 | command line option is the full string following "ifname:" (the | |
160 | "\Device\NPF_" prefix can be removed). In other words, wpa_supplicant | |
161 | would be started with the following command: | |
162 | ||
163 | # wpa_supplicant.exe -i'{769E012B-FD17-4935-A5E3-8090C38E25D2}' -c wpa_supplicant.conf -d | |
164 | ||
165 | -d optional enables some more debugging (use -dd for even more, if | |
166 | needed). It can be left out if debugging information is not needed. | |
167 | ||
168 | With the alternative mechanism for selecting the interface, this | |
169 | command has identical results in this case: | |
170 | ||
171 | # wpa_supplicant.exe -iAtheros -c wpa_supplicant.conf -d | |
172 | ||
173 | ||
174 | Simple configuration example for WPA-PSK: | |
175 | ||
176 | #ap_scan=2 | |
177 | ctrl_interface= | |
178 | network={ | |
179 | ssid="test" | |
180 | key_mgmt=WPA-PSK | |
181 | proto=WPA | |
182 | pairwise=TKIP | |
183 | psk="secret passphrase" | |
184 | } | |
185 | ||
186 | (remove '#' from the comment out ap_scan line to enable mode in which | |
187 | wpa_supplicant tries to associate with the SSID without doing | |
188 | scanning; this allows APs with hidden SSIDs to be used) | |
189 | ||
190 | ||
191 | wpa_cli.exe and wpa_gui.exe can be used to interact with the | |
192 | wpa_supplicant.exe program in the same way as with Linux. Note that | |
193 | ctrl_interface is using UNIX domain sockets when built for cygwin, but | |
194 | the native build for Windows uses named pipes and the contents of the | |
195 | ctrl_interface configuration item is used to control access to the | |
196 | interface. Anyway, this variable has to be included in the configuration | |
197 | to enable the control interface. | |
198 | ||
199 | ||
200 | Example SDDL string formats: | |
201 | ||
202 | (local admins group has permission, but nobody else): | |
203 | ||
204 | ctrl_interface=SDDL=D:(A;;GA;;;BA) | |
205 | ||
206 | ("A" == "access allowed", "GA" == GENERIC_ALL == all permissions, and | |
207 | "BA" == "builtin administrators" == the local admins. The empty fields | |
208 | are for flags and object GUIDs, none of which should be required in this | |
209 | case.) | |
210 | ||
211 | (local admins and the local "power users" group have permissions, | |
212 | but nobody else): | |
213 | ||
214 | ctrl_interface=SDDL=D:(A;;GA;;;BA)(A;;GA;;;PU) | |
215 | ||
216 | (One ACCESS_ALLOWED ACE for GENERIC_ALL for builtin administrators, and | |
217 | one ACCESS_ALLOWED ACE for GENERIC_ALL for power users.) | |
218 | ||
219 | (close to wide open, but you have to be a valid user on | |
220 | the machine): | |
221 | ||
222 | ctrl_interface=SDDL=D:(A;;GA;;;AU) | |
223 | ||
224 | (One ACCESS_ALLOWED ACE for GENERIC_ALL for the "authenticated users" | |
225 | group.) | |
226 | ||
227 | This one would allow absolutely everyone (including anonymous | |
228 | users) -- this is *not* recommended, since named pipes can be attached | |
229 | to from anywhere on the network (i.e. there's no "this machine only" | |
230 | like there is with 127.0.0.1 sockets): | |
231 | ||
232 | ctrl_interface=SDDL=D:(A;;GA;;;BU)(A;;GA;;;AN) | |
233 | ||
234 | (BU == "builtin users", "AN" == "anonymous") | |
235 | ||
236 | See also [1] for the format of ACEs, and [2] for the possible strings | |
237 | that can be used for principal names. | |
238 | ||
239 | [1] | |
240 | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/ace_strings.asp | |
241 | [2] | |
242 | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/sid_strings.asp | |
243 | ||
244 | ||
245 | Starting wpa_supplicant as a Windows service (wpasvc.exe) | |
246 | --------------------------------------------------------- | |
247 | ||
248 | wpa_supplicant can be started as a Windows service by using wpasvc.exe | |
249 | program that is alternative build of wpa_supplicant.exe. Most of the | |
250 | core functionality of wpasvc.exe is identical to wpa_supplicant.exe, | |
251 | but it is using Windows registry for configuration information instead | |
252 | of a text file and command line parameters. In addition, it can be | |
253 | registered as a service that can be started automatically or manually | |
254 | like any other Windows service. | |
255 | ||
256 | The root of wpa_supplicant configuration in registry is | |
257 | HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant. This level includes global | |
258 | parameters and a 'interfaces' subkey with all the interface configuration | |
259 | (adapter to confname mapping). Each such mapping is a subkey that has | |
260 | 'adapter', 'config', and 'ctrl_interface' values. | |
261 | ||
262 | This program can be run either as a normal command line application, | |
263 | e.g., for debugging, with 'wpasvc.exe app' or as a Windows service. | |
264 | Service need to be registered with 'wpasvc.exe reg <full path to | |
265 | wpasvc.exe>'. Alternatively, 'wpasvc.exe reg' can be used to register | |
266 | the service with the current location of wpasvc.exe. After this, wpasvc | |
267 | can be started like any other Windows service (e.g., 'net start wpasvc') | |
268 | or it can be configured to start automatically through the Services tool | |
269 | in administrative tasks. The service can be unregistered with | |
270 | 'wpasvc.exe unreg'. | |
271 | ||
272 | If the service is set to start during system bootup to make the | |
273 | network connection available before any user has logged in, there may | |
274 | be a long (half a minute or so) delay in starting up wpa_supplicant | |
275 | due to WinPcap needing a driver called "Network Monitor Driver" which | |
276 | is started by default on demand. | |
277 | ||
278 | To speed up wpa_supplicant start during system bootup, "Network | |
279 | Monitor Driver" can be configured to be started sooner by setting its | |
280 | startup type to System instead of the default Demand. To do this, open | |
281 | up Device Manager, select Show Hidden Devices, expand the "Non | |
282 | Plug-and-Play devices" branch, double click "Network Monitor Driver", | |
283 | go to the Driver tab, and change the Demand setting to System instead. | |
284 | ||
285 | Configuration data is in HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs | |
286 | key. Each configuration profile has its own key under this. In terms of text | |
287 | files, each profile would map to a separate text file with possibly multiple | |
288 | networks. Under each profile, there is a networks key that lists all | |
289 | networks as a subkey. Each network has set of values in the same way as | |
290 | network block in the configuration file. In addition, blobs subkey has | |
291 | possible blobs as values. | |
292 | ||
293 | HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs\test\networks\0000 | |
294 | ssid="example" | |
295 | key_mgmt=WPA-PSK | |
296 | ||
297 | See win_example.reg for an example on how to setup wpasvc.exe | |
298 | parameters in registry. It can also be imported to registry as a | |
299 | starting point for the configuration. |