Product Documentation Devicescape Secure Wireless Client

Documentation Home for Devicescape Secure Wireless Client > Developer Guide

DSA Supplicant for Windows Targets

Overview of DSA Supplicant on Windows Targets
Building DSA Supplicant and Necessary Components
Limitations of DSA Supplicant on Windows

Overview of DSA Supplicant on Windows Targets

The Devicescape Windows version of DSA Supplicantis driven by an event loop. DSA Supplicant must respond to specified events, such as signals and sockets (receiving new packets to be read).

The Windows distribution of DSA Supplicant includes two implementations for handling layer 2 (link layer) packet sending and receiving. An implementation using Windows packet sockets is provided in l2_packet_ndis.c. The second implementation uses winpcap and is provided in l2_packet_winpcap.c.

DSA Supplicant for Windows is provided in both source and binary formats. For information on how to install the appropriate binary version, refer to the README.txt file included with the binary zip file. The following directions and requirements are applicable to source code builds.

Windows WLAN Drivers

DSA Supplicant utilizes the Windows NDIS driver interface. Therefore, any WLAN driver that conforms to the NDIS specification should be compatible with DSA Supplicant for generic WPA/WPA2 PSK and enterprise functions. Note that many drivers do not support Cisco CCX extensions - check with the driver developer to confirm the availability of these features.

Required Tools

In order to build and test the Devicescape Agent Supplicant for WinCE, Windows Mobile and Windows XP, the following tools and software must be installed on your development host.

Tools	Description
PC or laptop	The machine should be running either Windows 2000 or Windows XP Professional (the latter being preferable). This machine should have resources suitable for the installation and execution of the software development tools.
Windows Visual Studio 2005	This is a Windows development environment for Windows Mobile 5.0. For more information on Windows Visual Studio 2005 and how it can be obtained, see http://www.microsoft.com.
Windows Mobile 5.0 SDK	The Windows Mobile 5.0 SDK enables the development for Windows Mobile-based devices using Visual Studio 2005.
Windows CE 5.0 SDK	The Windows CE 5.0 SDK enables the development for Windows CE-based devices using Visual Studio 2005.
Win32 Perl interpreter	A recommended product called ActivePerl is available free of cost from http://www.activestate.com/Products/ActivePerl/. (This is required for building OpenSSL.)

DSA Supplicant Host Development Environment

DSA Supplicant provides two Microsoft Visual Studio 2005 solution files: "wince/dsa.sln" solution file (for Windows CE and Windows Mobile) or the "vs2005/wpa_supplicant.sln" solution file (for Windows XP). These files support a variety of build configurations.

DSA Supplicant can be built either as an application (.exe) or as a network service (.dll). The executable form can be useful for debugging and troubleshooting as it can be built with debug support and debugged with an appropriate debug transport. Due to the Linux heritage of the code, status messages are output using standard console I/O functions and Windows displays these messages if console support is built into the OS image. These messages can be suppressed by defining CONFIG_NO_STDOUT_DEBUG in cfgdefs.h (Windows CE and Windows Mobile) or build_config.h (Windows XP). This is a recommended step if you are building DSA Supplicant as a service.

Building DSA Supplicant and Necessary Components

Building OpenSSL for Windows XP
Building OpenSSL for WinCE and Windows Mobile
Configuring the DSA Supplicant Build
Building DSA Supplicant, the CLI and the GUI
Running DSA Supplicant as an Executable Program
Running DSA Supplicant as a Network Service

Before you build the Devicescape Agent Supplicant you must configure and build OpenSSL, if you are using OpenSSL as your TLS library. If you wish to use another TLS library (i.e. Certicom), please install and build the library according to the vendor's instructions.

Building OpenSSL for Windows XP

Unzip the DSA Supplicant source code (if you have not already done so) and navigate to the OpenSSL root directory, i.e:

cd openssl-0.9.8.a-devicescape-dsa-<version>

