1/**
2\page testing_tools Testing and development tools
3
4[ \ref eapol_test "eapol_test" |
5\ref preauth_test "preauth_test" |
6\ref unit_tests "Unit tests" |
7\ref wpa_trace "Tracing code" ]
8
9wpa_supplicant source tree includes number of testing and development
10tools that make it easier to test the programs without having to setup
11a full test setup with wireless cards. In addition, these tools can be
12used to implement automatic tests suites.
13
14\section eapol_test eapol_test - EAP peer and RADIUS client testing
15
16eapol_test is a program that links together the same EAP peer
17implementation that wpa_supplicant is using and the RADIUS
18authentication client code from hostapd. In addition, it has minimal
19glue code to combine these two components in similar ways to IEEE
20802.1X/EAPOL Authenticator state machines. In other words, it
21integrates IEEE 802.1X Authenticator (normally, an access point) and
22IEEE 802.1X Supplicant (normally, a wireless client) together to
23generate a single program that can be used to test EAP methods without
24having to setup an access point and a wireless client.
25
26The main uses for eapol_test are in interoperability testing of EAP
27methods against RADIUS servers and in development testing for new EAP
28methods. It can be easily used to automate EAP testing for
29interoperability and regression since the program can be run from
30shell scripts without require additional test components apart from a
31RADIUS server. For example, the automated EAP tests described in
32eap_testing.txt are implemented with eapol_test. Similarly, eapol_test
33could be used to implement an automated regression test suite for a
34RADIUS authentication server.
35
36eapol_test uses the same build time configuration file, .config, as
37wpa_supplicant. This file is used to select which EAP methods are
38included in eapol_test. This program is not built with the default
39Makefile target, so a separate make command needs to be used to
40compile the tool:
41
42\verbatim
43make eapol_test
44\endverbatim
45
46The resulting eapol_test binary has following command like options:
47
48\verbatim
49usage:
50eapol_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>]
53eapol_test scard
54eapol_test sim <PIN> <num triplets> [debug]
55
56options:
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)
69\endverbatim
70
71
72As an example,
73\verbatim
74eapol_test -ctest.conf -a127.0.0.1 -p1812 -ssecret -r1
75\endverbatim
76tries to complete EAP authentication based on the network
77configuration from test.conf against the RADIUS server running on the
78local host. A re-authentication is triggered to test fast
79re-authentication. The configuration file uses the same format for
80network blocks as wpa_supplicant.
81
82
83\section preauth_test preauth_test - WPA2 pre-authentication and EAP peer testing
84
85preauth_test is similar to eapol_test in the sense that in combines
86EAP peer implementation with something else, in this case, with WPA2
87pre-authentication. This tool can be used to test pre-authentication
88based on the code that wpa_supplicant is using. As such, it tests
89both the wpa_supplicant implementation and the functionality of an
90access point.
91
92preauth_test is built with:
93
94\verbatim
95make preauth_test
96\endverbatim
97
98and it uses following command line arguments:
99
100\verbatim
101usage: preauth_test <conf> <target MAC address> <ifname>
102\endverbatim
103
104For example,
105\verbatim
106preauth_test test.conf 02:11:22:33:44:55 eth0
107\endverbatim
108would use network configuration from test.conf to try to complete
109pre-authentication with AP using BSSID 02:11:22:33:44:55. The
110pre-authentication packets would be sent using the eth0 interface.
111
112
113\section unit_tests Unit tests
114
115Number of the components (.c files) used in wpa_supplicant define
116their own unit tests for automated validation of the basic
117functionality. Most of the tests for cryptographic algorithms are
118using standard test vectors to validate functionality. These tests can
119be useful especially when verifying port to a new CPU target.
120
121The test programs are collected in the tests subdirectory. All
122automated unit tests can be run with
123
124\verbatim
125make run-tests
126\endverbatim
127
128This make target builds and runs each test and terminates with zero
129exit code if all tests were completed successfully.
130
131
132\section wpa_trace Tracing code for developer debuggin
133
134wpa_supplicant and hostapd can be built with tracing code that will
135track and analyze memory allocations and other resource registrations
136and certain API uses. If incorrect use is detected, a backtrace of the
137call location (and/or allocation location) is shown. This can also be
138used to detect certain categories of memory leaks and report them
139automatically when the program is terminated. The report will also
140include information about forgotten eloop events.
141
142The trace code can be enabled with CONFIG_WPA_TRACE=y build
143option. More verbose backtrace information can be generated if libbfd
144is available and the binaries are not stripped of symbol
145information. This is enabled with CONFIG_WPA_TRACE_BFD=y.
146
147For example, a memory leak (forgotten os_free() call) would show up
148like this when the program is terminated:
149
150\verbatim
151MEMLEAK[0x82d200]: len 128
152WPA_TRACE: memleak - START
153[0]: ./wpa_supplicant(os_malloc+0x59) [0x41a5e9]
154     os_malloc() ../src/utils/os_unix.c:359
155[1]: ./wpa_supplicant(os_zalloc+0x16) [0x41a676]
156     os_zalloc() ../src/utils/os_unix.c:418
157[2]: ./wpa_supplicant(wpa_supplicant_init+0x38) [0x48b508]
158     wpa_supplicant_init() wpa_supplicant.c:2315
159[3]: ./wpa_supplicant(main+0x2f3) [0x491073]
160     main() main.c:252
161WPA_TRACE: memleak - END
162MEMLEAK: total 128 bytes
163\endverbatim
164
165Another type of error that can be detected is freeing of memory area
166that was registered for some use and is still be referenced:
167
168\verbatim
169WPA_TRACE: Freeing referenced memory - START
170[2]: ./wpa_supplicant(os_free+0x5c) [0x41a53c]
171     os_free() ../src/utils/os_unix.c:411
172[3]: ./wpa_supplicant(wpa_supplicant_remove_iface+0x30) [0x48b380]
173     wpa_supplicant_remove_iface() wpa_supplicant.c:2259
174[4]: ./wpa_supplicant(wpa_supplicant_deinit+0x20) [0x48b3e0]
175     wpa_supplicant_deinit() wpa_supplicant.c:2430
176[5]: ./wpa_supplicant(main+0x357) [0x4910d7]
177     main() main.c:276
178WPA_TRACE: Freeing referenced memory - END
179WPA_TRACE: Reference registration - START
180[1]: ./wpa_supplicant [0x41c040]
181     eloop_trace_sock_add_ref() ../src/utils/eloop.c:94
182[2]: ./wpa_supplicant(wpa_supplicant_ctrl_iface_deinit+0x17) [0x473247]
183     wpa_supplicant_ctrl_iface_deinit() ctrl_iface_unix.c:436
184[3]: ./wpa_supplicant [0x48b21c]
185     wpa_supplicant_cleanup() wpa_supplicant.c:378
186     wpa_supplicant_deinit_iface() wpa_supplicant.c:2155
187[4]: ./wpa_supplicant(wpa_supplicant_remove_iface+0x30) [0x48b380]
188     wpa_supplicant_remove_iface() wpa_supplicant.c:2259
189[5]: ./wpa_supplicant(wpa_supplicant_deinit+0x20) [0x48b3e0]
190     wpa_supplicant_deinit() wpa_supplicant.c:2430
191[6]: ./wpa_supplicant(main+0x357) [0x4910d7]
192     main() main.c:276
193WPA_TRACE: Reference registration - END
194Aborted
195\endverbatim
196
197This type of error results in showing backtraces for both the location
198where the incorrect freeing happened and the location where the memory
199area was marked referenced.
200
201*/
202