5eb513c3ba
The way autolink support is implementing in Doxygen is a bit inconvenient with wpa_supplicant being recognized as something that would always be linked to struct wpa_supplicant. In addition, number of links were not really noticed automatically. To get this working more robustly and without having to use the %wpa_supplicant workaround (which had its own issues, e.g., with titles), disable autolinking and use explicit \ref commands instead. This is also updating some of the obsolete notes to point to correct file names, etc. changes in the source code tree. Signed-off-by: Jouni Malinen <j@w1.fi>
201 lines
7.7 KiB
Text
201 lines
7.7 KiB
Text
/**
|
|
\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.
|
|
|
|
*/
|