]>
Commit | Line | Data |
---|---|---|
30c28971 JM |
1 | /** |
2 | \page testing_tools Testing and development tools | |
3 | ||
4 | [ \ref eapol_test "eapol_test" | | |
5 | \ref preauth_test "preauth_test" | | |
3e82a2ed JM |
6 | \ref unit_tests "Unit tests" | |
7 | \ref wpa_trace "Tracing code" ] | |
30c28971 JM |
8 | |
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. | |
13 | ||
14 | \section eapol_test eapol_test - EAP peer and RADIUS client testing | |
15 | ||
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. | |
25 | ||
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. | |
35 | ||
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 | |
40 | compile the tool: | |
41 | ||
42 | \verbatim | |
43 | make eapol_test | |
44 | \endverbatim | |
45 | ||
46 | The resulting eapol_test binary has following command like options: | |
47 | ||
48 | \verbatim | |
49 | usage: | |
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>] | |
53 | eapol_test scard | |
54 | eapol_test sim <PIN> <num triplets> [debug] | |
55 | ||
56 | options: | |
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 | ||
72 | As an example, | |
73 | \verbatim | |
74 | eapol_test -ctest.conf -a127.0.0.1 -p1812 -ssecret -r1 | |
75 | \endverbatim | |
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. | |
81 | ||
82 | ||
83 | \section preauth_test preauth_test - WPA2 pre-authentication and EAP peer testing | |
84 | ||
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 | |
90 | access point. | |
91 | ||
92 | preauth_test is built with: | |
93 | ||
94 | \verbatim | |
95 | make preauth_test | |
96 | \endverbatim | |
97 | ||
98 | and it uses following command line arguments: | |
99 | ||
100 | \verbatim | |
101 | usage: preauth_test <conf> <target MAC address> <ifname> | |
102 | \endverbatim | |
103 | ||
104 | For example, | |
105 | \verbatim | |
106 | preauth_test test.conf 02:11:22:33:44:55 eth0 | |
107 | \endverbatim | |
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. | |
111 | ||
112 | ||
30c28971 JM |
113 | \section unit_tests Unit tests |
114 | ||
115 | Number of the components (.c files) used in %wpa_supplicant define | |
116 | their own unit tests for automated validation of the basic | |
117 | functionality. Most of the tests for cryptographic algorithms are | |
118 | using standard test vectors to validate functionality. These tests can | |
119 | be useful especially when verifying port to a new CPU target. | |
120 | ||
bf5d6fc3 JM |
121 | The test programs are collected in the tests subdirectory. All |
122 | automated unit tests can be run with | |
30c28971 JM |
123 | |
124 | \verbatim | |
bf5d6fc3 | 125 | make run-tests |
30c28971 JM |
126 | \endverbatim |
127 | ||
128 | This make target builds and runs each test and terminates with zero | |
129 | exit code if all tests were completed successfully. | |
130 | ||
3e82a2ed JM |
131 | |
132 | \section wpa_trace Tracing code for developer debuggin | |
133 | ||
134 | %wpa_supplicant and hostapd can be built with tracing code that will | |
135 | track and analyze memory allocations and other resource registrations | |
136 | and certain API uses. If incorrect use is detected, a backtrace of the | |
137 | call location (and/or allocation location) is shown. This can also be | |
138 | used to detect certain categories of memory leaks and report them | |
139 | automatically when the program is terminated. The report will also | |
140 | include information about forgotten eloop events. | |
141 | ||
142 | The trace code can be enabled with CONFIG_WPA_TRACE=y build | |
143 | option. More verbose backtrace information can be generated if libbfd | |
144 | is available and the binaries are not stripped of symbol | |
145 | information. This is enabled with CONFIG_WPA_TRACE_BFD=y. | |
146 | ||
147 | For example, a memory leak (forgotten os_free() call) would show up | |
148 | like this when the program is terminated: | |
149 | ||
150 | \verbatim | |
151 | MEMLEAK[0x82d200]: len 128 | |
152 | WPA_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 | |
161 | WPA_TRACE: memleak - END | |
162 | MEMLEAK: total 128 bytes | |
163 | \endverbatim | |
164 | ||
165 | Another type of error that can be detected is freeing of memory area | |
166 | that was registered for some use and is still be referenced: | |
167 | ||
168 | \verbatim | |
169 | WPA_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 | |
178 | WPA_TRACE: Freeing referenced memory - END | |
179 | WPA_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 | |
193 | WPA_TRACE: Reference registration - END | |
194 | Aborted | |
195 | \endverbatim | |
196 | ||
197 | This type of error results in showing backtraces for both the location | |
198 | where the incorrect freeing happened and the location where the memory | |
199 | area was marked referenced. | |
200 | ||
30c28971 | 201 | */ |