Install Microsoft Visual Studio 2005, if not already installed.
Install the developer version of WinPcap (WpdPack_1_1, not WinPcap_3_1), available from http://www.winpcap.org/devel/htm.
Follow the INSTALL.W32 readme instructions in the openssl root directory, up to the point where you run the build (nmake) command. Choose the "Microsoft MASM" option for the assembly language routine optimization as VS 2005 contains MASM.
Change the OpenSSL build options so that it can be statically linked with a Windows executable. In the nt.mak file in the openssll\ms directory, find the following options line:

CFLAG= /MD /Ox /O2 /Ob2 /W3 /WX /Gs0 /GF /Gy /nologo -DOPENSSL_SYSNAME_WIN32 
-DWIN32_LEAN_AND_MEAN -DL_ENDIAN -DDSO_WIN32 -D_CRT_SECURE_NO_DEPRECATE -
DBN_ASM -DMD5_ASM -DSHA1_ASM -DRMD160_ASM /Fdout32 -DOPENSSL_NO_RC5 -
DOPENSSL_NO_MDC2 -DOPENSSL_NO_KRB5 

and remove the following options:

/MD /W3 /WX

The options line should now read as follows:

CFLAG= /Ox /O2 /Ob2 /Gs0 /GF /Gy /nologo -DOPENSSL_SYSNAME_WIN32 -
DWIN32_LEAN_AND_MEAN -DL_ENDIAN -DDSO_WIN32 -D_CRT_SECURE_NO_DEPRECATE -
DBN_ASM -DMD5_ASM -DSHA1_ASM -DRMD160_ASM /Fdout32 -DOPENSSL_NO_RC5 -
DOPENSSL_NO_MDC2 -DOPENSSL_NO_KRB5 

Open a VS2005 command prompt, and build OpenSSL by running the following command from the openssl\ms directory:

nmake -f nt.mak

Ensure that lib files are created in a new openssl\out32 directory.

All lib files will be placed in the out32 directory.

Building OpenSSL for WinCE and Windows Mobile

Unzip the DSA Supplicant source code (if you have not already done so) and navigate to the OpenSSL root directory, i.e:

cd openssl-0.9.8.a-devicescape-dsa-<version>

Install Microsoft Visual Studio 2005, if not already installed.
Follow the INSALL.WCS readme instructions in the openssl root directory.

Configuring the DSA Supplicant Build

For Windows CE and Windows Mobile, cfgdefs.h is used to determine which features are included in the DSA Supplicant build.

For Windows XP, build_config.h is used to determine which features are included in the DSA Supplicant build.

If you are using Certicom SSL as the TLS library instead of OpenSSL, follow the instructions provided in Building DSA Supplicant and Necessary Components and modify the project as described below. This example shows the changes required for an ARM target on WinCE. For Windows XP, you would modify build_config.h and include the appropriate x86 libraries.

Edit cfgdefs.hto include Certicom support and disable OpenSSL by using the following TLS support configuration:

#undef CONFIG_TLS_OPENSSL

#define CONFIG_TLS_CERTICOM

#undef CONFIG_TLS_MATRIXSSL

Include the following libraries:

sslplus.lib

huctx.lib

tp.lib

cic.lib

husw.lib

huuw.lib

hu.lib

Include the following library directories

sslplus5-wince3_arm\tools\tp_c_toolkit\sb-wince3_arm\lib

sslplus5-wince3_arm\lib\wince3_arm

slplus5-wince3_arm\lib\wince3_arm

Include these include directories

sslplus5-wince3_arm\include

sslplus5-wince3_arm\tools\tp_c_toolkit\sb-wince3_arm\include

Building DSA Supplicant, the CLI and the GUI

DSA Supplicant is built using the Microsoft Visual Studio 2005 solution file. For Windows CE 5.0, the Windows CE 5.0 SDK is also required. For Windows Mobile, the Windows Mobile 5.0 SDK is also required. Both of these downloads are available from Microsoft. At this time, these SDKs only support ARM architectures.

