wpa_supplicant/README-Windows.txt

   1 wpa_supplicant for Windows
   2 ==========================
   3
   4 Copyright (c) 2003-2009, Jouni Malinen <j@w1.fi> and contributors
   5 All Rights Reserved.
   6
   7 This program is licensed under the BSD license (the one with
   8 advertisement clause removed).
   9
  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
  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
  52 starting point for building the programs with VS2005 IDE. Visual Studio
  53 2008 Express Edition is also able to use these project files.
  54
  55 WinPcap development package is needed for the build and this can be
  56 downloaded from http://www.winpcap.org/install/bin/WpdPack_4_0_2.zip. The
  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
  65 http://www.openssl.org/source/openssl-0.9.8i.tar.gz and built and
  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
  68 patched to# support it openssl-0.9.8i-tls-extensions.patch. The example
  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.