Changeset View
Changeset View
Standalone View
Standalone View
contrib/wpa/doc/testing_tools.doxygen
- This file was added.
/** | |||||
\page testing_tools Testing and development tools | |||||
[ \ref eapol_test "eapol_test" | | |||||
\ref preauth_test "preauth_test" | | |||||
\ref unit_tests "Unit tests" | | |||||
\ref wpa_trace "Tracing code" ] | |||||
wpa_supplicant source tree includes number of testing and development | |||||
tools that make it easier to test the programs without having to setup | |||||
a full test setup with wireless cards. In addition, these tools can be | |||||
used to implement automatic tests suites. | |||||
\section eapol_test eapol_test - EAP peer and RADIUS client testing | |||||
eapol_test is a program that links together the same EAP peer | |||||
implementation that wpa_supplicant is using and the RADIUS | |||||
authentication client code from hostapd. In addition, it has minimal | |||||
glue code to combine these two components in similar ways to IEEE | |||||
802.1X/EAPOL Authenticator state machines. In other words, it | |||||
integrates IEEE 802.1X Authenticator (normally, an access point) and | |||||
IEEE 802.1X Supplicant (normally, a wireless client) together to | |||||
generate a single program that can be used to test EAP methods without | |||||
having to setup an access point and a wireless client. | |||||
The main uses for eapol_test are in interoperability testing of EAP | |||||
methods against RADIUS servers and in development testing for new EAP | |||||
methods. It can be easily used to automate EAP testing for | |||||
interoperability and regression since the program can be run from | |||||
shell scripts without require additional test components apart from a | |||||
RADIUS server. For example, the automated EAP tests described in | |||||
eap_testing.txt are implemented with eapol_test. Similarly, eapol_test | |||||
could be used to implement an automated regression test suite for a | |||||
RADIUS authentication server. | |||||
eapol_test uses the same build time configuration file, .config, as | |||||
wpa_supplicant. This file is used to select which EAP methods are | |||||
included in eapol_test. This program is not built with the default | |||||
Makefile target, so a separate make command needs to be used to | |||||
compile the tool: | |||||
\verbatim | |||||
make eapol_test | |||||
\endverbatim | |||||
The resulting eapol_test binary has following command like options: | |||||
\verbatim | |||||
usage: | |||||
eapol_test [-nWS] -c<conf> [-a<AS IP>] [-p<AS port>] [-s<AS secret>] \ | |||||
[-r<count>] [-t<timeout>] [-C<Connect-Info>] \ | |||||
[-M<client MAC address>] | |||||
eapol_test scard | |||||
eapol_test sim <PIN> <num triplets> [debug] | |||||
options: | |||||
-c<conf> = configuration file | |||||
-a<AS IP> = IP address of the authentication server, default 127.0.0.1 | |||||
-p<AS port> = UDP port of the authentication server, default 1812 | |||||
-s<AS secret> = shared secret with the authentication server, default 'radius' | |||||
-r<count> = number of re-authentications | |||||
-W = wait for a control interface monitor before starting | |||||
-S = save configuration after authentiation | |||||
-n = no MPPE keys expected | |||||
-t<timeout> = sets timeout in seconds (default: 30 s) | |||||
-C<Connect-Info> = RADIUS Connect-Info (default: CONNECT 11Mbps 802.11b) | |||||
-M<client MAC address> = Set own MAC address (Calling-Station-Id, | |||||
default: 02:00:00:00:00:01) | |||||
\endverbatim | |||||
As an example, | |||||
\verbatim | |||||
eapol_test -ctest.conf -a127.0.0.1 -p1812 -ssecret -r1 | |||||
\endverbatim | |||||
tries to complete EAP authentication based on the network | |||||
configuration from test.conf against the RADIUS server running on the | |||||
local host. A re-authentication is triggered to test fast | |||||
re-authentication. The configuration file uses the same format for | |||||
network blocks as wpa_supplicant. | |||||
\section preauth_test preauth_test - WPA2 pre-authentication and EAP peer testing | |||||
preauth_test is similar to eapol_test in the sense that in combines | |||||
EAP peer implementation with something else, in this case, with WPA2 | |||||
pre-authentication. This tool can be used to test pre-authentication | |||||
based on the code that wpa_supplicant is using. As such, it tests | |||||
both the wpa_supplicant implementation and the functionality of an | |||||
access point. | |||||
preauth_test is built with: | |||||
\verbatim | |||||
make preauth_test | |||||
\endverbatim | |||||
and it uses following command line arguments: | |||||
\verbatim | |||||
usage: preauth_test <conf> <target MAC address> <ifname> | |||||
\endverbatim | |||||
For example, | |||||
\verbatim | |||||
preauth_test test.conf 02:11:22:33:44:55 eth0 | |||||
\endverbatim | |||||
would use network configuration from test.conf to try to complete | |||||
pre-authentication with AP using BSSID 02:11:22:33:44:55. The | |||||
pre-authentication packets would be sent using the eth0 interface. | |||||
\section unit_tests Unit tests | |||||
Number of the components (.c files) used in wpa_supplicant define | |||||
their own unit tests for automated validation of the basic | |||||
functionality. Most of the tests for cryptographic algorithms are | |||||
using standard test vectors to validate functionality. These tests can | |||||
be useful especially when verifying port to a new CPU target. | |||||
The test programs are collected in the tests subdirectory. All | |||||
automated unit tests can be run with | |||||
\verbatim | |||||
make run-tests | |||||
\endverbatim | |||||
This make target builds and runs each test and terminates with zero | |||||
exit code if all tests were completed successfully. | |||||
\section wpa_trace Tracing code for developer debuggin | |||||
wpa_supplicant and hostapd can be built with tracing code that will | |||||
track and analyze memory allocations and other resource registrations | |||||
and certain API uses. If incorrect use is detected, a backtrace of the | |||||
call location (and/or allocation location) is shown. This can also be | |||||
used to detect certain categories of memory leaks and report them | |||||
automatically when the program is terminated. The report will also | |||||
include information about forgotten eloop events. | |||||
The trace code can be enabled with CONFIG_WPA_TRACE=y build | |||||
option. More verbose backtrace information can be generated if libbfd | |||||
is available and the binaries are not stripped of symbol | |||||
information. This is enabled with CONFIG_WPA_TRACE_BFD=y. | |||||
For example, a memory leak (forgotten os_free() call) would show up | |||||
like this when the program is terminated: | |||||
\verbatim | |||||
MEMLEAK[0x82d200]: len 128 | |||||
WPA_TRACE: memleak - START | |||||
[0]: ./wpa_supplicant(os_malloc+0x59) [0x41a5e9] | |||||
os_malloc() ../src/utils/os_unix.c:359 | |||||
[1]: ./wpa_supplicant(os_zalloc+0x16) [0x41a676] | |||||
os_zalloc() ../src/utils/os_unix.c:418 | |||||
[2]: ./wpa_supplicant(wpa_supplicant_init+0x38) [0x48b508] | |||||
wpa_supplicant_init() wpa_supplicant.c:2315 | |||||
[3]: ./wpa_supplicant(main+0x2f3) [0x491073] | |||||
main() main.c:252 | |||||
WPA_TRACE: memleak - END | |||||
MEMLEAK: total 128 bytes | |||||
\endverbatim | |||||
Another type of error that can be detected is freeing of memory area | |||||
that was registered for some use and is still be referenced: | |||||
\verbatim | |||||
WPA_TRACE: Freeing referenced memory - START | |||||
[2]: ./wpa_supplicant(os_free+0x5c) [0x41a53c] | |||||
os_free() ../src/utils/os_unix.c:411 | |||||
[3]: ./wpa_supplicant(wpa_supplicant_remove_iface+0x30) [0x48b380] | |||||
wpa_supplicant_remove_iface() wpa_supplicant.c:2259 | |||||
[4]: ./wpa_supplicant(wpa_supplicant_deinit+0x20) [0x48b3e0] | |||||
wpa_supplicant_deinit() wpa_supplicant.c:2430 | |||||
[5]: ./wpa_supplicant(main+0x357) [0x4910d7] | |||||
main() main.c:276 | |||||
WPA_TRACE: Freeing referenced memory - END | |||||
WPA_TRACE: Reference registration - START | |||||
[1]: ./wpa_supplicant [0x41c040] | |||||
eloop_trace_sock_add_ref() ../src/utils/eloop.c:94 | |||||
[2]: ./wpa_supplicant(wpa_supplicant_ctrl_iface_deinit+0x17) [0x473247] | |||||
wpa_supplicant_ctrl_iface_deinit() ctrl_iface_unix.c:436 | |||||
[3]: ./wpa_supplicant [0x48b21c] | |||||
wpa_supplicant_cleanup() wpa_supplicant.c:378 | |||||
wpa_supplicant_deinit_iface() wpa_supplicant.c:2155 | |||||
[4]: ./wpa_supplicant(wpa_supplicant_remove_iface+0x30) [0x48b380] | |||||
wpa_supplicant_remove_iface() wpa_supplicant.c:2259 | |||||
[5]: ./wpa_supplicant(wpa_supplicant_deinit+0x20) [0x48b3e0] | |||||
wpa_supplicant_deinit() wpa_supplicant.c:2430 | |||||
[6]: ./wpa_supplicant(main+0x357) [0x4910d7] | |||||
main() main.c:276 | |||||
WPA_TRACE: Reference registration - END | |||||
Aborted | |||||
\endverbatim | |||||
This type of error results in showing backtraces for both the location | |||||
where the incorrect freeing happened and the location where the memory | |||||
area was marked referenced. | |||||
*/ |