A sample MFC Windows Mobile based UI for DSA Supplicant is provided along with the source code in the following directory: devicescape-dsa-<someversion>\sample_windows_gui\. This GUI is common to Windows XP, Windows CE and Windows Mobile.

Windows XP

For Windows XP builds the vs2005/wpa_supplicant.sln file is used to build the following files:

File	Content
win_if_list.exe	returns a current list of network interfaces
wpa_cli.exe	provides a CLI for DSA Supplicant
wpa_passphrase.exe	generates a PSK from a passphrase, and vice versa
wpa_supplicant.exe	the supplicant as an application
wpasvc.exe	the supplicant as a service
wpa_gui.exe	the DSA Supplicant sample GUI

To build these files, issue the following command from a Visual Studio 2005 command prompt in the vs2005 directory:

devenv wpa_supplicant.sln /rebuild release

The build will also take the above executable files (except wpasvc.exe) and wrap them in a Windows XP installer to allow easy installation on a Windows XP target.

Windows CE and Windows Mobile

For Windows CE and Mobile builds the wince/wpa_supplicant file is used to build the following files:

File	Content
dsfilter_activate.exe	enables the IM driver
dsfilter_deactivate.exe	disables the IM driver
dsfilter_setup.exe	configures the IM driver
file2reg.exe	utility to convert a text file to registry entries (not included in install by default)
get_debug.exe	utility to dump IM driver debug log contents to a text file on the file system
ndis_enum.exe	utility that returns NDIS adapter bindings, useful to verify IM driver install
dsfilter.dll	the IM driver used to route 802.1X packets to DSA Supplicant
set_debug.exe	utility to turn on/off IM driver debug mode)
sreginit.exe	populates registry
wpa_supplicant.exe	DSA Supplicant as an application
wpasvc.dll	DSA Supplicant as a service
terminate.exe	utility to terminate DSA Supplicant and return control to WZC
wpacli.exe	DSA Supplicant CLI application (if a command line is available)
wpagui.exe	the DSA Supplicant sample GUI

To build these files, issue the following command from a Visual Studio 2005 command prompt in the wince directory (for Windows CE and Windows Mobile builds, respectively):

devenv wpa_supplicant.sln /rebuild "Release|SandgateII_P (ARMV4I)" 

devenv wpa_supplicant.sln /rebuild "Release|Windows Mobile 5.0 Pocket PC 
SDK (ARMV4I)"

The build will also take the above executable files (except file2reg.exe and wpasvc.dll) wrap them in a CAB file. This CAB file can then be transferred to the target device and installed by double-clicking the CAB file icon, followed by a device reboot.

Note	If you wish to initialize the dsfilter.dll file during OS boot-up, it may need to be signed with a digital certificate from the device manufacturer. This limitation can be avoided by waiting until after the OS has completed booting before initializing dsfilter.dll.

Running DSA Supplicant as an Executable Program

When DSA Supplicant supplicant is used as an application wpa_supplicant.exe (Windows CE and Windows Mobile) or wpa_supplicant.exe (Windows XP), it is started by simply running the program. The application can be terminated by using its control interface to send a TERMINATE command. wpa_cli.c includes example code that uses the control interface. Similar functionality can be added into a separate program (e.g., the wireless configuration tool) that selects which supplicant is used. This application should be linked with wpa_ctrl.c to include functions needed for using the control interface.

The following example code sends a TERMINATE command:

struct wpa_ctrl *ctrl_conn = wpa_ctrl_open("");

if (ctrl_conn) {

   char reply[10];

   size_t len = sizeof(reply);

   wpa_ctrl_request(ctrl_conn, "TERMINATE", 9, reply, &len, NULL);

   wpa_ctrl_close(ctrl_conn);

}

