contrib/wpa_supplicant/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 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
  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).
  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
  71 starting point for building the programs with VS2005 IDE. Visual Studio
  72 2008 Express Edition is also able to use these project files.
  73
  74 WinPcap development package is needed for the build and this can be
  75 downloaded from http://www.winpcap.org/install/bin/WpdPack_4_0_2.zip. The
  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
  84 http://www.openssl.org/source/openssl-0.9.8i.tar.gz and built and
  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
  87 patched to# support it openssl-0.9.8i-tls-extensions.patch. The example
  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