Appendix A. Supplementary Information
The following sections provide workarounds, command output, and utility build procedures and other supplementary information that may be useful to WinCE target developers. This information is cross-referenced in the topic DSA Supplicant for Windows Targets in the context of various procedures for building an deploying DSA Supplicant.
Command Line Options for DSA Supplicant
Syntax
wpa_supplicant [-BddehLqqvw] [-P<pid file>] [-g<global ctrl>] \
-i<ifname> -c<ConfigFile> [-D<driver>] [-p<driver_param>]\
[-N -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] [-p<driver_param>] ...]
Options
|
Option
|
Description
|
|
-B
|
Run daemon in the background
|
|
-b
|
Specify optional bridge interface name
|
|
-c
|
Tell DSA Supplicant from where to read the configuration file
|
|
-C
|
ctrl_interface parameter (only used if -c is not)
|
|
-i
|
Interface name
|
|
-d
|
Increase debugging verbosity (-dd even more)
|
|
-D
|
Driver name
|
|
-g
|
Global ctrl_interface
|
|
-K
|
Include keys (passwords, etc.) in debug output
|
|
-t
|
Include timestamp in debug messages
|
|
-h
|
Show this help text
|
|
-L
|
Show license (GPL and BSD)
|
|
-p
|
Driver parameters
|
|
-P
|
PID file
|
|
-q
|
Decrease debugging verbosity (-qq even less)
|
|
-v
|
Show version
|
|
-w
|
Wait for interface to be added, if needed
|
|
-W
|
Wait for a control interface monitor before starting
|
|
-N
|
Start describing new interface drivers
|
Drivers
|
D<driver>
|
Description
|
|
Supported Driver Interfaces
|
|
i802
|
Devicescape 80211.o
|
|
AR6000
|
Atheros AR6000
|
|
broadcom
|
Broadcom wl.o driver BCM4306/4309/4320
|
|
Unsupported Driver Interfaces
|
|
hostap
|
Host AP driver (Intersil Prism2/2.5/3). This is the default.
hostap can also be used with Linuxant DriverLoader
|
|
prism54
|
Prism54.org driver (Intersil Prism GT/Duette/Indigo not yet fully implemented)
|
|
hermes
|
Agere Systems Inc. driver (Hermes-I/Hermes-II)
|
|
madwifi
|
MADWIFI 802.11 support (Atheros, for example)
|
|
atmel
|
ATMEL AT76C5XXx (USB, PCMCIA)
|
|
wext
|
Linux wireless extensions (generic)
|
|
ndiswrapper
|
Linux ndiswrapper
|
|
ipw
|
Intel ipw2100/2200 driver
|
|
bsd
|
BSD 802.11 support (Atheros, for example)
|
|
ndis
|
Windows NDIS driver
|
|
Marvell
|
Marvell driver for Linux
|
In most common cases, wpa_supplicant is started with the following options:
wpa_supplicant -Bw -c/etc/wpa_supplicant.conf -iwlan0
This makes the process fork into background and wait for the wlan0 interface if it is not available at startup time.
The easiest way to debug problems, and to get debug log for bug reports, is to start wpa_supplicant in the foreground with debugging enabled:
wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
For even more verbose debugging, use the -ddK option.
DSA Supplicant can control multiple interfaces (radios) either by running one process for each interface separately or by running one process and a list of options at the command line. Each interface is separated with -N argument. As an example, the following command would start DSA Supplicant for two interfaces:
-c wpa1.conf -i wlan0 -D hostap -N \
-c wpa2.conf -i ath0 -D madwifi
Using wpa_cli
wpa_cli is a text-based front-end program for interacting with DSA Supplicant. It is used to query current status, change configuration, trigger events, and request interactive user input.
wpa_cli can show the current authentication status, selected security mode, dot11 and dot1x MIBs, etc. In addition, it can configure some variables like EAPOL state machine parameters and trigger events like reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user interface to request authentication information, like username and password, if these are not included in the configuration. This can be used to implement; for example, one-time-passwords or generic token card authentication where the authentication is based on a challenge-response that uses an external device for generating the response.
The control interface of wpa_supplicant can be configured to allow non-root user access (ctrl_interface_group in the configuration file). This makes it possible to run wpa_cli with a normal user account.
wpa_cli can also be configured for remote CLI operation via a UDP connection with another host. This is useful for when the target does not support a CLI or when it is impractical to use a CLI directly on the target. To use this feature, set the following macro in .config (Linux) cfgdefs.h (WinCE/WinMobile) or build_config.h (WinXP) to CONFIG_REMOTE_CLI
Next you will need to compile the wpa_remote_cli.c file to run on your remote host. This program is simply a UDP proxy to the actual wpa_cli application running on the target. Therefore, the wpa_cli application must be running on the target in order to use the remote CLI. Note that is the remote CLI is enabled, the local CLI on the target is disabled.
wpa_cli supports two modes: interactive and command line. Both modes share the same command set and the main difference is in interactive mode providing access to unsolicited messages (event messages, username/password requests).
Interactive mode is started when wpa_cli is executed without including the command as a command line parameter. Commands are then entered on the wpa_cli prompt. In command line mode, the same commands are entered as command line arguments for wpa_cli.
For more detailed information on wpa_cli commands, see wpa_cli commands
Interactive Authentication Parameters Request
When DSA Supplicant needs authentication parameters, like username and password, which are not present in the configuration file, it sends a request message to all attached front-end programs, for wpa_cli in interactive mode. wpa_cli shows these requests with "CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or OTP (one-time-password). <id> is a unique identifier for the current network. <text> is description of the request. In case of OTP request, it includes the challenge from the authentication server.
The reply to these requests can be given with 'identity', 'password', and 'otp' commands. <id> needs to be copied from the matching request. 'password' and 'otp' commands can be used regardless of whether the request was for PASSWORD or OTP. The main difference between these two commands is that values given with 'password' are remembered as long as DSA Supplicant is running whereas values given with 'otp' are used only once and then forgotten; that is,DSA Supplicant will ask front-end for a new value for every use. This can be used to implement one-time-password lists and generic token card-based authentication.
Example request for password and a matching reply:
CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
> password 1 mysecretpassword
Example request for generic token card challenge-response:
CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
wpa_cli commands
Syntax
wpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \
[-P<pid file>] [-g<global ctrl>] [command..]
-h = help (show this usage text)
-v = shown version information
-a = run in daemon mode executing the action file based on events from wpa_supplicant
-B = run a daemon in the background
default path: /var/run/wpa_supplicant
default interface: first interface found in socket path
Commands
|
Option
|
Description
|
|
status [verbose]
|
get current WPA/EAPOL/EAP status
|
|
mib
|
get MIB variables (dot1x, dot11)
|
|
help
|
show this usage help
|
|
interface [ifname]
|
show interfaces/select interface
|
|
level <debug level>
|
change debug level
|
|
license
|
show full wpa_cli license
|
|
logoff
|
IEEE 802.1X EAPOL state machine logoff
|
|
logon
|
IEEE 802.1X EAPOL state machine logon
|
|
set
|
set variables (shows list of variables when run without arguments)
|
|
pmksa
|
show PMKSA cache
|
|
reassociate
|
force reassociation
|
|
reconfigure
|
force wpa_supplicant to re-read its configuration file
|
|
preauthenticate <BSSID>
|
force preauthentication
|
|
identity <network id> <identity>
|
configure identity for an SSID
|
|
password <network id> <password>
|
configure password for an SSID
|
|
new_password <network id> <password>
|
change password for an SSID
|
|
pin <network id> <pin>
|
configure pin for an SSID
|
|
otp <network id> <password>
|
configure one-time-password for an SSID
|
|
passphrase <network id> <passphrase>
|
configure private key passphrase for an SSID
|
|
bssid <network id> <BSSID>
|
set preferred BSSID for an SSID
|
|
list_networks
|
list configured networks
|
|
select_network <network id>
|
select a network (disable others)
|
|
enable_network <network id>
|
enable a network
|
|
disable_network <network id>
|
disable a network
|
|
add_network
|
add a network
|
|
remove_network <network id>
|
remove a network
|
|
set_network <network id> <variable> <value>
|
set network variables (shows list of variables when run without arguments)
|
|
get_network <network id> <variable>
|
get network variables
|
|
save_config
|
save the current configuration
|
|
disconnect
|
disconnect and wait for reassociate command before connecting
|
|
scan
|
request new BSS scan
|
|
scan_results
|
get latest scan results
|
|
get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg>
|
get capabilites
|
|
stakey-request <addr>
|
request STAKey negotiation with <addr>
|
|
ap_scan <value>
|
set ap_scan parameter
|
|
terminate
|
terminate wpa_supplicant
|
|
quit
|
exit wpa_cli
|
Defining Windows Registry Keys for DSA Supplicant Runtime Configuration
The runtime configuration information for the DSA Supplicant Windows application or service must be stored in the Windows registry on the target system. The following sections provide a brief introduction to some key concepts with regard to the registry and explain how to define registry keys for your DSA Supplicant application or service.
What is the Registry?
The registry is a Microsoft system database used to store configuration information in applications and in the Microsoft Windows operating system itself. The registry system provides a standard framework to store configuration data. Microsoft development tools support registry editors. Microsoft Visual Studio 2005 supports registry library and APIs.
Registry keys are name - value pairs stored in the registry that define the configuration for an application or service on a Microsoft Windows operating system.
Creating DSA Supplicant Registry Entries
The DSA Supplicant application or service is designed to operate in the standard Windows environment via security profiles that get and set parameters in the registry. The steps to create DSA Supplicant registry keys on Windows CE and Windows Mobile targets is as follows:
- Build the utility "file2reg" (built by default) and download the resulting executable
file2reg.exe to the target device. Use any of the text-based example configuration files provided with the source package (in devicescape-dsa-<version>/examples/) as a model for defining runtime configuration modes for the wireless client. Example profiles are provided for various security modes. The wpa_supplicant.conf file provided in the top level of the source package shows all parameters and proper syntax for runtime configuration of the client.
- Copy, modify, and save your text-based configuration file and then download it to the target device.
- Use file2reg utility on the target to convert the configuration file to a registry-based configuration. (You can also use the Remote Registry Editor to modify the keys once they are on the target.)
Using file2reg (Syntax and Options)
Use the file2reg utility on the target to convert the configuration file to a registry-based configuration. Following is the syntax for using this command line utility:
file2reg -c <ConfigFile> -i <InterfaceName>
where:
- <
ConfigFile> is the full path to the text-based configuration file. For example, temp\dsa.txt which will be used as the default value if -c parameter is not included on the command line.
<InterfaceName> is the default interface name. The DSA Supplicant will use this interface as the default interface. DSFLTR_AR6K1 will be used as the default interface name if -i parameter is not specified on the command line."
The -c and -I options are not required.
Output of file2reg
When you run the file2reg command on a configuration file, it will create a registry tree structure with the following:
Registry Key Definitions for DSA Supplicant
The Microsoft registry supports three of the root keys:
- HKEY_LOCAL_MACHINE
- HKEY_CURRENT_USER
- HKEY_CLASSES_ROOT
Configuration data for the Devicescape Agent Supplicant running on a Windows target is stored under the HKEY_LOCAL_MACHINE key.
The DSA Supplicant configuration data in the registry is obtained by means of following structure: HKEY_LOCAL_MACHINE\Software\Devicescape\DSA Supplicant
|
Directory
|
|
Type
|
|
<DSA Supplicant_Root>\
|
wpa_debug_level
|
REG_DWORD
|
|
<DSA Supplicant_Root>\
|
profile-001\<Profile_SubKey>\
|
|
|
|
profile-002\<Profile_SubKey>\
|
|
|
|
......
|
|
|
|
profile-n\<Profile_SubKey>\
|
|
| |
Interface-001\<Interface>\
|
|
| |
Interface-002\<Interface>\
|
|
| |
......
|
|
| |
Interface-n\<Interface>\
|
|
| |
|
|
|
<Interface>\
|
iface
|
REG_SZ
|
| |
driver
|
REG_SZ
|
| |
profile
|
REG_SZ
|
| |
|
|
| |
|
|
|
<Profile_SubKey>\
|
update_config
|
REG_DWORD
|
|
|
eapol_version
|
REG_DWORD
|
|
|
ap_scan
|
REG_DWORD
|
|
|
fast_reauth
|
REG_DWORD
|
| |
open_engine_path
|
REG_SZ
|
| |
pkcs11_engine_path
|
REG_SZ
|
| |
pkcs11_module_path
|
REG_SZ
|
| |
dot11RSNAConfigPMKLifeTime
|
REG_DWORD
|
| |
dot11RSNAConfigPMKReauthThreshhold
|
REG_DWORD
|
| |
dot11RSNAconfigSATimeout
|
REG_DWORD
|
|
|
network-001\<Network_SubKey>
|
|
|
|
network-002\<Network_SubKey>
|
|
|
|
......
|
|
|
|
network-n\<Network_SubKey>
|
|
|
|
blob-base64-001
|
REG_BINARY
|
|
|
blob-base64-002
|
REG_BINARY
|
|
|
......
|
......
|
|
|
blob-base64-n
|
REG_BINARY
|
|
|
|
|
|
<Network_SubKey>\
|
disabled
|
REG_DWORD
|
|
|
ssid
|
REG_SZ
|
|
|
bssid
|
REG_SZ
|
|
|
psk
|
REG_SZ
|
|
|
passphrase
|
REG_SZ
|
|
|
pairwise
|
REG_SZ
|
|
|
group
|
REG_SZ
|
| |
key_mgmt
|
REG_SZ
|
| |
proto
|
REG_SZ
|
| |
auth_alg
|
REG_SZ
|
| |
scan_ssid
|
REG_DWORD
|
| |
identity
|
REG_SZ
|
| |
anonymous_identity
|
REG_SZ
|
| |
eap
|
REG_SZ
|
|
|
eappsk
|
REG_SZ
|
|
|
nai
|
REG_SZ
|
|
|
password
|
REG_SZ
|
|
|
ca_cert
|
REG_SZ
|
| |
client_cert
|
REG_SZ
|
| |
private_key
|
REG_SZ
|
| |
private_key_passwd
|
REG_SZ
|
| |
dh_file
|
REG_SZ
|
| |
subject_match
|
REG_SZ
|
| |
altsubject_match
|
REG_SZ
|
| |
ca_cert2
|
REG_SZ
|
|
|
client_cert2
|
REG_SZ
|
| |
private_key2
|
REG_SZ
|
| |
private_key2_passwd
|
REG_SZ
|
| |
dh_file2
|
REG_SZ
|
| |
subject_match2
|
REG_SZ
|
| |
altsubject_match2
|
REG_SZ
|
| |
phase1
|
REG_SZ
|
| |
phase2
|
REG_SZ
|
| |
pcsc
|
REG_SZ
|
| |
pin
|
REG_SZ
|
| |
engine
|
REG_DWORD
|
| |
engine_id
|
REG_SZ
|
| |
key_id
|
REG_SZ
|
| |
eapol_flags
|
REG_DWORD
|
| |
wep_key0
|
REG_SZ
|
| |
wep_key1
|
REG_SZ
|
| |
wep_key2
|
REG_SZ
|
| |
wep_key3
|
REG_SZ
|
| |
wep_tx_keyidx
|
REG_DWORD
|
| |
proactive_key_caching
|
REG_DWORD
|
| |
mixed_cell
|
REG_DWORD
|
| |
beacon_int
|
REG_DWORD
|
| |
channel
|
REG_DWORD
|
| |
eap_workaround
|
REG_DWORD
|
| |
pac_file
|
REG_SZ
|
| |
mode
|
REG_DWORD
|
Example Runtime Configuration and Usage
Example Configurations (wpa_supplicant.conf)
DSA Supplicant is configured using a text file that lists all accepted networks and security policies, including pre-shared keys. See example configuration file, wpa_supplicant.conf, for detailed information about the configuration format and supported fields.
Changes to the configuration file can be reloaded by sending SIGHUP signal to wpa_supplicant
(killall -HUP wpa_supplicant). Similarly, reloading can be triggered with wpa_cli reconfigure command.
The configuration file can include one or more network blocks; for example, one for each used SSID. DSA Supplicant will automatically select the best network based on the order of network blocks in the configuration file, network security level (WPA/WPA2 is preferred), and signal strength.
The following section shows example configuration files for some common configurations:
|
Note
|
If you start/run the DSA Supplicant in the background, it will change its working directory to the root directory. If you are referring to certificate and private key files with relative pathnames based on the starting directory, wpa_supplicant may not be able to find these files after having moved to another directory. To avoid this problem, be sure to use absolute pathnames when specifying these files in the wpa_supplicant.conf file.
|
Example 1: WPA-Personal (PSK) Home
This example configuration file sets up a WPA-Personal (PSK) as a Home Network.
# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
# ctrl_interface=/var/run/wpa_supplicant
# ctrl_interface_group=wheel
# home network; allow all valid ciphers
psk="very secret passphrase"
Example 2: WPA-Enterprise with EAP-TLS Network
This example configuration file sets up a WPA-Enterprise with EAP-TLS.
# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
identity="user@example.com"
ca_cert="/etc/cert/ca.pem"
client_cert="/etc/cert/user.pem"
private_key="/etc/cert/user.prv"
private_key_passwd="password"
Example 3: WPA-Enterprise with EAP-PEAP/MSCHAPv2
This example configuration file sets up EAP-PEAP/MSCHAPv2 with RADIUS servers.
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
identity="user@example.com"
ca_cert="/etc/cert/ca.pem"
Example 4: EAP-TTLS/EAP-MD5-Challenge
This example configuration file sets up an EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the unencrypted use. The real identity is sent only within an encrypted TLS tunnel.
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
identity="user@example.com"
anonymous_identity="anonymous@example.com"
ca_cert="/etc/cert/ca.pem"
Example 5: IEEE 802.1X with Dynamic WEP Keys and EAP-TLS Authentication
This example configuration file sets up IEEE 802.1X (not WPA) with dynamic WEP keys (both unicast and broadcast required). EAP-TLS is used for authentication.
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
identity="user@example.com"
ca_cert="/etc/cert/ca.pem"
client_cert="/etc/cert/user.pem"
private_key="/etc/cert/user.prv"
private_key_passwd="password"
Example 6: Allow All Configuration Modes (for Testing Only)
The following is a "catch-all" example that allows (more or less) all configuration modes. The configuration options are used based on what security policy is used in the selected SSID. This is mostly for testing and is not recommended for normal use.
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
group=CCMP TKIP WEP104 WEP40
psk="very secret passphrase"
identity="user@example.com"
ca_cert="/etc/cert/ca.pem"
client_cert="/etc/cert/user.pem"
private_key="/etc/cert/user.prv"
private_key_passwd="password"
ca_cert2="/etc/cert/ca2.pem"
client_cert2="/etc/cer/user.pem"
private_key2="/etc/cer/user.prv"
private_key2_passwd="password"
Using Certificates
Some EAP authentication methods require use of certificates. EAP-TLS uses both server side and client certificates whereas EAP-PEAP and EAP-TTLS only require the server side certificate. When a client certificate is used, a matching private key file has to also be included in configuration. If the private key is entered in encrypted form and requires a password, this has to be configured in wpa_supplicant.conf (private_key_passwd).
You can use the same configuration for certificates which are in separate files, or you can use the Windows certificate store for private key and client certificate. (This will set the private_key registry entry shown in Defining Windows Registry Keys for DSA Supplicant Runtime Configuration.)
Configuration options for private_key formats are provided in wpa_supplicant.conf in the DSA Supplicant source package. The private_key provides the file path to the wireless client private key file (PEM/DER/PFX).
To use a private key configuration, edit the your runtime DSA Supplicant configuration file to include the private_key format(s) you want to use. (You can cut-and-paste the private_key entry in wpa_supplicant.conf and uncomment the settings you want to use.)
When PKCS#12/PFX file (.p12/.pfx) is used, client_cert should be commented out. Both the private key and certificate will be read from the PKCS#12 file in this case. Use the full pathname since the working directory may change when wpa_supplicant is run in the background.
The Windows certificate store can be used by commenting out client_cert and configuring private_key in one of the following formats:
cert://substring_to_matchhash://certificate_thumbprint_in_hex
For example: private_key="hash://63093aa9c47f56ae88334c7b65a4"
Alternatively, a named configuration blob can be used by setting this to blob://<blob name>.
For more information on defining the Windows registry keys, see Defining Windows Registry Keys for DSA Supplicant Runtime Configuration.
For more information on the DSA Supplicant runtime configuration file and options, see Example Configurations (wpa_supplicant.conf).
Options that Must be Configured in the WLAN Driver
Most options for client mode are set in wpa_supplicant.conf for all drivers. However, options for configuring the following features are not currently available in wpa_supplicant.conf because they are outside the scope of wireless security. These features must be configured in the driver:
- Wi-Fi Multimedia Extensions (WMM)
- Wireless Monitor Mode (sniffer)
- Country/Regulatory Domain
Sample GUI Interface Implementation
DSA Supplicant provides a socket-based UDP interface to a GUI. For a more detailed description of the commands available with this interface, see http://www.devicescape.com/docs/dsa/doxygen/html/ctrl_iface_page.html, in the API documentation.
The following steps are an example of a socket based UDP interface implementation.
- First you need to open the control connection.
struct wpa_ctrl *monitor_conn;
struct wpa_ctrl *ctrl_conn;
int openCtrlConnection(char *ifname)
- You should close all other active connections.
wpa_ctrl_close ( ctrl_conn );
wpa_ctrl_detach ( monitor_conn );
wpa_ctrl_close ( monitor_conn );
- Re-open connections
ctrl_conn = wpa_ctrl_open ("");
monitor_conn = wpa_ctrl_open("");
if (monitor_conn == NULL)
wpa_ctrl_close( ctrl_conn );
if ( wpa_ctrl_attach ( monitor_conn ) )
m_strStatus = "Attach Failed";
wpa_ctrl_close ( monitor_conn );
wpa_ctrl_close ( ctrl_conn );
- This is a thread to catch unsolicited messages
CreateThread(0, 0, (LPTHREAD_START_ROUTINE) recv1, (LPVOID)this, 0,
&IDThread);
Now commands can be sent via this ctrlRequest function:
If the return value is 0, i.e.successful, the reply in buf can still say "FAIL", or "UNKNOWN COMMAND"
int ctrlRequest(const char *cmd, char *buf, size_t *buflen)
ret = wpa_ctrl_request(ctrl_conn, cmd, strlen(cmd), buf, buflen,
printf("'%s' command timed out.\n", cmd);
printf("'%s' command failed.\n", cmd);
This is a callback for unsolicited messages. Unsolicited messages are asynchronous messages that the supplicant sends without provocation, i.e. authentication request for username password/passphrase, status messages etc.
void wpa_gui_msg_cb(char *msg, size_t)
printf("message: %s\n", msg);