Running DSA Supplicant as a Network Service

Running DSA Supplicant as a network service is the typical mode of deployment on production devices. When DSA Supplicant supplicant is used as a service wpasvc.dll (Windows CE and Windows Mobile) or wpasvc.exe (Windows XP), it is started like any other system service. If swcserv is installed with the default .inf file, wpasvc is automatically started at boot time based on registry entries. Alternatively, the service can be loaded with a RegisterService() call. Once the service is loaded, it can be started and stopped with IOCTL_SERVICE_START/IOCTL_SERVICE_STOP calls to WPASVC device.

The following example code stops and start the service:

static int wpa_svc_ioctl(DWORD cmd)

{

	HANDLE h;

	int ret = 0;

	h = CreateFile(L"WPASVC:", 0, 0, NULL, OPEN_EXISTING,

		       FILE_ATTRIBUTE_NORMAL, NULL);

	h = GetServiceHandle(L"WPASVC:", NULL, NULL);

	if (h == INVALID_HANDLE_VALUE) {

		/* Failed to get handle to WPASVC: */

		return -1;

	}

	if (ServiceIoControl(h, cmd, NULL, 0, NULL, 0, NULL, NULL)) {

		/* ServiceIoControl successfully completed */

	} else {

		/* ServiceIoControl failed */

		ret = -1;

	}

	CloseHandle(h);

	return ret;

}

int wpa_svc_start(void)

{

	return wpa_svc_ioctl(IOCTL_SERVICE_START);

}

int wpa_svc_stop(void)

{

	return wpa_svc_ioctl(IOCTL_SERVICE_STOP);

}

DSA Supplicant Network Service Registry Configuration

The wpasvc subkey in HKEY_LOCAL_MACHINE\SERVICES\WPASVC (WinCE/WinMobile) or HKEY_LOCAL_MACHINE\SOFTWARE\Devicescape\DSA (WinXP) is responsible for configuring the DSA Supplicant service. This subkey is enumerated by Windows on startup.

To add the DSA Supplicant service, add subkey wpasvc of "Services" called "swcserv". This subkey should then contain the following set of registry values. Values marked as optional need not be instantiated.

Value Name	Value Type	Value Data Description
Order	REG_DWORD	Should be set to a value appropriate for your system. Lower numbered services are loaded first. If there are services that depend on the secure wireless connection made by DSA Supplicant, then Order should be of a lower value than these services, or else Order can be a relatively high value.
Dll	REG_SZ	Should be set to "wpasvc.dll" if using the pre-configured projects, or what the DLL output of your service project is, if you choose to create your own project with a different IDE. This DLL should reside in the \Windows directory of your device.
Keep	REG_DWORD	Always set to 1
Prefix	REG_SZ	Should be set to "DSA Supplicant"
Index	REG_DWORD	Should be set to 0
DisplayName	REG_SZ	Optional
Description	REG_SZ	Optional
Context	REG_DWORD	Always set to 0
Flags	REG_DWORD	Optional, or set to 0 for the default value

For more general information about registry keys, see also Defining Windows Registry Keys for DSA Supplicant Runtime Configuration.

Limitations of DSA Supplicant on Windows

It should be noted that there are a number of compatibility issues when running DSA Supplicant on Windows Platforms. These are described in the following table:

Windows Platform	Compatibility Issue
Windows XP	Windows Zero Config (WZC)must always be disabled when using DSA Supplicant. DSA Supplicant will automatically disable WZC once it starts running. You can also disable WZC from the Desktop.
WinCE	The DSA Supplicant wireless interface looks like a Wired Interface There is no Power Management capability WZC will still appear as a menu option even when it is not active
Windows Mobile	All of those mentioned for WinCE and including; No Command Line for the CLI

© 2006 Devicescape Software, Inc. - Sitemap - BLOG     Contact Sales sales@devicescape.com or call +1.650.829.2600