2
\page testing_tools Testing and development tools
4
[ \ref eapol_test "eapol_test" |
5
\ref preauth_test "preauth_test" |
6
\ref driver_test "driver_test" |
7
\ref unit_tests "Unit tests" ]
9
%wpa_supplicant source tree includes number of testing and development
10
tools that make it easier to test the programs without having to setup
11
a full test setup with wireless cards. In addition, these tools can be
12
used to implement automatic tests suites.
14
\section eapol_test eapol_test - EAP peer and RADIUS client testing
16
eapol_test is a program that links together the same EAP peer
17
implementation that %wpa_supplicant is using and the RADIUS
18
authentication client code from hostapd. In addition, it has minimal
19
glue code to combine these two components in similar ways to IEEE
20
802.1X/EAPOL Authenticator state machines. In other words, it
21
integrates IEEE 802.1X Authenticator (normally, an access point) and
22
IEEE 802.1X Supplicant (normally, a wireless client) together to
23
generate a single program that can be used to test EAP methods without
24
having to setup an access point and a wireless client.
26
The main uses for eapol_test are in interoperability testing of EAP
27
methods against RADIUS servers and in development testing for new EAP
28
methods. It can be easily used to automate EAP testing for
29
interoperability and regression since the program can be run from
30
shell scripts without require additional test components apart from a
31
RADIUS server. For example, the automated EAP tests described in
32
eap_testing.txt are implemented with eapol_test. Similarly, eapol_test
33
could be used to implement an automated regression test suite for a
34
RADIUS authentication server.
36
eapol_test uses the same build time configuration file, .config, as
37
%wpa_supplicant. This file is used to select which EAP methods are
38
included in eapol_test. This program is not built with the default
39
Makefile target, so a separate make command needs to be used to
46
The resulting eapol_test binary has following command like options:
50
eapol_test [-nWS] -c<conf> [-a<AS IP>] [-p<AS port>] [-s<AS secret>] \
51
[-r<count>] [-t<timeout>] [-C<Connect-Info>] \
52
[-M<client MAC address>]
54
eapol_test sim <PIN> <num triplets> [debug]
57
-c<conf> = configuration file
58
-a<AS IP> = IP address of the authentication server, default 127.0.0.1
59
-p<AS port> = UDP port of the authentication server, default 1812
60
-s<AS secret> = shared secret with the authentication server, default 'radius'
61
-r<count> = number of re-authentications
62
-W = wait for a control interface monitor before starting
63
-S = save configuration after authentiation
64
-n = no MPPE keys expected
65
-t<timeout> = sets timeout in seconds (default: 30 s)
66
-C<Connect-Info> = RADIUS Connect-Info (default: CONNECT 11Mbps 802.11b)
67
-M<client MAC address> = Set own MAC address (Calling-Station-Id,
68
default: 02:00:00:00:00:01)
74
eapol_test -ctest.conf -a127.0.0.1 -p1812 -ssecret -r1
76
tries to complete EAP authentication based on the network
77
configuration from test.conf against the RADIUS server running on the
78
local host. A re-authentication is triggered to test fast
79
re-authentication. The configuration file uses the same format for
80
network blocks as %wpa_supplicant.
83
\section preauth_test preauth_test - WPA2 pre-authentication and EAP peer testing
85
preauth_test is similar to eapol_test in the sense that in combines
86
EAP peer implementation with something else, in this case, with WPA2
87
pre-authentication. This tool can be used to test pre-authentication
88
based on the code that %wpa_supplicant is using. As such, it tests
89
both the %wpa_supplicant implementation and the functionality of an
92
preauth_test is built with:
98
and it uses following command line arguments:
101
usage: preauth_test <conf> <target MAC address> <ifname>
106
preauth_test test.conf 02:11:22:33:44:55 eth0
108
would use network configuration from test.conf to try to complete
109
pre-authentication with AP using BSSID 02:11:22:33:44:55. The
110
pre-authentication packets would be sent using the eth0 interface.
113
\section driver_test driver_test - driver interface for testing wpa_supplicant
115
%wpa_supplicant was designed to support number of different ways to
116
communicate with a network device driver. This design uses \ref
117
driver_wrapper "driver interface API" and number of driver interface
118
implementations. One of these is driver_test.c, i.e., a test driver
119
interface that is actually not using any drivers. Instead, it provides
120
a mechanism for running %wpa_supplicant without having to have a
121
device driver or wireless LAN hardware for that matter.
123
driver_test can be used to talk directly with hostapd's driver_test
124
component to create a test setup where one or more clients and access
125
points can be tested within one test host and without having to have
126
multiple wireless cards. This makes it easier to test the core code in
127
%wpa_supplicant, and hostapd for that matter. Since driver_test uses
128
the same driver API than any other driver interface implementation,
129
the core code of %wpa_supplicant and hostapd can be tested with the
130
same coverage as one would get when using real wireless cards. The
131
only area that is not tested is the driver interface implementation
134
Having the possibility to use simulated network components makes it
135
much easier to do development testing while adding new features and to
136
reproduce reported bugs. As such, it is often easiest to just do most
137
of the development and bug fixing without using real hardware. Once
138
the driver_test setup has been used to implement a new feature or fix
139
a bug, the end result can be verified with wireless LAN cards. In many
140
cases, this may even be unnecessary, depending on what area the
141
feature/bug is relating to. Of course, changes to driver interfaces
142
will still require use of real hardware.
144
Since multiple components can be run within a single host, testing of
145
complex network configuration, e.g., large number of clients
146
association with an access point, becomes quite easy. All the tests
147
can also be automated without having to resort to complex test setup
148
using remote access to multiple computers.
150
driver_test can be included in the %wpa_supplicant build in the same
151
way as any other driver interface, i.e., by adding the following line
158
When running %wpa_supplicant, the test interface is selected by using
159
\a -Dtest command line argument. The interface name (\a -i argument)
160
can be selected arbitrarily, i.e., it does not need to match with any
161
existing network interface. The interface name is used to generate a
162
MAC address, so when using multiple clients, each should use a
163
different interface, e.g., \a sta1, \a sta2, and so on.
165
%wpa_supplicant and hostapd are configured in the same way as they
166
would be for normal use. Following example shows a simple test setup
169
hostapd is configured with following psk-test.conf configuration file:
176
logger_stdout_level=0
178
dump_file=/tmp/hostapd.dump
180
test_socket=/tmp/Test/ap1
187
wpa_passphrase=12345678
190
and started with following command:
193
hostapd psk-test.conf
196
%wpa_supplicant uses following configuration file:
199
driver_param=test_socket=/tmp/Test/ap1
208
%wpa_supplicant can then be started with following command:
211
wpa_supplicant -Dtest -cpsk-test.conf -ista1 -ddK
214
If run without debug information, i.e., with
217
wpa_supplicant -Dtest -cpsk-test.conf -ista1
220
%wpa_supplicant completes authentication and prints following events:
223
Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
224
Associated with 02:b8:a6:62:08:5a
225
WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
226
CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
229
If test setup is using multiple clients, it is possible to run
230
multiple %wpa_supplicant processes. Alternatively, the support for
231
multiple interfaces can be used with just one process to save some
232
resources on single-CPU systems. For example, following command runs
236
./wpa_supplicant -Dtest -cpsk-test.conf -ista1 \
237
-N -Dtest -cpsk-test.conf -ista2
240
This shows following event log:
243
Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
244
Associated with 02:b8:a6:62:08:5a
245
WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
246
CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
247
Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
248
Associated with 02:b8:a6:62:08:5a
249
WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
250
CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
253
hostapd shows this with following events:
256
ap1: STA 02:b5:64:63:30:63 IEEE 802.11: associated
257
ap1: STA 02:b5:64:63:30:63 WPA: pairwise key handshake completed (WPA)
258
ap1: STA 02:b5:64:63:30:63 WPA: group key handshake completed (WPA)
259
ap1: STA 02:2a:c4:18:5b:f3 IEEE 802.11: associated
260
ap1: STA 02:2a:c4:18:5b:f3 WPA: pairwise key handshake completed (WPA)
261
ap1: STA 02:2a:c4:18:5b:f3 WPA: group key handshake completed (WPA)
264
By default, driver_param is simulating a driver that uses the WPA/RSN
265
IE generated by %wpa_supplicant. Driver-generated IE and AssocInfo
266
events can be tested by adding \a use_associnfo=1 to the \a driver_param
267
line in the configuration file. For example:
270
driver_param=test_socket=/tmp/Test/ap1 use_associnfo=1
274
\section unit_tests Unit tests
276
Number of the components (.c files) used in %wpa_supplicant define
277
their own unit tests for automated validation of the basic
278
functionality. Most of the tests for cryptographic algorithms are
279
using standard test vectors to validate functionality. These tests can
280
be useful especially when verifying port to a new CPU target.
282
In most cases, these tests are implemented in the end of the same file
283
with functions that are normally commented out, but ca be included by
284
defining a pre-processor variable when building the file separately.
285
The details of the needed build options are included in the Makefile
286
(test-* targets). All automated unit tests can be run with
292
This make target builds and runs each test and terminates with zero
293
exit code if all tests were completed successfully.
added
removed
wpa_supplicant/doc/testing_tools.doxygen
