libeap/doc/testing_tools.doxygen

   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
   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
 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
 121 The test programs are collected in the tests subdirectory. All
 122 automated unit tests can be run with
 123
 124 \verbatim
 125 make run-tests
 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
 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
 201 */